回归测试

概念

  1. Suite: 一个测试用例，目前仅用来指代测试用例文件名
  2. Group: 一个测试集，目前仅用于指代测试用例所属的目录
  3. Action: 一个封装好的具体测试行为，比如用于执行sql的sql Action，用于校验结果的test Action，用于导入数据的streamLoad Action等

测试步骤

  1. 需要预先安装好集群
  2. 修改配置文件${DORIS_HOME}/conf/regression-conf.groovy，设置jdbc url、用户等配置项
  3. 创建测试用例文件并编写用例
  4. 如果用例文件包含qt Action，则需要创建关联的的data文件，比如suites/demo/qt_action.groovy这个例子，需要用到data/demo/qt_action.out这个TSV文件来校验输出是否一致
  5. 运行${DORIS_HOME}/run-regression-test.sh测试全部用例,或运行${DORIS_HOME}/run-regression-test.sh --run <suiteName> 测试若干用例，更多例子见”启动脚本例子”章节

目录结构

开发时需要关注的重要文件/目录

  1. run-regression-test.sh: 启动脚本
  2. regression-conf.groovy: 回归测试的默认配置
  3. data: 存放输入数据和输出校验数据
  4. suites: 存放用例
1. ./${DORIS_HOME}
2. |-- **run-regression-test.sh**           回归测试启动脚本
3. |-- regression-test
4. |   |-- conf
5. |   |   |-- logback.xml                  日志配置文件
6. |   |   |-- **regression-conf.groovy**   默认配置文件
7. |   |
8. |   |-- framework                        回归测试框架源码
9. |   |-- **data**                         用例的输入输出文件
10. |   |   |-- demo                         存放demo的输入输出文件
11. |   |   |-- correctness                  存放正确性测试用例的输入输出文件
12. |   |   |-- performance                  存放性能测试用例的输入输出文件
13. |   |   |-- utils                        存放其他工具的输入输出文件
14. |   |
15. |   |-- **suites**                       回归测试用例
16. |       |-- demo                         存放测试用例的demo
17. |       |-- correctness                  存放正确性测试用例
18. |       |-- performance                  存放性能测试用例
19. |       |-- utils                        其他工具
20. |
21. |-- output
22. |-- regression-test
23. |-- log                          回归测试日志

框架默认配置

测试时需要实际情况修改jdbc和fe的配置

2. /* ============ 一般只需要关注下面这部分 ============ */
3. // 默认DB,如果未创建,则会尝试创建这个db
4. defaultDb = "regression_test"

6. // Jdbc配置
7. jdbcUrl = "jdbc:mysql://127.0.0.1:9030/?"
8. jdbcUser = "root"
9. jdbcPassword = ""

11. // fe地址配置, 用于stream load
12. feHttpAddress = "127.0.0.1:8030"
13. feHttpUser = "root"
14. feHttpPassword = ""

16. /* ============ 一般不需要修改下面的部分 ============ */

18. // DORIS_HOME变量是通过run-regression-test.sh传入的
19. // 即 java -DDORIS_HOME=./

21. // 设置回归测试用例的目录
22. suitePath = "${DORIS_HOME}/regression-test/suites"
23. // 设置输入输出数据的目录
24. dataPath = "${DORIS_HOME}/regression-test/data"

26. // 默认会读所有的组,读多个组可以用半角逗号隔开，如: "demo,performance"
27. // 一般不需要在配置文件中修改，而是通过run-regression-test.sh来动态指定和覆盖
28. testGroups = ""
29. // 默认会读所有的用例, 同样可以使用run-regression-test.sh来动态指定和覆盖
30. testSuites = ""

32. // 其他自定义配置
33. customConf1 = "test_custom_conf_value"

编写用例的步骤

  1. 进入${DORIS_HOME}/regression-test目录
  2. 根据测试的目的来选择用例的目录，正确性测试存在suites/correctness，而性能测试存在suites/performance
  3. 新建一个groovy用例文件，增加若干Action用于测试，Action讲在后续章节具体说明

Action

