回归测试

概念

  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