Skip to content

Version 1.7 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

HugeGraph Toolchain Local Testing Guide

This guide helps developers run HugeGraph toolchain tests locally.

1. Core Concepts

1.1 Core Dependency: HugeGraph Server

Integration and functional tests of the toolchain depend on HugeGraph Server, including Client, Loader, Hubble, Spark Connector, Tools, and other components.

1.2 Test Types

  • Unit Tests: Test individual functions/methods, no external dependencies required
  • API Tests (ApiTestSuite): Test API interfaces, requires running HugeGraph Server
  • Functional Tests (FuncTestSuite): End-to-end tests, require complete system environment

2. Environment Setup

2.1 System Requirements

  • Operating System: Linux / macOS (Windows use WSL2)
  • JDK: >= 11, configure JAVA_HOME
  • Maven: >= 3.6
  • Python: >= 3.11 (only required for Hubble tests)

2.2 Clone Code

1git clone https://github.com/apache/hugegraph-toolchain.git
2cd hugegraph-toolchain

3. Deploy Test Environment

Deployment Options

  • Script Deployment: Specify a Server commit to reproduce the server version used by CI
  • Docker Deployment: Suitable for quick checks; if tests fail, first verify compatibility between the image and Toolchain

For detailed installation instructions, refer to Community Documentation

3.1 Script Deployment

Parameter Description

  • $COMMIT_ID: Specify Server source code Git Commit ID
  • $DB_DATABASE / $DB_PASS: MySQL database name and password for Loader JDBC tests

Deployment Steps

1. Install HugeGraph Server

1# Set the Server baseline; use a full commit SHA for reproducible results
2export COMMIT_ID="master"
3
4# Execute installation (script located in /assembly/travis/ directory)
5hugegraph-client/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID
  • The script starts HTTP and HTTPS instances on ports 8080 and 8443 and configures admin/pa authentication.
  • Ensure both ports are available before running it.

2. Install Optional Dependencies

1# Hadoop (only required for Loader HDFS tests)
2hugegraph-loader/assembly/travis/install-hadoop.sh
3
4# MySQL (only required for Loader JDBC tests)
5hugegraph-loader/assembly/travis/install-mysql.sh $DB_DATABASE $DB_PASS

3. Health Check

1curl -u admin:pa http://localhost:8080/graphspaces/DEFAULT/graphs
2# Returns {"graphs":["hugegraph"]} indicates success

3.2 Docker Deployment

Note: Docker images may have version lag, use script deployment if encountering compatibility issues

Quick Start

1docker network create hugegraph-net
2docker run -itd --name=server -p 8080:8080 --network hugegraph-net hugegraph/hugegraph:latest

docker-compose Configuration (Optional)

Complete configuration example including Server, MySQL, Hadoop services (requires Docker Compose V2):

 1version: '3.8'
 2
 3services:
 4  hugegraph-server:
 5    image: hugegraph/hugegraph:latest  # Can be replaced with a specific version, or build your own image
 6    container_name: hugegraph-server
 7    ports:
 8      - "8080:8080"  # HugeGraph Server HTTP port
 9    environment:
