TiDB Dumpling 集成测试框架指南：从 AGENTS.md 到 `make dumpling_integration_test` 的完整实践

TiDB Dumpling 集成测试框架指南从 AGENTS.md 到make dumpling_integration_test的完整实践【免费下载链接】tidbTiDB is built for agentic workloads that grow unpredictably, with ACID guarantees and native support for transactions, analytics, and vector search. No data silos. No noisy neighbors. No infrastructure ceiling.项目地址: https://gitcode.com/GitHub_Trending/ti/tidbDumpling 是 TiDB 生态中面向数据导出的工具其集成测试分布在dumpling/tests/**目录下。本篇文章以仓库中的 dumpling/tests/AGENTS.md 为骨架结合 dumpling/tests/run.sh、dumpling/tests/_utils/测试工具库以及 Makefile 中的真实 target 定义系统讲解 Dumpling 集成测试的目录约定、测试用例编写规范、双数据库TiDB/MySQL端口切换策略、运行方式与验证流程。读完本文你将能够独立读懂现有用例、为新的 Dumpling 行为编写高质量集成测试并在本地或 CI 中精准地跑通单个或多个测试用例。一、AGENTS.md 在 Dumpling 测试中的作用仓库根目录的 AGENTS.md 定义了全局的开发与协作约定而dumpling/tests/AGENTS.md是对其的路径级补充只针对dumpling/tests/**下的集成测试提供更具体的指导。它主要回答三个问题新测试应该放在哪里Test Placement编写用例时应该使用哪些工具函数Harness Helpers如何选择测试目标端口、如何运行与验证Ports and Services / Running Tests / Validation Notes。因此任何修改 Dumpling 集成测试的提交都应同时满足根级 AGENTS.md 与本路径级文档的要求。二、测试放置原则先扩展再新建关于用例的物理位置文档给出了明确的三条纪律优先扩展就近的既有用例。如果dumpling/tests/case/run.sh中已经存在与待测行为最接近的用例应优先在其中追加测试块而不是新建目录。例如 dumpling/tests/basic/run.sh 一个文件里就串行了简单表导出、WHERE 过滤、分区表、OR WHERE、--sql 选项、sequence、一致性锁、网络用量记录、文件关闭失败重试等十余个测试块正是就近扩展的典型实践。新用例只聚焦一个 Dumpling 行为或工作流。避免在共享用例中做宽泛的环境改动除非被测行为本身要求如此。这保证了每个用例的失败都能快速定位到单一功能点。使用确定性数据与精确断言。构造表数据时用固定的值如insert values (1), (2)断言时直接对$DUMPLING_OUTPUT_DIR下生成的文件做精确匹配而不是依赖统计或随机数据。此外每个测试块都要自行准备并清理它所依赖的库表状态不得依赖同脚本中前面测试块遗留的状态。以 dumpling/tests/basic/run.sh 为例每个块开头都先drop database if exists再重建正是这一原则的落地run_sql drop database if exists \$DB_NAME\; run_sql create database \$DB_NAME\ DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_bin; run_sql create table \$DB_NAME\.\$TABLE_NAME\ (a int); run_sql insert into \$DB_NAME\.\$TABLE_NAME\ values (1), (2);三、Harness Helpers测试框架提供的工具函数所有 Dumpling 集成测试都运行在一个 shell 测试框架harness之上。框架把可复用的操作封装成了放在 dumpling/tests/_utils/ 下的若干脚本用例脚本通过把该目录加入PATH后直接以命令形式调用。文档规定工具用途底层实现run_sql对源数据库执行 SQL 语句用于建表、插数据与结果断言见 dumpling/tests/_utils/run_sqlrun_dumpling调用bin/dumpling执行导出避免直接调用二进制见 dumpling/tests/_utils/run_dumplingfile_should_exist断言输出目录下某文件存在见 dumpling/tests/_utils/file_should_existfile_not_exist断言输出目录下某文件不存在见 dumpling/tests/_utils/file_not_exist3.1 run_sqlSQL 设置与断言dumpling/tests/_utils/run_sql 本质是对mysql客户端的薄封装mysql -u $DUMPLING_TEST_USER -h 127.0.0.1 -P $DUMPLING_TEST_PORT \ --default-character-setutf8mb4 --database$DUMPLING_TEST_DATABASE \ -E -e $SQL $它从环境变量读取连接参数DUMPLING_TEST_USER默认root、DUMPLING_TEST_PORT目标端口、DUMPLING_TEST_DATABASE默认库并以-E垂直输出执行 SQL便于 grep 断言。这也是SQL 设置与断言都要走run_sql的原因端口切换只需改变量无需改动调用方。3.2 run_dumpling导出调用dumpling/tests/_utils/run_dumpling 封装了 Dumpling 调用bin/dumpling -u $DUMPLING_TEST_USER -h 127.0.0.1 \ -P $DUMPLING_TEST_PORT -B $DUMPLING_TEST_DATABASE \ -o $DUMPLING_OUTPUT_DIR $它自动注入用户名、主机、端口、数据库与输出目录并把用例传入的额外参数如-f、--where、--rows原样透传给bin/dumpling。文档强调不要直接调用bin/dumpling除非该测试本身就是针对这个 helper 或命令包装器的。3.3 文件存在性断言file_should_exist文件不存在则打印错误并exit 1file_not_exist文件存在则打印错误并exit 1。两者配合可用于验证分片数量是否符合预期。例如 dumpling/tests/basic/run.sh 中seq 1 8 | xargs -I\? file_not_exist ...断言中间 8 个分片文件不存在从而证明--where b 4 or b 95配合--rows 10只产出了首尾两个分片。3.4 对输出文件的断言技巧文档建议在$DUMPLING_OUTPUT_DIR下检查导出的 SQL/CSV且grep / cut 的粒度要足够窄让断言恰好证明被测行为。例如 dumpling/tests/basic/run.sh 用grep -w (.*) ... | wc -l统计行数精确等于 2同文件 L38-L41 则用cut -c2-2提取每个 INSERT 行的首列并逐一比对seq 3 9。四、端口与服务4000 与 3306 的分工测试框架同时支持两个目标服务通过DUMPLING_TEST_PORT切换DUMPLING_TEST_PORT4000指向由测试框架自己启动的 TiDB server。用于验证 TiDB 专属特性以及受 TiDB 版本门控的行为。DUMPLING_TEST_PORT3306指向框架预期的外部 MySQL 服务。仅用于 MySQL 兼容性覆盖或既有用例中有意对比 MySQL 行为时。两条重要纪律每次切换端口都要显式设置。不能在脚本开头设一次就默认后续块沿用。参考 dumpling/tests/basic/run.sh 中的反复切换分区表测试前export DUMPLING_TEST_PORT4000L44OR WHERE 测试前切回3306L59sequence 测试又切回4000L121。版本解析依赖 Git 上下文。如果用例依赖 TiDB 版本解析如对版本做门控必须确认本地或 CI 中的bin/tidb-server是从带有足够 Git tag/history 的 checkout构建的因为 Dumpling 用git describe --tags生成 semver 形状的发布串。浅克隆或没有 tag 的 checkout 会让 Dumpling 把 TiDB 识别为0.0.0导致版本门控行为走错分支。4.1 框架如何拉起 TiDBdumpling/tests/_utils/run_services 展示了4000端口的服务从何而来它生成一套临时 TLS 证书写出tidb.toml监听port 4000状态端口10080开启enable-table-lock并配置 SSL然后后台启动bin/tidb-server --config ...最后通过curl http://127.0.0.1:10080/status轮询等待就绪。而入口脚本 dumpling/tests/run.sh 默认export DUMPLING_TEST_PORT3306即默认把断言打在 MySQL 上。4.2 默认输出目录dumpling/tests/run.sh 定义了核心环境变量DUMPLING_TEST_DIR${DUMPLING_TEST_DIR:-/tmp/dumpling_test_result} DUMPLING_TEST_USER${DUMPLING_TEST_USER:-root}每个用例的输出目录DUMPLING_OUTPUT_DIR由run_case_by_fullpath动态计算为$DUMPLING_TEST_DIR/sql_res.TEST_NAME并用完即清。用例脚本可直接引用这些变量无需自行推导路径。五、运行测试从构建到执行所有命令都从仓库根目录执行。5.1 构建 TiDB servermake server当框架需要 TiDB 服务4000端口时需要存在bin/tidb-server二进制make server负责构建它。5.2 运行全部 Dumpling 集成用例make dumpling_integration_test该 target 在 Makefile 中定义为dumpling_integration_test: dumpling_bins failpoint-enable make build_dumpling make failpoint-disable ./dumpling/tests/run.sh $(CASE)它会先构建 Dumpling 二进制再调用 dumpling/tests/run.sh未传CASE时run.sh 遍历dumpling/tests/*/run.sh执行全部用例。5.3 运行单个用例CASEbasic make dumpling_integration_testrun.sh 收到参数后构造dumpling/tests/$test_case/run.sh并执行run.sh L52-L64同时按用例名生成独立的DUMPLING_OUTPUT_DIR。5.4 带 shell 追踪运行VERBOSEtrue CASEbasic make dumpling_integration_test当VERBOSEtrue时run.sh 会以bash -x方式运行用例脚本并开启PS4追踪显示源文件与行号、函数名便于排查 shell 脚本中的变量展开与分支走向run.sh L40-L47。5.5 前置二进制检查dumpling_integration_test依赖dumpling_binsMakefile L646-L649运行前需要以下二进制就位bin/tidb-serverTiDB 服务bin/minio对象存储模拟供 S3 相关用例bin/mcMinIO 客户端bin/tidb-lightning导入工具供 light 相关用例bin/sync_diff_inspector数据一致性校验工具——注意路径中的分隔符是下划线sync_diff_inspector拼写错误会导致检查失败此外完整框架还要求本机存在mysql客户端并在127.0.0.1:3306上有本地 MySQL 兼容服务供针对 MySQL 的用例使用。这些检查在 dumpling/tests/run.sh L20-L23 中通过file_should_exist逐一完成。六、验证注意事项小改动如何自测对于仅涉及 shell 的改动验证策略分三档首选完整目标本地前置条件齐备时直接运行CASEcase make dumpling_integration_test跑被改动的用例。聚焦复现如果同一用例脚本中其他测试块依赖本地没有的服务如 MySQL可以先用只针对 TiDB 的最小复现脚本迭代但必须如实报告官方用例 target 未完整运行不能冒充全量通过。构建元数据make bazel_prepare对仅改动 Dumpling shell 集成测试或本文件的场景不是必需的只有同时改动了 Go 文件、Bazel 元数据或 module 文件时才需要回到根级 AGENTS.md 按全局流程执行。七、源码级剖析一个真实用例的完整生命周期以 dumpling/tests/basic/run.sh 为样本可以完整串联上述所有约定准备run_sql建库建表插入确定性数据导出run_dumpling -f $DB_NAME.$TABLE_NAME -L ${DUMPLING_OUTPUT_DIR}/dumpling.log调用框架封装的导出并把日志写到输出目录断言对$DUMPLING_OUTPUT_DIR/${DB_NAME}.${TABLE_NAME}.000000000.sql做精确 grep/cut 断言错误路径测试用set e/set -e包裹预期失败的调用再对日志 grep 特定错误串如unsupported config.FileType sql when we specify --sql确认报错而非 panicFailpoint 注入借助GO_FAILPOINTS注入失败路径如PrintTiDBMemQuotaQuery、FailToCloseDataFile验证 Dumpling 的日志输出、重试与失败上报行为收尾下一个测试块重新drop database不依赖上一块残留状态。其中run_dumpling的-L日志参数与GO_FAILPOINTS的配合是理解 Dumpling 可观测性设计版本 banner、tidb_mem_quota_query打印、IOTotalBytes网络用量统计最直接的窗口而FailToCloseDataFile1*return后依然出现dump data successfully、5*return后出现dump failed error stack info的对比则实证了 Dumpling 对写文件失败的重试机制。这些都属于 AGENTS.md 所强调的精确断言在实战中的高阶形态。八、总结把约定固化为习惯Dumpling 集成测试框架的设计哲学可以浓缩为四句话就近扩展优先在dumpling/tests/case/run.sh内追加测试块保持用例聚焦单一行为工具化所有 SQL、导出、文件检查都走 dumpling/tests/_utils/ 下的 harness helpers不直接裸调二进制显式端口4000框架自启 TiDB与3306外部 MySQL每次使用前显式设置且注意版本解析对 Git tag 的依赖精确验证改动 shell 用例用CASEcase make dumpling_integration_test验证改动 Go/Bazel 文件则补齐根级 AGENTS.md 要求。理解了这些约定你既可以快速定位任一 Dumpling 行为对应哪个用例文件也能以最小成本为新增功能补上符合社区标准的集成测试。【免费下载链接】tidbTiDB is built for agentic workloads that grow unpredictably, with ACID guarantees and native support for transactions, analytics, and vector search. No data silos. No noisy neighbors. No infrastructure ceiling.项目地址: https://gitcode.com/GitHub_Trending/ti/tidb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考