如何添加测试查询到 ClickHouse CI

ClickHouse 拥有数百（甚至数千）项功能。每个提交都会经过一组复杂的测试检查，这些测试包含数千个测试用例。

核心功能经过了非常充分的测试，但 ClickHouse CI 可以发现一些极端情况和功能的不同组合。

我们看到的大多数错误/回归都发生在测试覆盖率较差的“灰色区域”。

我们非常希望通过测试覆盖现实生活中使用的大多数可能场景和功能组合。

为什么要添加测试

为什么/何时应将测试用例添加到 ClickHouse 代码中：1) 您使用了一些复杂的场景/功能组合/您有一些可能不太常用的极端情况 2) 您发现某些行为在版本之间发生了更改，但在变更日志中没有通知 3) 您只是想帮助提高 ClickHouse 的质量并确保您使用的功能在将来的版本中不会被破坏 4) 测试添加/接受后，您可以确保您检查的极端情况永远不会被意外破坏。 5) 您将成为优秀的开源社区的一员 6) 您的姓名将显示在 system.contributors 表中！ 7) 您将让世界变得更美好 :)

操作步骤

先决条件

我假设您运行的是一些 Linux 机器（您可以在其他操作系统上使用 docker/虚拟机），以及任何现代浏览器/互联网连接，并且您具有一些基本的 Linux 和 SQL 技能。

不需要任何高度专业化的知识（因此您不需要了解 C++ 或 ClickHouse CI 的工作原理）。

准备工作

1) 创建 GitHub 账户（如果您还没有） 2) 设置 git

# for Ubuntu
sudo apt-get update
sudo apt-get install git

git config --global user.name "John Doe" # fill with your name
git config --global user.email "[email protected]" # fill with your email

3) 为 ClickHouse 项目创建分支 - 只需打开 https://github.com/ClickHouse/ClickHouse 并点击右上角的分支按钮：

4) 将您的分支克隆到 PC 上的某个文件夹中，例如 ~/workspace/ClickHouse

mkdir ~/workspace && cd ~/workspace
git clone https://github.com/< your GitHub username>/ClickHouse
cd ClickHouse
git remote add upstream https://github.com/ClickHouse/ClickHouse

测试的新分支

1) 从最新的 clickhouse master 创建一个新分支

cd ~/workspace/ClickHouse
git fetch upstream
git checkout -b name_for_a_branch_with_my_test upstream/master

安装和运行 ClickHouse

1) 安装 clickhouse-server（请遵循 官方文档） 2) 安装测试配置（它将使用 Zookeeper 模拟实现并调整一些设置）

cd ~/workspace/ClickHouse/tests/config
sudo ./install.sh

3) 运行 clickhouse-server

sudo systemctl restart clickhouse-server

创建测试文件

1) 查找测试编号 - 在 tests/queries/0_stateless/ 中查找编号最大的文件。

$ cd ~/workspace/ClickHouse
$ ls tests/queries/0_stateless/[0-9]*.reference | tail -n 1
tests/queries/0_stateless/01520_client_print_query_id.reference

目前，测试的最后一个编号是 01520，因此我的测试编号将是 01521

2) 创建一个 SQL 文件，其中包含下一个编号以及您要测试的功能的名称。

touch tests/queries/0_stateless/01521_dummy_test.sql

3) 使用您喜欢的编辑器编辑 SQL 文件（请参阅下面创建测试的提示）。

vim tests/queries/0_stateless/01521_dummy_test.sql

4) 运行测试，并将结果放入参考文件中。

clickhouse-client -nm < tests/queries/0_stateless/01521_dummy_test.sql | tee tests/queries/0_stateless/01521_dummy_test.reference

5) 确保一切正确，如果测试输出不正确（例如由于某些错误），请使用文本编辑器调整参考文件。

如何创建良好的测试

• 测试应
  • 最小化 - 只创建与测试功能相关的表，删除不相关的列和查询部分。
  • 快速 - 不应花费超过几秒钟（最好是亚秒级）。
  • 正确 - 功能无法工作时失败。

    - deterministic
  • 隔离/无状态
    • 不要依赖某些环境因素。
    • 在可能的情况下不要依赖计时。
• 尝试覆盖极端情况（零/空值/空集/抛出异常）。
• 要测试查询是否返回错误，您可以在查询后添加特殊注释：-- { serverError 60 } 或 -- { clientError 20 }。
• 不要切换数据库（除非必要）。
• 如果需要，您可以在同一节点上创建多个表副本。
• 如果需要，您可以使用其中一个测试集群定义（请参阅 system.clusters）。
• 在适用时，使用 number/numbers_mt/zeros/zeros_mt 等进行查询/初始化数据。
• 在测试后和测试前清理创建的对象（DROP IF EXISTS） - 以防出现某些脏数据状态。
• 优先使用操作的同步模式（变异、合并等）。
• 使用 0_stateless 文件夹中的其他 SQL 文件作为示例。
• 确保您要测试的功能/功能组合尚未通过现有测试进行覆盖。

测试命名规则

正确命名测试非常重要，这样用户就可以在 clickhouse-test 调用中关闭某些测试子集。

测试器标记	测试名称中应该包含什么	何时应添加标记
--[no-]zookeeper	"zookeeper" 或 "replica"	测试使用来自 ReplicatedMergeTree 系列的表。
--[no-]shard	"shard" 或 "distributed" 或 "global"	测试使用连接到 127.0.0.2 或类似地址。
--[no-]long	"long" 或 "deadlock" 或 "race"	测试运行时间超过 60 秒。

提交/推送/创建 PR。

1) 提交并推送您的更改。

cd ~/workspace/ClickHouse
git add tests/queries/0_stateless/01521_dummy_test.sql
git add tests/queries/0_stateless/01521_dummy_test.reference
git commit # use some nice commit message when possible
git push origin HEAD

2) 使用推送过程中显示的链接，向主仓库创建 PR 3) 调整 PR 标题和内容，在 变更日志类别（选择一个）中保留 构建/测试/打包改进，如果需要，填写其余字段。