Action是一个测试框架默认提供的测试行为，使用DSL来定义。

sql action

sql action用于提交sql并获取结果，如果查询失败则会抛出异常

参数如下

  • String sql: 输入的sql字符串
  • return List<List>: 查询结果，如果是DDL/DML，则返回一行一列，唯一的值是updateRowCount

下面的样例代码存放于${DORIS_HOME}/regression-test/suites/demo/sql_action.groovy:

1. // execute sql and ignore result
2. sql "show databases"

4. // execute sql and get result, outer List denote rows, inner List denote columns in a single row
5. List<List<Object>> tables = sql "show tables"

7. // assertXxx() will invoke junit5's Assertions.assertXxx() dynamically
8. assertTrue(tables.size() >= 0) // test rowCount >= 0

10. // syntax error
11. try {
12. sql "a b c d e"
13. throw new IllegalStateException("Should be syntax error")
14. } catch (java.sql.SQLException t) {
15. assertTrue(true)
16. }

18. def testTable = "test_sql_action1"

20. try {
21. sql "DROP TABLE IF EXISTS ${testTable}"

23. // multi-line sql
24. def result1 = sql """
25. CREATE TABLE IF NOT EXISTS ${testTable} (
26. id int
27. )
28. DISTRIBUTED BY HASH(id) BUCKETS 1
29. PROPERTIES (
30. "replication_num" = "1"
31. )
32. """

34. // DDL/DML return 1 row and 1 column, the only value is update row count
35. assertTrue(result1.size() == 1)
36. assertTrue(result1[0].size() == 1)
37. assertTrue(result1[0][0] == 0, "Create table should update 0 rows")

39. def result2 = sql "INSERT INTO test_sql_action1 values(1), (2), (3)"
40. assertTrue(result2.size() == 1)
41. assertTrue(result2[0].size() == 1)
42. assertTrue(result2[0][0] == 3, "Insert should update 3 rows")
43. } finally {
44. /**
45. * try_xxx(args) means:
46. *
47. * try {
48. *    return xxx(args)
49. * } catch (Throwable t) {
50. *     // do nothing
51. * }
52. */
53. try_sql("DROP TABLE IF EXISTS ${testTable}")

55. // you can see the error sql will not throw exception and return
56. try {
57. def errorSqlResult = try_sql("a b c d e f g")
58. assertTrue(errorSqlResult == null)
59. } catch (Throwable t) {
60. assertTrue(false, "Never catch exception")
61. }
62. }

64. // order_sql(sqlStr) equals to sql(sqlStr, isOrder=true)
65. // sort result by string dict
66. def list = order_sql """
67. select 2
68. union all
69. select 1
70. union all
71. select null
72. union all
73. select 15
74. union all
75. select 3
76. """
77. assertEquals(null, list[0][0])
78. assertEquals(1, list[1][0])
79. assertEquals(15, list[2][0])
80. assertEquals(2, list[3][0])
81. assertEquals(3, list[4][0])

qt action

qt action用于提交sql，并使用对应的.out TSV文件来校验结果

  • String sql: 输入sql字符串
  • return void

下面的样例代码存放于${DORIS_HOME}/regression-test/suites/demo/qt_action.groovy:

1. /**
2. * qt_xxx sql equals to quickTest(xxx, sql) witch xxx is tag.
3. * the result will be compare to the relate file: ${DORIS_HOME}/regression_test/data/qt_action.out.
4. *
5. * if you want to generate .out tsv file for real execute result. you can run with -genOut or -forceGenOut option.
6. * e.g
7. *   ${DORIS_HOME}/run-regression-test.sh --run qt_action -genOut
8. *   ${DORIS_HOME}/run-regression-test.sh --run qt_action -forceGenOut
9. */
10. qt_select "select 1, 'beijing' union all select 2, 'shanghai'"

12. qt_select2 "select 2"

14. // order result by string dict then compare to .out file.
15. // order_qt_xxx sql equals to quickTest(xxx, sql, true).
16. order_qt_union_all  """
17. select 2
18. union all
19. select 1
20. union all
21. select null
22. union all
23. select 15
24. union all
25. select 3
26. """

