imbajin commented on code in PR #412: URL: https://github.com/apache/incubator-hugegraph-doc/pull/412#discussion_r2444639394
########## content/cn/docs/guides/toolchain-local-test.md: ########## @@ -0,0 +1,523 @@ +--- +title: "HugeGraph工具链本地测试指南" +linkTitle: "Toolchain本地测试" +weight: 7 +--- + +本指南旨在帮助开发者高效地在本地环境下运行 HugeGraph 工具链相关测试，涵盖各子项目的编译、依赖服务安装、测试与覆盖率报告生成等流程。 + +## 1. 前言与核心概念 + +### 1.1 核心依赖说明：HugeGraph Server + +在 HugeGraph 工具链的测试中，**HugeGraph Server 是绝大多数集成测试和功能测试的核心依赖**。它提供了图数据库的核心服务，工具链中的许多组件（如 Client、Loader、Hubble、Spark Connector、Tools）都需要与 Server 进行交互才能完成其功能并进行测试。因此，配置好 HugeGraph Server 正常运行是完整进行功能测试的前提，本指南将在下文介绍如何安装/构建HugeGraph Server。 + +### 1.2 测试套件类型解释 + +在 HugeGraph 工具链的测试中，您可能会遇到以下几种常见的测试套件类型： + +* **单元测试 (Unit Tests)**： + * **目标**：验证程序中最小可测试单元（通常是单个函数、方法或类）的正确性。通常不涉及外部依赖（如数据库、网络服务等） + +* **API 测试 (API Tests / ApiTestSuite)**： + * **目标**：验证程序对外提供API的正确性、稳定性和符合性。它们通常模拟客户端请求，与server进行交互，检查 API 的响应数据、处理机制是否符合预期。 + * **特点**：需要一个正在运行的服务端（如 HugeGraph Server）来响应 API 请求。 + + +* **功能测试 (Functional Tests / FuncTestSuite)**： + * **目标**：验证系统或组件的特定功能是否按照需求正常工作。用于模拟用户场景或业务流程，涉及多个组件的交互，是端到端的测试。 + * **特点**：执行时间相对较长，需要完整的系统环境（包括所有依赖服务）来运行，能够发现集成层面的问题。 + +## 2. 测试前准备 + +### 2.1 系统与软件要求 + +* **操作系统**：建议 Linux, macOS。Windows 平台请使用 WSL2。 +* **JDK**：>= 11。确保您的 `JAVA_HOME` 环境变量已正确配置。 +* **Maven**：建议 3.5 及以上。用于项目构建和依赖管理。 +* **Python**：>= 3.11（仅HugeGraph-Hubble 相关测试需用）。建议使用虚拟环境进行管理，以避免版本冲突。 + +### 2.2 克隆代码仓库 + +首先，您需要克隆 HugeGraph 工具链的源代码仓库： + +```bash +git clone https://github.com/${GITHUB_USER_NAME}/hugegraph-toolchain.git +cd hugegraph-toolchain +``` + +## 3. 部署测试环境 + +关于测试环境，由于HugeGraph Server 是绝大多数集成测试和功能测试的核心依赖，有关安装/构建 HugeGraph-Server，可参考访问 [社区版文档](https://hugegraph.apache.org/cn/docs/quickstart/hugegraph/hugegraph-server/)。在本测试指南中，我们会介绍通过脚本部署与通过docker部署两种方式。 + +重要提示： +* 推荐优先使用脚本进行本地部署 HugeGraph Server。 这种方式允许您通过指定 Git Commit ID 来精确控制 Server 版本，确保与您的工具链代码版本高度匹配，从而有效避免因接口或实现变动导致测试异常的问题。 + +* Docker 部署方式更适合快速启动一个默认配置的 HugeGraph Server，但在进行精细化的集成测试时，特别是当您的工具链代码依赖于特定 HugeGraph Server 版本的功能或修复时，Docker 镜像的版本滞后或默认配置可能导致测试不通过。当工具链代码与 HugeGraph Server 存在接口/实现变动时，Docker 部署的便捷性可能反而导致测试失败，此时推荐回退到脚本部署方式。 + +### 3.1 使用脚本快速部署测试环境（推荐） + +这种方式允许您从源代码编译和安装特定版本的 HugeGraph Server，确保测试环境与特定 HugeGraph Server 版本的一致性，这对于复现问题或验证兼容性至关重要。 + +#### 3.1.1 变量与参数 + +* **`$COMMIT_ID`** + * 指定 HugeGraph Server 源代码的 Git Commit ID。当您需要从源代码编译和安装特定版本的 HugeGraph Server 作为测试依赖时，会使用此变量,确保测试环境与特定 HugeGraph Server 版本的一致性，这对于复现问题或验证兼容性至关重要。使用时直接接作为参数传递给 install-hugegraph-from-source.sh 脚本。 + +* **`$DB_DATABASE` 与 `$DB_PASS`** + 指定 HugeGraph-Loader 进行 JDBC 测试时所连接的 MySQL 数据库名称与 root 用户密码。请作为参数传递给 `install-mysql.sh` 脚本，供 Loader 正常读写数据。 + +#### 3.1.2 执行流程 + +**安装并启动 HugeGraph Server** + +如果您选择手动安装，可以使用以下脚本来安装 HugeGraph Server。该脚本位于任意工具仓库的`/assembly/travis/` 目录下 +用于从指定 commit id 拉取 HugeGraph Server 源码、编译、解压并分别以 http/https 启动服务 +```bash +hugegraph-*/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID +``` + +* `$COMMIT_ID`：指定 HugeGraph Server 的 Git Commit ID。 +* 默认http占用端口为8080，https占用端口为8443，请确保其在server启动前未被占用。 + +**安装并启动Hadoop (HDFS)** (仅当运行 hugegraph-loader的HDFS 测试时需要)： +```bash +hugegraph-loader/assembly/travis/install-hadoop.sh +``` + +**安装并启动MySQL** (仅当运行 hugegraph-loader的JDBC 测试时需要)： +```bash +hugegraph-loader/assembly/travis/install-mysql.sh $DB_DATABASE $DB_PASS +``` + + +**健康性检查** + +```bash +curl http://localhost:8080/graphs +``` +若返回 `{"graphs":["hugegraph"]}`，则表示服务器已准备就绪，可以接收请求。 + +### 3.2 使用 Docker 部署测试环境 + +通过使用官方发布的 hugegraph-server Docker 镜像，您可以快速启动一个 HugeGraph Server。这种方式简化了测试环境的搭建、确保环境一致性并提高测试的可重复性。**然而，请注意，Docker 镜像可能不会及时更新到 HugeGraph Server 的最新开发版本。这意味着如果您的工具链代码依赖于 HugeGraph Server 的最新接口或功能，使用 Docker 镜像可能会导致兼容性问题。在这种情况下，建议使用脚本方式部署特定 `COMMIT_ID` 的 HugeGraph Server。** + +#### docker快速启动 + +```bash +docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph:latest Review Comment: **Docker命令缺少网络配置**: 快速启动命令未配置网络,可能导致容器间通信问题。 **当前命令**: ```bash docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph:latest ``` **问题**: 如果后续需要启动MySQL或Hadoop容器与Server通信,它们无法相互访问(不在同一网络) **建议改进**: ```bash # 1. 先创建网络 docker network create hugegraph-net # 2. 启动server并加入网络 docker run -itd --name=server -p 8080:8080 --network hugegraph-net hugegraph/hugegraph:latest ``` 或直接推荐使用后续的 `docker-compose.yml` 方式。 ########## content/cn/docs/guides/toolchain-local-test.md: ########## @@ -0,0 +1,523 @@ +--- +title: "HugeGraph工具链本地测试指南" +linkTitle: "Toolchain本地测试" +weight: 7 +--- + +本指南旨在帮助开发者高效地在本地环境下运行 HugeGraph 工具链相关测试，涵盖各子项目的编译、依赖服务安装、测试与覆盖率报告生成等流程。 + +## 1. 前言与核心概念 + +### 1.1 核心依赖说明：HugeGraph Server + +在 HugeGraph 工具链的测试中，**HugeGraph Server 是绝大多数集成测试和功能测试的核心依赖**。它提供了图数据库的核心服务，工具链中的许多组件（如 Client、Loader、Hubble、Spark Connector、Tools）都需要与 Server 进行交互才能完成其功能并进行测试。因此，配置好 HugeGraph Server 正常运行是完整进行功能测试的前提，本指南将在下文介绍如何安装/构建HugeGraph Server。 + +### 1.2 测试套件类型解释 + +在 HugeGraph 工具链的测试中，您可能会遇到以下几种常见的测试套件类型： + +* **单元测试 (Unit Tests)**： + * **目标**：验证程序中最小可测试单元（通常是单个函数、方法或类）的正确性。通常不涉及外部依赖（如数据库、网络服务等） + +* **API 测试 (API Tests / ApiTestSuite)**： + * **目标**：验证程序对外提供API的正确性、稳定性和符合性。它们通常模拟客户端请求，与server进行交互，检查 API 的响应数据、处理机制是否符合预期。 + * **特点**：需要一个正在运行的服务端（如 HugeGraph Server）来响应 API 请求。 + + +* **功能测试 (Functional Tests / FuncTestSuite)**： + * **目标**：验证系统或组件的特定功能是否按照需求正常工作。用于模拟用户场景或业务流程，涉及多个组件的交互，是端到端的测试。 + * **特点**：执行时间相对较长，需要完整的系统环境（包括所有依赖服务）来运行，能够发现集成层面的问题。 + +## 2. 测试前准备 + +### 2.1 系统与软件要求 + +* **操作系统**：建议 Linux, macOS。Windows 平台请使用 WSL2。 +* **JDK**：>= 11。确保您的 `JAVA_HOME` 环境变量已正确配置。 +* **Maven**：建议 3.5 及以上。用于项目构建和依赖管理。 +* **Python**：>= 3.11（仅HugeGraph-Hubble 相关测试需用）。建议使用虚拟环境进行管理，以避免版本冲突。 + +### 2.2 克隆代码仓库 + +首先，您需要克隆 HugeGraph 工具链的源代码仓库： + +```bash +git clone https://github.com/${GITHUB_USER_NAME}/hugegraph-toolchain.git +cd hugegraph-toolchain +``` + +## 3. 部署测试环境 + +关于测试环境，由于HugeGraph Server 是绝大多数集成测试和功能测试的核心依赖，有关安装/构建 HugeGraph-Server，可参考访问 [社区版文档](https://hugegraph.apache.org/cn/docs/quickstart/hugegraph/hugegraph-server/)。在本测试指南中，我们会介绍通过脚本部署与通过docker部署两种方式。 + +重要提示： +* 推荐优先使用脚本进行本地部署 HugeGraph Server。 这种方式允许您通过指定 Git Commit ID 来精确控制 Server 版本，确保与您的工具链代码版本高度匹配，从而有效避免因接口或实现变动导致测试异常的问题。 + +* Docker 部署方式更适合快速启动一个默认配置的 HugeGraph Server，但在进行精细化的集成测试时，特别是当您的工具链代码依赖于特定 HugeGraph Server 版本的功能或修复时，Docker 镜像的版本滞后或默认配置可能导致测试不通过。当工具链代码与 HugeGraph Server 存在接口/实现变动时，Docker 部署的便捷性可能反而导致测试失败，此时推荐回退到脚本部署方式。 + +### 3.1 使用脚本快速部署测试环境（推荐） + +这种方式允许您从源代码编译和安装特定版本的 HugeGraph Server，确保测试环境与特定 HugeGraph Server 版本的一致性，这对于复现问题或验证兼容性至关重要。 + +#### 3.1.1 变量与参数 + +* **`$COMMIT_ID`** + * 指定 HugeGraph Server 源代码的 Git Commit ID。当您需要从源代码编译和安装特定版本的 HugeGraph Server 作为测试依赖时，会使用此变量,确保测试环境与特定 HugeGraph Server 版本的一致性，这对于复现问题或验证兼容性至关重要。使用时直接接作为参数传递给 install-hugegraph-from-source.sh 脚本。 + +* **`$DB_DATABASE` 与 `$DB_PASS`** + 指定 HugeGraph-Loader 进行 JDBC 测试时所连接的 MySQL 数据库名称与 root 用户密码。请作为参数传递给 `install-mysql.sh` 脚本，供 Loader 正常读写数据。 + +#### 3.1.2 执行流程 + +**安装并启动 HugeGraph Server** + +如果您选择手动安装，可以使用以下脚本来安装 HugeGraph Server。该脚本位于任意工具仓库的`/assembly/travis/` 目录下 +用于从指定 commit id 拉取 HugeGraph Server 源码、编译、解压并分别以 http/https 启动服务 +```bash +hugegraph-*/assembly/travis/install-hugegraph-from-source.sh $COMMIT_ID +``` + +* `$COMMIT_ID`：指定 HugeGraph Server 的 Git Commit ID。 +* 默认http占用端口为8080，https占用端口为8443，请确保其在server启动前未被占用。 + +**安装并启动Hadoop (HDFS)** (仅当运行 hugegraph-loader的HDFS 测试时需要)： +```bash +hugegraph-loader/assembly/travis/install-hadoop.sh +``` + +**安装并启动MySQL** (仅当运行 hugegraph-loader的JDBC 测试时需要)： +```bash +hugegraph-loader/assembly/travis/install-mysql.sh $DB_DATABASE $DB_PASS +``` + + +**健康性检查** + +```bash +curl http://localhost:8080/graphs +``` +若返回 `{"graphs":["hugegraph"]}`，则表示服务器已准备就绪，可以接收请求。 + +### 3.2 使用 Docker 部署测试环境 + +通过使用官方发布的 hugegraph-server Docker 镜像，您可以快速启动一个 HugeGraph Server。这种方式简化了测试环境的搭建、确保环境一致性并提高测试的可重复性。**然而，请注意，Docker 镜像可能不会及时更新到 HugeGraph Server 的最新开发版本。这意味着如果您的工具链代码依赖于 HugeGraph Server 的最新接口或功能，使用 Docker 镜像可能会导致兼容性问题。在这种情况下，建议使用脚本方式部署特定 `COMMIT_ID` 的 HugeGraph Server。** + +#### docker快速启动 + +```bash +docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph:latest +``` + +快速启动一个内置了 RocksDB 的 Hugegraph server。满足大部分测试与toolchain组件运行的要求。 + +#### 示例 `docker-compose.yml` 文件 + +以下是一个示例 `docker-compose.yml` 文件，它定义了 HugeGraph Server、MySQL 和 Hadoop (HDFS) 服务。您可以根据实际测试需求进行调整。 + +```yaml +version: '3.8' + +services: + hugegraph-server: + image: hugegraph/hugegraph:latest # 可以替换为特定版本，或构建自己的镜像 + container_name: hugegraph-server + ports: + - "8080:8080" # HugeGraph Server HTTP 端口 + environment: + # 根据需要配置HugeGraph Server的参数，例如后端存储 + - HUGEGRAPH_SERVER_OPTIONS="-Dstore.backend=rocksdb" + volumes: + # 如果需要持久化数据或挂载配置文件，可以在这里添加卷 + # - ./hugegraph-data:/opt/hugegraph/data + healthcheck: + test: ["CMD-SHELL", "curl -f http://localhost:8080/graphs || exit 1"] + interval: 5s + timeout: 3s + retries: 5 + networks: + - hugegraph-net + + # 如果需要hugegraph-loader的JDBC测试，可以添加以下服务 + # mysql: + # image: mysql:5.7 + # container_name: mysql-db + # environment: + # MYSQL_ROOT_PASSWORD: ${DB_PASS:-your_mysql_root_password} # 从环境变量读取，或使用默认值 + # MYSQL_DATABASE: ${DB_DATABASE:-hugegraph_test_db} # 从环境变量读取，或使用默认值 + # ports: + # - "3306:3306" + # volumes: + # - ./mysql-data:/var/lib/mysql # 数据持久化 + # healthcheck: + # test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-p${DB_PASS:-your_mysql_root_password}"] + # interval: 5s + # timeout: 3s + # retries: 5 + # networks: + # - hugegraph-net + + # 如果需要hugegraph-loader的Hadoop/HDFS测试，可以添加以下服务 + # namenode: + # image: johannestang/hadoop-namenode:2.0.0-hadoop2.8.5-java8 + # container_name: namenode + # ports: + # - "0.0.0.0:9870:9870" + # - "0.0.0.0:8020:8020" + # environment: + # - CLUSTER_NAME=test-cluster + # - HDFS_NAMENODE_USER=root + # - HADOOP_CONF_DIR=/hadoop/etc/hadoop + # volumes: + # - ./config/core-site.xml:/hadoop/etc/hadoop/core-site.xml + # - ./config/hdfs-site.xml:/hadoop/etc/hadoop/hdfs-site.xml Review Comment: **Docker Compose配置存在问题**: 命令执行顺序和健康检查配置不正确。 **问题1 - namenode启动命令错误**: ```yaml command: bash -c "hdfs namenode -format && /entrypoint.sh" ``` - `hdfs namenode -format` 会每次格式化,导致数据丢失 - 应该只在首次初始化时格式化 **问题2 - 卷未定义**: docker-compose使用了 `namenode_data` 和 `datanode_data` 卷,但在文件末尾未定义: ```yaml volumes: namenode_data: datanode_data: ``` **建议修改**: ```yaml # 1. 修改command,检查是否已格式化 command: | bash -c ' if [ \! -d /hadoop/dfs/name/current ]; then hdfs namenode -format -force fi /entrypoint.sh ' # 2. 在文件末尾添加卷定义 volumes: namenode_data: datanode_data: ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
