本地测试文档

Author: root

hugegraph-toolchian-LOCAL_TEST_GUIDE.md

@@ -0,0 +1,232 @@
+# HugeGraph 工具链本地测试指南
+
+本指南帮助开发者高效地在本地环境下运行 HugeGraph 工具链相关测试，涵盖各子项目的编译、依赖服务安装、测试与覆盖率报告生成等流程。
+
+## 0. 变量与环境说明
+
+- **$COMMIT_ID**：指定 HugeGraph Server 版本的 commit id，需提前设置。例如：`export COMMIT_ID=f838897`
+- **$DB_DATABASE / $DB_PASS**：MySQL 数据库名和密码，建议在 shell 中设置环境变量。
+- **如遇脚本权限问题，先执行**：`chmod +x hugegraph-*/assembly/travis/*.sh`
+- **所有测试依赖Server正常运行，请检查相关配置**
+- **HugeGraph-Client 用于连接 HugeGraph-Server，工具链中其他测试均依赖Client**
+
+## 1. 测试前准备
+
+- **操作系统**：建议 Linux, macOS。Windows 平台请使用 WSL2
+- **JDK**：>=11
+- **Maven**：建议 3.5 及以上
+- **Python**：>=3.11（Hubble 相关测试需用）
+
+## 2. 克隆代码仓库
+
+```bash
+git clone https://github.com/${GITHUB_USER_NAME}/hugegraph-toolchain.git
+cd hugegraph-toolchain
+```
+
+## 3. Maven 配置文件设置
+
+如需使用 staged maven 仓库：
+
+```bash
+cp $HOME/.m2/settings.xml /tmp/settings.xml
+mv -vf .github/configs/settings.xml $HOME/.m2/settings.xml
+```
+
+---
+
+## hugegraph-loader 本地测试
+
+### 1. 编译
+
+```bash
+mvn install -pl hugegraph-client,hugegraph-loader -am -Dmaven.javadoc.skip=true -DskipTests -ntp
+```
+
+### 2. 依赖服务安装
+
+```bash
+hugegraph-loader/assembly/travis/install-hadoop.sh
+hugegraph-loader/assembly/travis/install-mysql.sh $DB_DATABASE $DB_PASS
+hugegraph-loader/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID
+```
+> 若已安装 HugeGraph Server，可跳过最后一步install-hugegraph，并确保 http/https 端口（默认 8080/8443）服务已启动。
+
+### 3. 运行测试
+
+```bash
+cd hugegraph-loader
+mvn test -P unit -ntp
+mvn test -P file
+mvn test -P hdfs
+mvn test -P jdbc
+mvn test -P kafka
+```
+
+*请在hdfs测试运行中确保hadoop的datanode正常进行，确保数据正常操作*
+
+### 4. 生成覆盖率报告
+
+```bash
+mvn clean test jacoco:report
+# 用浏览器打开 target/site/jacoco/index.html 查看详细覆盖率
+```
+
+---
+
+## hugegraph-hubble 本地测试
+
+> 需 Python >=3.11，建议使用虚拟环境：
+> ```bash
+> python3.11 -m venv venv && source venv/bin/activate
+> ```
+
+### 1. 编译
+
+```bash
+mvn install -pl hugegraph-client,hugegraph-loader -am -Dmaven.javadoc.skip=true -DskipTests -ntp
+cd hugegraph-hubble
+mvn -e compile -Dmaven.javadoc.skip=true -ntp
+```
+
+### 2. 依赖服务安装
+
+```bash
+python -m pip install -r hubble-dist/assembly/travis/requirements.txt
+mvn package -Dmaven.test.skip=true
+cd apache-hugegraph-hubble-incubating*/bin
+./start-hubble.sh -d
+./stop-hubble.sh
+cd ../../../
+hubble-dist/assembly/travis/install-hugegraph.sh $COMMIT_ID
+```
+> 若已安装 HugeGraph Server，可跳过最后一步install-hugegraph，并确保 http/https 端口（默认 8080/8443）服务已启动。
+
+### 3. 运行测试
+
+```bash
+cd hugegraph-hubble
+mvn test -P unit-test -pl hugegraph-hubble/hubble-be -ntp
+hubble-dist/assembly/travis/run-api-test.sh
+```
+
+### 4. 生成覆盖率报告
+
+```bash
+mvn clean test jacoco:report
+# 用浏览器打开 target/site/jacoco/index.html 查看详细覆盖率
+```
+
+---
+
+## hugegraph-client 本地测试（Java 版本）
+
+### 1. 编译
+
+```bash
+mvn -e compile -pl hugegraph-client -Dmaven.javadoc.skip=true -ntp
+```
+
+### 2. 依赖服务安装
+
+```bash
+hugegraph-client/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID
+```
+> 若已安装 HugeGraph Server，可跳过，并确保 http/https 端口（默认 8080/8443）服务已启动。
+
+### 3. 运行测试
+
+```bash
+cd hugegraph-client
+mvn test -Dtest=UnitTestSuite -ntp
+mvn test -Dtest=ApiTestSuite
+mvn test -Dtest=FuncTestSuite
+```
+
+### 4. 生成覆盖率报告
+
+```bash
+mvn clean test jacoco:report
+# 用浏览器打开 target/site/jacoco/index.html 查看详细覆盖率
+```
+
+---
+
+## hugegraph-spark-connector 本地测试
+
+### 1. 编译
+
+```bash
+mvn install -pl hugegraph-client,hugegraph-spark-connector -am -Dmaven.javadoc.skip=true -DskipTests -ntp
+```
+
+### 2. 依赖服务安装
+
+```bash
+hugegraph-spark-connector/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID
+```
+> 若已安装 HugeGraph Server，可跳过，并确保 http/https 端口（默认 8080/8443）服务已启动。
+
+
+### 3. 运行测试
+
+```bash
+cd hugegraph-spark-connector
+mvn test
+```
+
+### 4. 生成覆盖率报告
+
+```bash
+mvn clean test jacoco:report
+# 用浏览器打开 target/site/jacoco/index.html 查看详细覆盖率
+```
+
+---
+
+## hugegraph-tools 本地测试
+
+### 1. 编译
+
+```bash
+mvn install -pl hugegraph-client,hugegraph-tools -am -Dmaven.javadoc.skip=true -DskipTests -ntp
+```
+
+### 2. 依赖服务安装
+
+```bash
+hugegraph-tools/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID
+```
+> 若已安装 HugeGraph Server，可跳过，并确保 http/https 端口（默认 8080/8443）服务已启动。
+
+
+### 3. 运行测试
+
+```bash
+cd hugegraph-tools
+mvn test -Dtest=FuncTestSuite -pl hugegraph-tools -ntp
+```
+
+### 4. 生成覆盖率报告
+
+```bash
+mvn clean test jacoco:report
+# 用浏览器打开 target/site/jacoco/index.html 查看详细覆盖率
+```
+
+---
+
+## 常见问题与 FAQ
+
+- 确认所有依赖服务已启动且端口无冲突
+- 检查数据库、Hadoop、HugeGraph Server 日志
+- 如遇依赖包下载慢，可配置国内 Maven 源
+- 如遇端口占用、服务未启动等问题，可通过 `lsof -i:端口号` 或 `ps aux | grep hugegraph` 排查
+- 常见报错可参考 CI 日志或 issue 区
+
+---
+
+## 参考
+
+- CI 脚本路径：`.github/workflows/*-ci.yml`
+- 依赖服务安装脚本：`hugegraph-*/assembly/travis/`