10      # Configure HugeGraph Server parameters as needed, e.g., backend storage
11      - HUGEGRAPH_SERVER_OPTIONS="-Dstore.backend=rocksdb"
12    volumes:
13      # If you need to persist data or mount configuration files, add volumes here
14      # - ./hugegraph-data:/opt/hugegraph/data
15    healthcheck:
16      test: ["CMD-SHELL", "curl -f http://localhost:8080/graphspaces/DEFAULT/graphs || exit 1"]
17      interval: 10s
18      timeout: 3s
19      retries: 5
20    networks:
21      - hugegraph-net
22  
23  # If you need JDBC tests for hugegraph-loader, you can add the following service
24  #   mysql:
25  #     image: mysql:5.7
26  #     container_name: mysql-db
27  #     environment:
28  #       MYSQL_ROOT_PASSWORD: ${DB_PASS:-your_mysql_root_password} # Read from environment variable, or use default
29  #       MYSQL_DATABASE: ${DB_DATABASE:-hugegraph_test_db} # Read from environment variable, or use default
30  #     ports:
31  #       - "3306:3306"
32  #     volumes:
33  #       - ./mysql-data:/var/lib/mysql # Data persistence
34  #     healthcheck:
35  #       test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-p${DB_PASS:-your_mysql_root_password}"]
36  #       interval: 5s
37  #       timeout: 3s
38  #       retries: 5
39  #     networks:
40  #       - hugegraph-net
41
42  # If you need Hadoop/HDFS tests for hugegraph-loader, you can add the following services
43  #   namenode:
44  #     image: johannestang/hadoop-namenode:2.0.0-hadoop2.8.5-java8
45  #     container_name: namenode
46  #     ports:
47  #       - "0.0.0.0:9870:9870"
48  #       - "0.0.0.0:8020:8020"
49  #     environment:
50  #       - CLUSTER_NAME=test-cluster
51  #       - HDFS_NAMENODE_USER=root
52  #       - HADOOP_CONF_DIR=/hadoop/etc/hadoop
53  #     volumes:
54  #       - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml
55  #       - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml
56  #       - namenode_data:/hadoop/dfs/name
57  #     command: bash -c "if [ ! -d /hadoop/dfs/name/current ]; then hdfs namenode -format; fi && /entrypoint.sh"
58  #     healthcheck:
59  #       test: ["CMD", "hdfs", "dfsadmin", "-report"]
60  #       interval: 5s
61  #       timeout: 3s
62  #       retries: 5
63  #     networks:
64  #       - hugegraph-net
65
66  #   datanode:
67  #     image: johannestang/hadoop-datanode:2.0.0-hadoop2.8.5-java8
68  #     container_name: datanode
69  #     depends_on:
70  #       - namenode
71  #     environment:
72  #       - CLUSTER_NAME=test-cluster
73  #       - HDFS_DATANODE_USER=root
74  #       - HADOOP_CONF_DIR=/hadoop/etc/hadoop
75  #     volumes:
76  #       - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml
77  #       - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml
78  #       - datanode_data:/hadoop/dfs/data
79  #     healthcheck:
80  #       test: ["CMD", "hdfs", "dfsadmin", "-report"]
81  #       interval: 5s
82  #       timeout: 3s
83  #       retries: 5
84  #     networks:
85  #       - hugegraph-net
86
87networks:
88  hugegraph-net:
89    driver: bridge
90volumes:
91  namenode_data:
92  datanode_data:

Hadoop Configuration Mounts

Create a ./config folder in the same directory as docker-compose.yml to mount Hadoop configuration files. You can skip this step if HDFS testing is not required.

📁 ./config/core-site.xml content:

1<configuration>
2    <property>
3        <name>fs.defaultFS</name>
4        <value>hdfs://namenode:8020</value>
5    </property>
6</configuration>

📁 ./config/hdfs-site.xml content:

 1<configuration>
 2    <property>
 3        <name>dfs.namenode.name.dir</name>
 4        <value>/hadoop/hdfs/name</value>
 5    </property>
 6    <property>
 7        <name>dfs.datanode.data.dir</name>
 8        <value>/hadoop/hdfs/data</value>
 9    </property>
10    <property>
11        <name>dfs.permissions.superusergroup</name>
12        <value>hadoop</value>
13    </property>
14    <property>
15        <name>dfs.support.append</name>
16        <value>true</value>
17    </property>
18</configuration>

Docker Operations

 1# Start services
 2docker compose up -d
 3
 4# Check status
 5docker compose ps
 6lsof -i:8080  # Server
 7lsof -i:8020  # Hadoop
 8lsof -i:3306  # MySQL
 9
10# Stop services
11docker compose down

4. Run Tests

Test process for each tool:

HugeGraph Toolchain Testing Process

4.1 hugegraph-client

Compile

1mvn -e compile -pl hugegraph-client -Dmaven.javadoc.skip=true -ntp

Dependent Services

Start HugeGraph Server (refer to Section 3)

Server Authentication Configuration

ApiTest requires authentication. No additional configuration is needed when using the script in Section 3.1. For a manually deployed Server, the authentication settings and test credentials must match the test code.

 1# 1. Modify authentication mode
 2cp conf/rest-server.properties conf/rest-server.properties.backup
 3sed -i 's|#auth.authenticator=.*|auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator|' conf/rest-server.properties
 4grep auth.authenticator conf/rest-server.properties
 5sed -i 's|gremlin.graph=org.apache.hugegraph.HugeFactory|gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy|' conf/graphs/hugegraph.properties
 6
 7# 2. Set password
 8# Note: Test code uses "pa" as default password, must match for tests to work
 9bin/stop-hugegraph.sh