test action

test action可以使用更复杂的校验规则来测试，比如验证行数、执行时间、是否抛出异常

可用参数

  • String sql: 输入的sql字符串
  • List<List> result: 提供一个List对象，用于校验真实查询结果对比是否相等
  • String exception: 校验抛出的异常是否包含某些字符串
  • long rowNum: 验证结果行数
  • long time: 验证执行时间是否小于这个值，单位是毫秒
  • Closure<List<List>, Throwable, Long, Long> check: 自定义回调校验，可传入结果、异常、时间。存在回调函数时，其他校验方式会失效。

下面的样例代码存放于${DORIS_HOME}/regression-test/suites/demo/qt_action.groovy:

1. test {
2. sql "abcdefg"
3. // check exception message contains
4. exception "errCode = 2, detailMessage = Syntax error"
5. }

7. test {
8. sql """
9. select *
10. from (
11. select 1 id
12. union all
13. select 2
14. ) a
15. order by id"""

17. // multi check condition

19. // check return 2 rows
20. rowNum 2
21. // execute time must <= 5000 millisecond
22. time 5000
23. // check result, must be 2 rows and 1 column, the first row is 1, second is 2
24. result(
25. [[1], [2]]
26. )
27. }

29. test {
30. sql "a b c d e f g"

32. // other check will not work because already declared a check callback
33. exception "aaaaaaaaa"

35. // callback
36. check { result, exception, startTime, endTime ->
37. // assertXxx() will invoke junit5's Assertions.assertXxx() dynamically
38. assertTrue(exception != null)
39. }
40. }

42. test {
43. sql  """
44. select 2
45. union all
46. select 1
47. union all
48. select null
49. union all
50. select 15
51. union all
52. select 3
53. """

55. check { result, ex, startTime, endTime ->
56. // same as order_sql(sqlStr)
57. result = sortRows(result)

59. assertEquals(null, result[0][0])
60. assertEquals(1, result[1][0])
61. assertEquals(15, result[2][0])
62. assertEquals(2, result[3][0])
63. assertEquals(3, result[4][0])
64. }
65. }

explain action

explain action用来校验explain返回的字符串是否包含某些字符串

可用参数:

  • String sql: 查询的sql，需要去掉sql中的explain
  • String contains: 校验explain是否包含某些字符串，可多次调用校验同时多个结果
  • String notContains: 校验explain是否不含某些字符串，可多次调用校验同时多个结果
  • Closure check: 自定义校验回调函数，可以获取返回的字符串，存在校验函数时，其他校验方式会失效
  • Closure<String, Throwable, Long, Long> check: 自定义校验回调函数，可以额外获取异常和时间

下面的样例代码存放于${DORIS_HOME}/regression-test/suites/demo/explain_action.groovy:

1. explain {
2. sql("select 100")

4. // contains("OUTPUT EXPRS:<slot 0> 100\n") && contains("PARTITION: UNPARTITIONED\n")
5. contains "OUTPUT EXPRS:<slot 0> 100\n"
6. contains "PARTITION: UNPARTITIONED\n"
7. }

9. explain {
10. sql("select 100")

12. // contains(" 100\n") && !contains("abcdefg") && !("1234567")
13. contains " 100\n"
14. notContains "abcdefg"
15. notContains "1234567"
16. }

18. explain {
19. sql("select 100")
20. // simple callback
21. check { explainStr -> explainStr.contains("abcdefg") || explainStr.contains(" 100\n") }
22. }

24. explain {
25. sql("a b c d e")
26. // callback with exception and time
27. check { explainStr, exception, startTime, endTime ->
28. // assertXxx() will invoke junit5's Assertions.assertXxx() dynamically
29. assertTrue(exception != null)
30. }
31. }

streamLoad action

