Databend 测试区实战指南读懂 tests/ 目录结构与测试治理规范【免费下载链接】databendData Agent Ready Warehouse : One for Analytics, Search, AI, Python Sandbox. — rebuilt from scratch. Unified architecture on your S3.项目地址: https://gitcode.com/GitHub_Trending/da/databendDatabend 是一个为分析、搜索、AI 与 Python Sandbox 场景设计的 Data Agent Ready Warehouse其正确性保障高度依赖仓库根目录下tests/中分层清晰的测试体系。本文以 tests/AGENTS.md 这份测试区导航文档为骨架逐层拆解 Databend 测试区的工作指南如何在 stateless 回归、sqllogictest、metactl 夹具、兼容性矩阵与长跑测试之间做出正确的最小测试平台选择并给出每个子系统的目录规范、运行命令与源码依据。读完本文你将能像 Databend 维护者一样快速定位某个改动应该落在哪个测试目录、用什么命令运行、如何保证输出确定性。一、测试区总纲AGENTS.md 的九条工作准则tests/AGENTS.md 全篇只有 9 行却浓缩了 Databend 测试区tests/的全部治理原则。它服务于两类读者在tests/下工作的开发者以及更重要地被接入仓库执行任务的 AI Agent。其核心决策逻辑可以归纳为一条主线——先选最小的、能覆盖待验证行为的测试平台再读就近的 README 确认文件布局与运行器工作流。文档给出的选择矩阵如下待验证的行为应使用的测试区域对应目录无状态 SQL 回归不依赖外部数据/服务的纯 SQL 行为Stateless SQL 回归tests/suites/0_stateless/带预期结果的语句/查询测试、定向 glob、自动补全Sqllogictest 用例tests/sqllogictests/meta 类型变更引发的 metactl 夹具刷新或恢复流程Metactl 夹具测试tests/metactl/集群行为集群测试tests/meta-cluster/query 与 meta 之间的版本兼容性兼容性测试tests/compat/FUSE 表存储格式的跨版本读写兼容FUSE 存储格式兼容测试tests/compat_fuse/并发与重负载下的正确性/性能长跑测试tests/longrun/AGENTS.md 在结尾提出两条铁律也是全文唯一的两条禁止/必须约束保持预期输出确定性Keep expected outputs deterministic——这是所有基于结果比对.result、sqllogictest 期望值的测试成立的前提当可复现性依赖新夹具或新配置时必须为它们补文档——防止能跑但说不清的黑盒测试积累。这两条准则将贯穿下面所有子系统的展开。二、Stateless 回归tests/suites/0_stateless/的命名与分类规范AGENTS.md 要求 stateless SQL 回归文件必须遵循数字分类 序号的命名规则这一规范在 tests/suites/0_stateless/README.md 中有完整定义。2.1 目录结构00_dummy/ ├── 00_0000_dummy_select_1.result ├── 00_0000_dummy_select_1.sql ├── 00_0000_dummy_select_sh.sh ├── 00_0001_select_with_stackoverflow.result ├── 00_0001_select_with_stackoverflow.sql ├── 00_0002_dummy_select_py.py ├── 00_0002_dummy_select_py.result └── 00_0002_dummy_select_sh.result一个测试用例由同名的多个文件组成.sql为输入的 SQL 脚本.result为期望输出也可以出现.shshell 脚本或.pyPython 脚本形式的驱动脚本它们各自对应一个.result文件。2.2 命名规则测试名格式为xx_yyyy_[test_name]xx是分类编号yyyy是该分类下的序号[test_name]是语义化名称。例如00_0000_dummy_select_1表示分类00下的第0000个测试名为dummy_select_1。2.3 分类编号对照表README 中给出的分类如下注意 README 的编号体系与实际仓库目录略有演化以当前仓库实际目录为准编号分类用途00dummyDummy 测试01system系统表测试02function函数测试03dmlSELECT、INSERT、UPDATE、DELETE测试04explainEXPLAIN测试05ddlDDL 测试06showSHOW语句测试07useUSE语句测试08optimizerOptimizer 测试09fuse_engineFUSE 存储引擎测试10drivers驱动集成测试20others其他测试README 特别注明如果测试不属于上述任何分类请新增分类编号而不是硬塞进不相关的类别。当前仓库实际已经演化出一组更细的目录例如 tests/suites/0_stateless/ 下包含01_transaction、02_ddl、03_dml、05_hints、10_drivers、12_time_travel、16_flashback、17_altertable、18_rbac、19_fuzz、20_others等这正体现了分类不足则新增的演进规则。三、Sqllogictesttests/sqllogictests/的用例格式与运行器工作流AGENTS.md 提到 sqllogictests 是用例 运行器专属工作流定向 glob 与自动补全的组合。这部分内容在 tests/sqllogictests/README.md 中有完整展开。3.1 实现基础Databend 的 sqllogictest 是基于 SQLite 官方 sqllogictest 思想的自研实现使用sqllogictest-rs解析测试文件并执行用例。运行前需要先生成databend-sqllogictests二进制。3.2 运行器常用命令运行三种 handlermysql、http下的全部测试databend-sqllogictests指定 handler 运行databend-sqllogictests --handlers handler_name按 glob 模式定向运行这是 AGENTS.md 提到的定向 globdatabend-sqllogictests --run tests/sqllogictests/suites/base/**/*.test或简写形式databend-sqllogictests --run **/suites/base/**/*用多个 glob 组合运行少量文件或目录databend-sqllogictests --run tests/sqllogictests/suites/base/00_dummy/*.test,tests/sqllogictests/suites/base/03_common/*.test跳过部分匹配文件databend-sqllogictests --run tests/sqllogictests/suites/base/**/*.test --skip tests/sqllogictests/suites/base/01_system按目录名运行在--suites下查找databend-sqllogictests --run_dir dir_name按文件名运行databend-sqllogictests --run_file file_name自动补全测试文件AGENTS.md 提到的auto-completion生成期望结果后仅需人工终审databend-sqllogictests --run_file file_name --complete关闭失败即停fail-fast默认遇失败即退出如需跑完全部测试databend-sqllogictests --no-fail-fast并行运行测试文件databend-sqllogictests --enable_sandbox --parallel number注意并行模式要求启动 databend query 时额外添加--internal-enable-sandbox-tenant配置。更多参数可查看databend-sqllogictests --help。3.3 用例格式sqllogictest 用例由两类记录组成Statement语句——执行后不校验结果集只校验成功或失败适用于CREATE TABLE、INSERT、UPDATE、DROP INDEX等。以以下两行之一开头statement ok statement error error infoSQL 命令位于记录的第二行及之后每条记录只允许一条 SQL且不能以分号结尾。Query查询——期望返回结果集允许为空。格式为# comments query type_string sort_mode label sql_query ---- expected_resultSQL 位于记录第二行起直到第一个----行或记录结束----之后是期望结果每行一个值若----和结果都省略则期望返回空集。type_string、sort_mode、label的具体语义遵循 sqllogictest 通用规范。3.4 附加特性SQL 中形如\$RAND_(\d)_(\d)的正则模式会被替换为指定范围内的随机数——这是保证确定性与随机性并存的典型设计测试数据随机但断言逻辑固定。四、Meta 类型变更tests/metactl/的夹具刷新与恢复流程AGENTS.md 规定当meta 类型变更要求刷新 metactl 夹具或恢复流程时使用tests/metactl/。该目录的说明文档 tests/metactl/README.md 极为精简——它只回答一个问题如何更新测试数据。当 meta 类型即 meta-service 的持久化数据结构发生变更后需要重新生成该测试使用的期望数据# 在 databend 仓库根目录执行 sh ./tests/metactl/update-metactl-test.sh结合 tests/metactl/ 目录内容可以看到这一子系统的全貌meta_v003.txt、meta_v004.txt不同版本的 meta 导出文本用于验证 metactl 的版本感知能力want_exported_v004、want_snapshot_v004期望的导出/快照结果config/metactl 测试配置subcommands/针对 metactl 子命令的专项测试脚本README_SUBCOMMAND_TESTS.mdtest-metactl.sh、test-metactl-restore-new-cluster.py、test_all_subcommands.py主测试入口与恢复流程测试metactl_utils.py、utils.py、requirements.txtPython 侧工具与依赖。AGENTS.md 特别强调fixtures夹具——meta_v00x.txt、want_*这类静态期望文件正是夹具它们必须与 meta 类型的当前实现保持同步这解释了为什么 meta 类型一变就要跑update-metactl-test.sh刷新。五、集群、兼容性与存储格式meta-cluster/compat/compat_fuseAGENTS.md 将四个目录归入同一档位仅当改动需要集群、兼容性、存储格式或长时运行覆盖时才使用。前三者在小节内展开。5.1 集群测试tests/meta-cluster/tests/meta-cluster/README.md 描述了一个三阶段的 meta 集群生命周期测试用--single启动单节点集群再拉起另外 2 个节点用--join加入集群让其中一个节点离开集群。这验证的是 databend-meta 的集群成员管理加入/离开与多节点协同。运行入口是 test-meta-cluster.sh。5.2 Query 与 Meta 的跨版本兼容tests/compat/tests/compat/README.md 说明该测试的目标是双向找出最小兼容版本找出能配合最新 databend-meta运行的最小 databend-query 版本找出能配合最新 databend-query运行的最小 databend-meta 版本。实现方式是在旧 query 最新 meta与旧 meta 最新 query两组组合上运行若干 sql-logic 测试。配套脚本为 test-compat.sh 与 util.shmeta_meta/子目录则存放 meta 到 meta 的兼容用例。5.3 FUSE 表格式跨版本读写tests/compat_fuse/tests/compat_fuse/README.md 定义了 FUSE 表存储格式fuse-table format的写后读兼容性测试方向有两个向后兼容Backward compat旧版本 writer 写 → 当前版本 reader 读向前兼容Forward compat当前版本 writer 写 → 旧版本 reader 读。测试矩阵由 tests/compat_fuse/test_cases.yaml 驱动每个用例字段如下字段说明writer写数据的 query 版本current表示最新构建reader读数据的 query 版本current表示最新构建meta按序运行的 meta-service 版本列表用于升级磁盘上的 meta 数据suitecompat-logictest/下的 sqllogictest 子目录新增用例只需向test_cases.yaml追加一条记录。运行方式# 跑全部用例CI 模式 python3 tests/compat_fuse/test_compat_fuse.py --run-all # 只打印用例不执行dry-run python3 tests/compat_fuse/test_compat_fuse.py --run-all --dry-run # 单用例本地调试指定 writer/reader/meta 版本与逻辑测试套件 python3 tests/compat_fuse/test_compat_fuse.py \ --writer-version 1.2.46 \ --reader-version current \ --meta-versions 1.2.527 1.2.677 1.2.833 \ --logictest-path base前置条件当前版本二进制必须放在./bins/current/bin/下包括databend-query、databend-meta、databend-sqllogictestsCI setup 动作会自动放置旧版本二进制由脚本自动下载。测试流程分三个阶段Write——用 meta 首版本 writer 版本 query 启动执行fuse_compat_write.testMeta upgrade——按序切换所有 meta 版本升级磁盘上的 meta 数据Read——用 meta 末版本 reader 版本 query 启动执行fuse_compat_read.test校验数据。每个compat-logictest/套件下固定包含两个 sqllogictest 文件fuse_compat_write.test建表写数据与fuse_compat_read.test读并校验。当前仓库中已有base、rbac_current、rbac_v1_2_311、revoke、udf等套件覆盖了从基础读写到 RBAC、UDF 的兼容面。六、长时运行测试tests/longrun/的并发与重负载验证6.1 目标与定位tests/longrun/README.md 明确指出长跑测试用于验证 Databend在并发与重负载下的数据正确性与性能典型场景包括并发大规模数据写入、表维护optimization、recluster、vacuum与查询并发执行。6.2 运行模型测试流程为三段式先执行_before.sh前置脚本再重复执行一组并发测试脚本最后执行_after.sh后置脚本做校验。所有事件日志都会写入 Databend 上的一个表中供后续分析Long Run │ ▼ Before Test Scripts │ ▼ Concurrent Test Scripts (Test Script 1 / 2 / 3 ... 并发) │ ▼ After Test Scripts6.3 运行命令与参数WAREHOUSE_DSNtarget databend warehouse dsn python3 longrun.py -d scripts directory -i concurrent test iteration number本地集群示例重复并发脚本 3 次WAREHOUSE_DSNdatabend://root:localhost:8000/?sslmodedisable python3 longrun.py -d ./example -i 3环境变量名称说明默认值WAREHOUSE_DSNDatabend warehouse 的 DSNdatabend://root:localhost:8000/?sslmodedisable命令行参数名称说明默认值必填-d, --directory长跑测试脚本目录—是-i, --iteration并发测试脚本的迭代次数—是--logger存放测试事件日志的目标表events否6.4 编写测试用例为用例创建目录如example可选在用例目录下建datagen/用于生成 DML 测试数据例如执行./example/datagen/gen.sh创建_before.sh——并发脚本执行前运行创建若干并发测试脚本如background.sh、dml.sh、sql.sh它们并发执行并按-i指定的次数重复创建_after.sh校验结果。当前仓库 tests/longrun/example/ 目录正是该规范的样板datagen/gen.sh生成数据_before.sh、_after.sh围住并发主体background.sh、dml.sh、sql.sh三个脚本构成并发负载。七、配套测试设施一览AGENTS.md 虽然只点名了六个目录但tests/下还有大量配套设施支撑上述测试体系理解它们有助于整体定位tests/databend-test无状态/有状态测试的实际执行入口runnertests/shell_env.sh测试环境的 shell 环境变量配置tests/helpers/client.py、native_client.py、uexpect.py等测试辅助客户端tests/suites/1_stateful/ 与3_stateful_iceberg/、3_stateful_paimon/、4_stateful_large_data/依赖外部数据源/服务的状态化测试与无状态测试区分明显tests/suites/5_ee/ 与7_management/企业版特性与运维管理类测试tests/fuzz/、tests/lineage/、tests/logging/、tests/metaverifier/、tests/task/、tests/udf/ 等分别覆盖模糊测试、血缘、日志、meta 校验、任务与 UDF 专项tests/cloud_control_server/cloud control 的模拟服务端含 protobuf 生成的 Python 桩tests/data/csv/、parquet/、ndjson/、avro/、orc/、arrow/、delta/、hive/等各格式测试数据。这套体系的层级设计——最小平台优先、就近 README、确定性输出、夹具可复现——正是 Databend 在持续演进的存储格式与版本矩阵下仍能保持高置信度测试覆盖的关键。八、实践建议如何遵循 AGENTS.md 落地一次测试改动综合全文一个符合 tests/AGENTS.md 精神的测试改动流程可以归纳为四步先选最小平台判断改动性质——纯 SQL 行为选 tests/suites/0_stateless/ 或 tests/sqllogictests/meta 类型变更选 tests/metactl/并运行update-metactl-test.sh刷新夹具涉及集群/跨版本/存储格式/长时运行才动用meta-cluster、compat、compat_fuse、longrun四类重量级设施就近读文档进入目录后先读最近的 README如 stateless 规范、sqllogictests 说明确认文件布局与 runner 工作流遵守命名与格式stateless 用例遵循xx_yyyy_[test_name]命名并成对提交.sql/.resultsqllogictest 用例遵循statement/query记录格式善用--runglob 定向执行与--complete自动补全保证确定性与可复现保持期望输出确定性新增夹具或配置时同步补文档使任何后续维护者包括 Agent都能复现同样的验证路径。【免费下载链接】databendData Agent Ready Warehouse : One for Analytics, Search, AI, Python Sandbox. — rebuilt from scratch. Unified architecture on your S3.项目地址: https://gitcode.com/GitHub_Trending/da/databend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考