This is an automated email from the ASF dual-hosted git repository.

panjuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git


The following commit(s) were added to refs/heads/master by this push:
     new 2efec03  Update IT document (#9105)
2efec03 is described below

commit 2efec0394d1010a547a91765b69913c1794c64b5
Author: Liang Zhang <terrym...@163.com>
AuthorDate: Wed Jan 20 18:35:18 2021 +0800

    Update IT document (#9105)
    
    * Update index
    
    * Update index
    
    * Update it document
---
 .../content/features/test-engine/_index.cn.md      |   4 +-
 .../features/test-engine/integration-test.cn.md    | 221 ++++++++++++---------
 .../features/test-engine/integration-test.en.md    |   2 -
 .../static/img/test-engine/integration-test.jpg    | Bin 288085 -> 0 bytes
 4 files changed, 127 insertions(+), 100 deletions(-)

diff --git a/docs/document/content/features/test-engine/_index.cn.md 
b/docs/document/content/features/test-engine/_index.cn.md
index 61e9f3b..c4f6b8f 100644
--- a/docs/document/content/features/test-engine/_index.cn.md
+++ b/docs/document/content/features/test-engine/_index.cn.md
@@ -6,6 +6,6 @@ chapter = true
 +++
 
 Apache ShardingSphere 提供了完善的测试引擎。
-它以 XML 方式定义 SQL,每个引擎分别为MySQL、PostgreSQL、SQLServer 和 Oracle 数据库运行测试用例。
+它以 XML 方式定义 SQL,每个引擎分别为 MySQL、PostgreSQL、SQLServer 和 Oracle 数据库运行测试用例。
 
-为了方便上手,测试引擎不必修改任何 **Java** 代码,只需要修改相应的配置文件即可运行断言。
+为了方便上手,测试引擎无需修改任何 **Java** 代码,只需修改相应的配置文件即可运行断言。
diff --git a/docs/document/content/features/test-engine/integration-test.cn.md 
b/docs/document/content/features/test-engine/integration-test.cn.md
index 4cef504..69c1358 100644
--- a/docs/document/content/features/test-engine/integration-test.cn.md
+++ b/docs/document/content/features/test-engine/integration-test.cn.md
@@ -4,130 +4,159 @@ title = "集成测试"
 weight = 1
 +++
 
-SQL解析单元测试全面覆盖SQL占位符和字面量维度。
-整合测试进一步拆分为策略和JDBC两个维度,策略维度包括分库分表、仅分表、仅分库、读写分离等策略,JDBC维度包括Statement、PreparedStatement。
+## 设计
 
-因此,1条SQL会驱动5种数据库的解析 * 2种参数传递类型 + 5种数据库 * 5种分片策略 * 2 种 JDBC 运行方式 = 
60个测试用例,以达到ShardingSphere对于高质量的追求。
+集成测试包括 3 个模块:测试用例、测试环境以及测试引擎。
 
-## 流程
+### 测试用例
 
-Junit 中的 `Parameterized` 会聚合起所有的测试数据,并将测试数据一一传递给测试方法进行断言。数据处理就像是沙漏中的流沙:
+用于定义待测试的 SQL 以及测试结果的断言数据。
+每个用例定义一条 SQL,SQL 可定义多种数据库执行类型。
 
-![](https://shardingsphere.apache.org/document/current/img/test-engine/integration-test.jpg)
+### 测试环境
 
-### 配置
+用于搭建运行测试用例的数据库和 ShardingSphere-Proxy 环境。
+环境又具体分为环境准备方式,数据库类型和场景。
 
-  - 环境类文件
-    - 
/shardingsphere-integration-test-suite/src/test/resources/env-native.properties
-    - 
/shardingsphere-integration-test-suite/src/test/resources/env/`SQL-TYPE`/dataset.xml
-    - 
/shardingsphere-integration-test-suite/src/test/resources/env/`SQL-TYPE`/schema.xml
-  - 测试用例类文件
-    - 
/shardingsphere-integration-test-suite/src/test/resources/cases/`SQL-TYPE`/`SQL-TYPE`-integration-test-cases.xml
-    - 
/shardingsphere-integration-test-suite/src/test/resources/cases/`SQL-TYPE`/dataset/`FEATURE-TYPE`/*.xml
-  - sql-case 文件
-    - 
/shardingsphere-integration-test-suite/src/main/resources/sql/sharding/`SQL-TYPE`/*.xml
+环境准备方式分为 Native 和 Docker,未来还将增加 Embed 类型的支持。
 
-### 环境配置 
+  - Native 环境用于测试用例直接运行在开发者提供的测试环境中,适于调试场景;
+  - Docker 环境由 Maven 运行 Docker-Compose 插件直接搭建,适用于云编译环境和测试 ShardingSphere-Proxy 
的场景,如:GitHub Action;
+  - Embed 环境由测试框架自动搭建嵌入式 MySQL,适用于 ShardingSphere-JDBC 的本地环境测试。
 
-集成测试需要真实的数据库环境,根据相应的配置文件创建测试环境:
+当前默认采用 Native 环境,使用 ShardingSphere-JDBC + H2 数据库运行测试用例。
+通过 Maven 的 `-P -Pit.env.docker` 参数可以指定 Docker 环境的运行方式。
+未来将采用 Embed 环境的 ShardingSphere-JDBC + MySQL,替换 Native 执行测试用例的默认环境类型。 
 
-首先,修改配置文件 
`/shardingsphere-integration-test-suite/src/test/resources/env-native.properties`
 ,例子如下:
+数据库类型目前支持 MySQL、PostgreSQL、SQLServer 和 Oracle,并且可以支持使用 ShardingSphere-JDBC 
或是使用 ShardingSphere-Proxy 执行测试用例。
 
-```properties
-# 测试主键,并发,column index等的开关
-it.run.additional.cases=false
+场景用于对 ShardingSphere 支持规则进行测试,目前支持数据分片和读写分离的相关场景,未来会不断完善场景的组合。
 
-# 测试场景,可指定多种规则
-it.scenarios=db,tbl,dbtbl_with_replica_query,replica_query
+### 测试引擎
 
-# 要测试的数据库,可以指定多种数据库(H2,MySQL,Oracle,SQLServer,PostgreSQL)
-it.databases=MySQL,PostgreSQL
-
-# MySQL配置
-it.mysql.host=127.0.0.1
-it.mysql.port=13306
-it.mysql.username=root
-it.mysql.password=root
-
-## PostgreSQL配置
-it.postgresql.host=db.psql
-it.postgresql.port=5432
-it.postgresql.username=postgres
-it.postgresql.password=postgres
-
-## SQLServer配置
-it.sqlserver.host=db.mssql
-it.sqlserver.port=1433
-it.sqlserver.username=sa
-it.sqlserver.password=Jdbc1234
-
-## Oracle配置
-it.oracle.host=db.oracle
-it.oracle.port=1521
-it.oracle.username=jdbc
-it.oracle.password=jdbc
-```
+用于批量读取测试用例,并逐条执行和断言测试结果。
 
-其次,修改文件 
`/shardingsphere-integration-test-suite/src/test/resources/env/SQL-TYPE/dataset.xml`
 
-在`dataset.xml`文件中定义元数据和测试数据。例如:
+测试引擎通过将用例和环境进行排列组合,以达到用最少的用例测试尽可能多场景的目的。
 
-```xml
-<dataset>
-    <metadata data-nodes="tbl.t_order_${0..9}">
-        <column name="order_id" type="numeric" />
-        <column name="user_id" type="numeric" />
-        <column name="status" type="varchar" />
-    </metadata>
-    <row data-node="tbl.t_order_0" values="1000, 10, init" />
-    <row data-node="tbl.t_order_1" values="1001, 10, init" />
-    <row data-node="tbl.t_order_2" values="1002, 10, init" />
-    <row data-node="tbl.t_order_3" values="1003, 10, init" />
-    <row data-node="tbl.t_order_4" values="1004, 10, init" />
-    <row data-node="tbl.t_order_5" values="1005, 10, init" />
-    <row data-node="tbl.t_order_6" values="1006, 10, init" />
-    <row data-node="tbl.t_order_7" values="1007, 10, init" />
-    <row data-node="tbl.t_order_8" values="1008, 10, init" />
-    <row data-node="tbl.t_order_9" values="1009, 10, init" />
-</dataset>
-```
+每条 SQL 会以`数据库类型 * 接入端类型 * SQL 执行模式 * JDBC 执行模式 * 场景`的组合方式生成测试报告,目前各个维度的支持情况如下:
+
+  - 数据库类型:H2、MySQL、PostgreSQL、SQLServer 和 Oracle;
+  - 接入端类型:ShardingSphere-JDBC 和 ShardingSphere-Proxy;
+  - SQL 执行模式:Statement 和 PreparedStatement;
+  - JDBC 执行模式:execute 和 executeQuery (查询) / executeUpdate (更新);
+  - 场景:分库、分表、读写分离和分库分表 + 读写分离。
+
+因此,1 条 SQL 会驱动:`数据库类型(5) * 接入端类型(2) * SQL 执行模式(2) * JDBC 执行模式(2) * 场景(4) = 
160` 个测试用例运行,以达到项目对于高质量的追求。
 
-开发者可以在 `schema.xml` 中自定义建库与建表语句。 
+## 使用指南
 
-### 断言配置
+### 测试用例配置
 
-`env-native.properties` 与 `dataset.xml ` 确定了什么SQL在什么环境执行,下面是断言数据的配置:
+SQL 用例在 
`shardingsphere-test/shardingsphere-integration-test/shardingsphere-integration-test/resources/cases/${SQL-TYPE}/${SQL-TYPE}-integration-test-cases.xml`。
 
-断言的配置,需要两种文件,第一类文件位于 
`/shardingsphere-integration-test-suite/src/test/resources/cases/SQL-TYPE/SQL-TYPE-integration-test-cases.xml`
-这个文件类似于一个索引,定义了要执行的SQL,参数以及期待的数据的文件位置。这里的 test-case 引用的就是`sharding-sql-test`中 
SQL 对应的`sql-case-id`,例子如下:
+用例文件格式如下:
 
 ```xml
 <integration-test-cases>
-    <dml-test-case sql-case-id="insert_with_all_placeholders">
-       <assertion parameters="1:int, 1:int, insert:String" 
expected-data-file="insert_for_order_1.xml" />
-       <assertion parameters="2:int, 2:int, insert:String" 
expected-data-file="insert_for_order_2.xml" />
-    </dml-test-case>
+    <test-case sql="${SQL}">
+        <assertion parameters="${value_1}:${type_1}, ${value_2}:${type_2}" 
expected-data-file="${dataset_file_1}.xml" />
+        <!-- ... more assertions -->
+        <assertion parameters="${value_3}:${type_3}, ${value_4}:${type_4}" 
expected-data-file="${dataset_file_2}.xml" />
+     </test-case>
+    
+    <!-- ... more test cases -->
 </integration-test-cases>
 ```
-还有一类文件 -- 断言数据,也就是上面配置中的 expected-data-file 对应的文件,文件在 
`/shardingsphere-integration-test-suite/src/test/resources/cases/SQL-TYPE/dataset/FEATURE-TYPE/*.xml`
-这个文件内容跟 dataset.xml 
很相似,只不过`expected-data-file`文件中不仅定义了断言的数据,还有相应SQL执行后的返回值等。例如:
+
+`expected-data-file` 的查找规则是:
+  1. 查找同级目录中 `dataset\${SCENARIO_NAME}\${DATABASE_TYPE}\${dataset_file}.xml` 
文件;
+  2. 查找同级目录中 `dataset\${SCENARIO_NAME}\${dataset_file}.xml` 文件;
+  3. 查找同级目录中 `dataset\${dataset_file}.xml` 文件;
+  4. 都找不到则报错。
+
+断言文件格式如下:
 
 ```xml
-<dataset update-count="1">
-    <metadata data-nodes="db_${0..9}.t_order">
-        <column name="order_id" type="numeric" />
-        <column name="user_id" type="numeric" />
-        <column name="status" type="varchar" />
+<dataset>
+    <metadata>
+        <column name="column_1" />
+        <!-- ... more columns -->
+        <column name="column_n" />
     </metadata>
-    <row data-node="db_0.t_order" values="1000, 10, update" />
-    <row data-node="db_0.t_order" values="1001, 10, init" />
-    <row data-node="db_0.t_order" values="2000, 20, init" />
-    <row data-node="db_0.t_order" values="2001, 20, init" />
+    <row values="value_01, value_02" />
+    <!-- ... more rows -->
+    <row values="value_n1, value_n2" />
 </dataset>
 ```
 
-所有需要配置的数据,都已经配置完毕,启动相应的集成测试类即可,全程不需要修改任何 `Java` 代码,只需要在 `xml` 
中做数据初始化以及断言,极大的降低了ShardingSphere数据测试的门槛以及复杂度。
+### 环境配置
+
+`${SCENARIO-TYPE}` 表示场景名称,在测试引擎运行中用于标识唯一场景。
+`${DATABASE-TYPE}` 表示数据库类型。
+
+#### Native 环境配置
+
+目录:`shardingsphere-test/shardingsphere-integration-test/shardingsphere-integration-test/resources/env/${SCENARIO-TYPE}`
+
+  - `scenario-env.properties`: 数据源配置
+  - `rules.yaml`: 规则配置
+  - `databases.xml`: 真实库名称
+  - `dataset.xml`: 初始化数据
+  - `${DATABASE-TYPE}\init.sql`: 初始化数据库表结构
+  - `authority.xml`: 待补充
+
+#### Docker 环境配置
+
+目录:`shardingsphere-test/shardingsphere-integration-test/shardingsphere-integration-test/resources/docker/${SCENARIO-TYPE}`
+
+  - `docker-compose.yml`: Docker-Compose 配置文件,用于 Docker 环境启动
+  - `proxy/conf/config-${SCENARIO-TYPE}.yaml`: 规则配置
+
+**Docker 环境配置为 ShardingSphere-Proxy 提供了远程调试端口,可以在 `docker-compose.yml` 文件的 
`shardingsphere-proxy`中找到第 2 个暴露的端口用于远程调试。**
+
+### 运行测试引擎
+
+#### 配置测试引擎运行环境
+
+通过配置 
`shardingsphere-test/shardingsphere-integration-test/shardingsphere-integration-test-suite/src/test/resources/env/engine-env.properties`
 控制测试引擎。
+
+所有的属性值都可以通过 Maven 命令行 `-D` 的方式动态注入。
+
+```properties
+# 配置环境类型,只支持单值。可选值:docker或空,默认值:空
+it.env.type=${it.env}
+# 待测试的接入端类型,多个值可用逗号分隔。可选值:jdbc, proxy,默认值:jdbc
+it.adapters=jdbc
+
+# 场景类型,多个值可用逗号分隔。可选值:db, tbl, dbtbl_with_replica_query, replica_query
+it.scenarios=db,tbl,dbtbl_with_replica_query,replica_query
+
+# 场景类型,多个值可用逗号分隔。可选值:H2, MySQL, Oracle, SQLServer, PostgreSQL
+it.databases=H2,MySQL,Oracle,SQLServer,PostgreSQL
+
+# 是否运行附加测试用例
+it.run.additional.cases=false
+```
+
+#### 运行调试模式
+
+  - 标准测试引擎
+    运行 
`org.apache.shardingsphere.test.integration.engine.it.${SQL-TYPE}.General${SQL-TYPE}IT`
 以启动不同 SQL 类型的测试引擎。
+
+  - 批量测试引擎
+    运行 
`org.apache.shardingsphere.test.integration.engine.it.dml.BatchDMLIT`,以启动为 DML 
语句提供的测试 `addBatch()` 的批量测试引擎。
+
+  - 附加测试引擎
+    运行 
`org.apache.shardingsphere.test.integration.engine.it.${SQL-TYPE}.Additional${SQL-TYPE}IT`
 以启动使用更多 JDBC 方法调用的测试引擎。
+    附加测试引擎需要通过设置 `it.run.additional.cases=true` 开启。
+
+#### 运行Docker 模式
+
+```bash
+./mvnw -B clean install -f 
shardingsphere-test/shardingsphere-integration-test/pom.xml -Pit.env.docker 
-Dit.adapters=proxy,jdbc 
-Dit.scenarios=${scenario_name_1,scenario_name_1,scenario_name_n} 
-Dit.databases=MySQL
+```
 
-## 注意事项
+#### 注意事项
 
-1. 如需测试Oracle,请在pom.xml中增加Oracle驱动依赖。
-1. 为了保证测试数据的完整性,整合测试中的分库分表采用了10库10表的方式,因此运行测试用例的时间会比较长。
+1. 如需测试 Oracle,请在 pom.xml 中增加 Oracle 驱动依赖;
+1. 为了保证测试数据的完整性和易读性,整合测试中的分库分表采用了 10 库 10 表的方式,完全运行测试用例所需时间较长。
diff --git a/docs/document/content/features/test-engine/integration-test.en.md 
b/docs/document/content/features/test-engine/integration-test.en.md
index 26ddbc7..a5d8dc8 100644
--- a/docs/document/content/features/test-engine/integration-test.en.md
+++ b/docs/document/content/features/test-engine/integration-test.en.md
@@ -13,8 +13,6 @@ Therefore, one SQL can drive 5 kinds of database parsing * 2 
kinds of parameter
 
 The `Parameterized` in JUnit will collect all test data, and pass to test 
method to assert one by one. The process of handling test data is just like a 
leaking hourglass:
 
-![](https://shardingsphere.apache.org/document/current/img/test-engine/integration-test.jpg)
-
 ### Configuration
  
   - environment type
diff --git a/docs/document/static/img/test-engine/integration-test.jpg 
b/docs/document/static/img/test-engine/integration-test.jpg
deleted file mode 100644
index bde171d..0000000
Binary files a/docs/document/static/img/test-engine/integration-test.jpg and 
/dev/null differ

Reply via email to