10export PASSWORD="pa"  # Set to test default password
11echo -e "${PASSWORD}" | bin/init-store.sh
12bin/start-hugegraph.sh

Run Tests

1# Check environment
2curl -u admin:pa http://localhost:8080/graphspaces/DEFAULT/graphs
3
4# Run tests
5cd hugegraph-client
6mvn test -Dtest=UnitTestSuite -ntp      # Unit tests
7mvn test -Dtest=ApiTestSuite -ntp       # API tests (requires Server)
8mvn test -Dtest=FuncTestSuite -ntp      # Functional tests (requires Server)

Check Server log if tests fail: logs/hugegraph-server.log

4.2 hugegraph-loader

Compile

1mvn install -pl hugegraph-client,hugegraph-loader -am -Dmaven.javadoc.skip=true -DskipTests -ntp

Dependent Services

  • Required: HugeGraph Server
  • Optional: Hadoop (HDFS tests), MySQL (JDBC tests)

Run Tests

1cd hugegraph-loader
2mvn test -P unit -ntp   # Unit tests
3mvn test -P file -ntp   # File tests (requires Server)
4mvn test -P hdfs -ntp   # HDFS tests (requires Server + Hadoop)
5mvn test -P jdbc -ntp   # JDBC tests (requires Server + MySQL)
6mvn test -P kafka -ntp  # Kafka tests (requires Server)

4.3 hugegraph-hubble

Compile

1mvn install -pl hugegraph-client,hugegraph-loader -am -Dmaven.javadoc.skip=true -DskipTests -ntp
2cd hugegraph-hubble
3mvn -e compile -Dmaven.javadoc.skip=true -ntp

Dependent Services

1. Start Server (refer to Section 3)

2. Python Environment

1python -m venv venv
2source venv/bin/activate  # Windows: venv\Scripts\activate
3python -m pip install -r hubble-dist/assembly/travis/requirements.txt

3. Build and Verify

1mvn package -Dmaven.test.skip=true
2# Optional: Start and verify
3cd apache-hugegraph-hubble*/bin
4./start-hubble.sh -d && sleep 10
5curl http://localhost:8088/actuator/health
6./stop-hubble.sh

Run Tests

 1# Unit tests
 2mvn test -P unit-test -pl hugegraph-hubble/hubble-be -ntp
 3
 4# Legacy Python API tests (requires Server; the script installs and starts Hubble)
 5curl -u admin:pa http://localhost:8080/graphspaces/DEFAULT/graphs  # Check Server
 6cd hugegraph-hubble
 7./hubble-dist/assembly/travis/run-api-test.sh
 8
 9# Full verification entry point used by current CI (build the Hubble tarball first)
10HUBBLE_TARBALL="$(ls target/apache-hugegraph-hubble-*.tar.gz | head -n 1)"
11hubble-dist/assembly/travis/verify-hubble-issue-694.sh \
12  "$HUBBLE_TARBALL" http://127.0.0.1:8080

4.4 hugegraph-spark-connector

Compile

1mvn install -pl hugegraph-client,hugegraph-spark-connector -am -Dmaven.javadoc.skip=true -DskipTests -ntp

Run Tests

1cd hugegraph-spark-connector
2mvn test -ntp  # Requires Server running

4.5 hugegraph-tools

Compile

1mvn install -pl hugegraph-client,hugegraph-tools -am -Dmaven.javadoc.skip=true -DskipTests -ntp

Run Tests

1cd hugegraph-tools
2mvn test -Dtest=FuncTestSuite -ntp  # Requires Server running

5. Common Issues

Service Connection Issues

If Server, MySQL, or Hadoop cannot be reached:

  • Confirm services are running (Server must be on port 8080)
  • Check port usage: lsof -i:8080
  • Docker check: docker compose ps and docker compose logs

Configuration Issues

If files cannot be found or parameters are invalid:

  • Check environment variables: echo $COMMIT_ID
  • Script permissions: chmod +x hugegraph-*/assembly/travis/*.sh

HDFS Test Failures

  • Confirm NameNode/DataNode running normally
  • Check Hadoop logs
  • Verify HDFS connection: hdfs dfsadmin -report

JDBC Test Failures

  • Confirm MySQL running normally
  • Verify database connection: mysql -u root -p$DB_PASS
  • Check MySQL logs

6. References

Last modified 2026-09-04 · docs: sync 1.7 documentation (4211f768b)