streamLoad action用于导入数据 可用参数为

  • String db: db，默认值为regression-conf.groovy中的defaultDb
  • String table: 表名
  • String file: 要导入的文件路径，可以写data目录下的相对路径，或者写http url来导入网络文件
  • Iterator<List> inputIterator: 要导入的迭代器
  • String inputText: 要导入的文本, 较为少用
  • InputStream inputStream: 要导入的字节流，较为少用
  • long time: 验证执行时间是否小于这个值，单位是毫秒
  • void set(String key, String value): 设置stream load的http请求的header，如label、columnSeparator
  • Closure<String, Throwable, Long, Long> check: 自定义校验回调函数，可以获取返回结果、异常和超时时间。当存在回调函数时，其他校验项会失效。

下面的样例代码存放于${DORIS_HOME}/regression-test/suites/demo/streamLoad_action.groovy:

1. def tableName = "test_streamload_action1"

3. sql """
4. CREATE TABLE IF NOT EXISTS ${tableName} (
5. id int,
6. name varchar(255)
7. )
8. DISTRIBUTED BY HASH(id) BUCKETS 1
9. PROPERTIES (
10. "replication_num" = "1"
11. )
12. """

14. streamLoad {
15. // you can skip declare db, because a default db already specify in ${DORIS_HOME}/conf/regression-conf.groovy
16. // db 'regression_test'
17. table tableName

19. // default label is UUID:
20. // set 'label' UUID.randomUUID().toString()

22. // default column_separator is specify in doris fe config, usually is '\t'.
23. // this line change to ','
24. set 'column_separator', ','

26. // relate to ${DORIS_HOME}/regression-test/data/demo/streamload_input.csv.
27. // also, you can stream load a http stream, e.g. http://xxx/some.csv
28. file 'streamload_input.csv'

30. time 10000 // limit inflight 10s

32. // stream load action will check result, include Success status, and NumberTotalRows == NumberLoadedRows
33. }

36. // stream load 100 rows
37. def rowCount = 100
38. def rowIt = java.util.stream.LongStream.range(0, rowCount) // [0, rowCount)
39. .mapToObj({i -> [i, "a_" + i]}) // change Long to List<Long, String>
40. .iterator()

42. streamLoad {
43. table tableName
44. // also, you can upload a memory iterator
45. inputIterator rowIt

47. // if declared a check callback, the default check condition will ignore.
48. // So you must check all condition
49. check { result, exception, startTime, endTime ->
50. if (exception != null) {
51. throw exception
52. }
53. log.info("Stream load result: ${result}".toString())
54. def json = parseJson(result)
55. assertEquals("success", json.Status.toLowerCase())
56. assertEquals(json.NumberTotalRows, json.NumberLoadedRows)
57. assertTrue(json.NumberLoadedRows > 0 && json.LoadBytes > 0)
58. }
59. }

启动脚本例子

1. # 查看脚本参数说明
2. ./run-regression-test.sh h

4. # 查看框架参数说明
5. ./run-regression-test.sh --run -h

7. # 测试所有用例
8. ./run-regression-test.sh

10. # 删除测试框架编译结果和测试日志
11. ./run-regression-test.sh --clean

13. # 测试suiteName为sql_action的用例, 目前suiteName等于文件名前缀，例子对应的用例文件是sql_action.groovy
14. ./run-regression-test.sh --run sql_action

16. # 测试suiteName包含'sql'的用例，**注意需要用单引号括起来**
17. ./run-regression-test.sh --run '*sql*'

19. # 测试demo和perfomance group
20. ./run-regression-test.sh --run -g 'demo,performance'

22. # 测试demo group下的sql_action
23. ./run-regression-test.sh --run -g demo -s sql_action

25. # 自定义配置
26. ./run-regression-test.sh --run -conf a=b

使用查询结果自动生成.out文件

1. # 使用查询结果自动生成sql_action用例的.out文件，如果.out文件存在则忽略
2. ./run-regression-test.sh --run sql_action -genOut

4. # 使用查询结果自动生成sql_action用例的.out文件，如果.out文件存在则覆盖
5. ./run-regression-test.sh --run sql_action -forceGenOut