集成测试

用于定义待测试的 SQL 以及测试结果的断言数据。每个用例定义一条 SQL，SQL 可定义多种数据库执行类型。

测试环境

用于搭建运行测试用例的数据库和 ShardingSphere-Proxy 环境。环境又具体分为环境准备方式，数据库类型和场景。

环境准备方式分为 Native 和 Docker，未来还将增加 Embed 类型的支持。

Native 环境用于测试用例直接运行在开发者提供的测试环境中，适用于调试场景。
Docker 环境由 Testcontainer 创建，适用于云编译环境和测试 ShardingSphere-Proxy 的场景，如：GitHub Action。
Embed 环境由测试框架自动搭建嵌入式 MySQL，适用于 ShardingSphere-JDBC 的本地环境测试。

当前默认采用 Docker 环境，使用 Testcontainer 创建运行时环境并执行测试用例。未来将采用 Embed 环境的 ShardingSphere-JDBC + MySQL，替换 Native 执行测试用例的默认环境类型。

数据库类型目前支持 MySQL、PostgreSQL、SQLServer 和 Oracle，并且可以支持使用 ShardingSphere-JDBC 或是使用 ShardingSphere-Proxy 执行测试用例。

场景用于对 ShardingSphere 支持规则进行测试，目前支持数据分片和读写分离的相关场景，未来会不断完善场景的组合。

用于批量读取测试用例，并逐条执行和断言测试结果。

测试引擎通过将用例和环境进行排列组合，以达到用最少的用例测试尽可能多场景的目的。

每条 SQL 会以的组合方式生成测试报告，目前各个维度的支持情况如下：

数据库类型：H2、MySQL、PostgreSQL、SQLServer 和 Oracle；
接入端类型：ShardingSphere-JDBC 和 ShardingSphere-Proxy；
SQL 执行模式：Statement 和 PreparedStatement；
JDBC 执行模式：execute 和 executeQuery（查询） / executeUpdate（更新）；
场景：分库、分表、读写分离和分库分表 + 读写分离。

使用指南

模块路径：test/e2e/suite

测试用例配置

SQL 用例在 resources/cases/${SQL-TYPE}/${SQL-TYPE}-integration-test-cases.xml。

用例文件格式如下：

expected-data-file 的查找规则是：

查找同级目录中 dataset\${SCENARIO_NAME}\${DATABASE_TYPE}\${dataset_file}.xml 文件；
查找同级目录中 dataset\${SCENARIO_NAME}\${dataset_file}.xml 文件；
查找同级目录中 dataset\${dataset_file}.xml 文件；
都找不到则报错。

断言文件格式如下：

${SCENARIO-TYPE} 表示场景名称，在测试引擎运行中用于标识唯一场景。 ${DATABASE-TYPE} 表示数据库类型。

Native 环境配置

目录：src/test/resources/env/scenario/${SCENARIO-TYPE}

: 数据源配置；
rules.yaml: 规则配置；
dataset.xml: 初始化数据；
init-sql\${DATABASE-TYPE}\init.sql: 初始化数据库表结构；
authority.xml: 待补充。

Docker 环境配置

目录：src/test/resources/env/${SCENARIO-TYPE}

proxy/conf/config-${SCENARIO-TYPE}.yaml: 规则配置。

Docker 环境配置为 ShardingSphere-Proxy 提供了远程调试端口，可以在 test/e2e/fixture/src/test/assembly/bin/start.sh 文件的 JAVA_OPTS 中找到第 2 个暴露的端口用于远程调试。

运行测试引擎

配置测试引擎运行环境

所有的属性值都可以通过 Maven 命令行的方式动态注入。

运行调试模式

标准测试引擎运行 org.apache.shardingsphere.test.integration.engine.${SQL-TYPE}.General${SQL-TYPE}E2EIT 以启动不同 SQL 类型的测试引擎。
批量测试引擎运行 org.apache.shardingsphere.test.integration.engine.dml.BatchDMLE2EIT，以启动为 DML 语句提供的测试 addBatch() 的批量测试引擎。
附加测试引擎运行 org.apache.shardingsphere.test.integration.engine.${SQL-TYPE}.Additional${SQL-TYPE}E2EIT 以启动使用更多 JDBC 方法调用的测试引擎。附加测试引擎需要通过设置 it.run.additional.cases=true 开启。

运行 Docker 模式

运行以上命令会构建出一个用于集成测试的 Docker 镜像 apache/shardingsphere-proxy-test:latest。如果仅修改了测试代码，可以复用已有的测试镜像，无须重新构建。使用以下命令可以跳过镜像构建，直接运行集成测试：

远程 debug Docker 容器中的 Proxy 代码

远程调试通过镜像启动的 Proxy

E2E 测试的 Proxy 镜像默认开启了 3308 端口用于远程调试容器中的实例。
使用 IDEA 等 IDE 工具可以通过如下方式连接并 debug 容器中的 Proxy 代码：

IDEA -> Run -> Edit Configurations -> Add New Configuration -> Remote JVM Debug

编辑对应的信息：

Name：一个描述性的名字，例如 e2e-debug。
Host：可以访问 docker 的 IP，例如 127.0.0.1。
Port：调试端口 3308。
use module classpath：项目根目录 shardingsphere。

编辑好上面的信息后，在 IDEA 中 Run -> Run -> e2e-debug 即可启动 IDEA 的远程 debug。

远程调试通过 Testcontainer 启动的 Proxy

在 Testcontainer 的相关启动类后打一个断点，例如 suite 测试中 BaseE2EIT#setUp() -> containerComposer.start(); 后面的一行打断点，此时相关容器一定已经启动。
通过快捷键 Alt + F8，进入断点调试模式，查看 containerComposer 下的 Proxy 对象 3308 映射的端口（Testcontainer 对外映射端口是随机的）。例如本次通过该表达式：((ShardingSphereProxyClusterContainer)((java.util.LinkedList)((ITContainers)((ClusterContainerComposer)containerComposer).containers).dockerContainers).getLast()).getMappedPort(3308) 获取到映射的对外随机端口为 51837。（或者通过命令 docker ps 查看）
参考中的方式，Port 设置为上一步中获取到的端口。