Catch2 贡献指南：测试分层、构建流程与编码规范实战详解

人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载本指南以仓库内置的 Catch2 测试框架位于third_party/clingo-sys/clingo/third_party/catch/作为 clingo 的第三方测试依赖引入的官方贡献文档为主体系统讲解为其提交代码的完整规范从 Git 协作流程、分层测试体系与一键构建命令到文档编写模板、C14 编码约束与CATCH_CONFIG扩展流程。读完本文你将能够按照官方标准为 Catch2 贡献 bug 修复与新特性并能在本地复现其全部测试链路SelfTest、Approval Tests、CTest 集成测试等。引言贡献什么都可以但先读规则Catch2 的维护者欢迎一切形式的贡献——无论是 bug 修复、新特性、对新编译器的支持还是文档修正问题报告、评论与疑问同样被重视。官方建议把提问放到 Discord 而不是 issue 跟踪器而代码库层面的贡献则应遵循本文所述的规范。这份指南覆盖四块核心内容Git 协作方式、测试变更、编写文档与编写代码并最终以行为准则CoC收尾。一、Git 协作规范分支、提交与合入节奏开发分支Catch2 的持续开发发生在devel分支面向 v3而 v2 版本的维护更新在v2.x分支上进行。这意味着任何新功能都应基于devel只有针对 v2 的缺陷修复才提交到v2.x。提交应当小而原子原子性一个提交在应用后代码库连同测试仍应像预期一样工作。即可独立回退、不影响整体可用性。小提交小且原子的提交让后续的bisect二分定位回归、revert回退等 git 历史操作更容易。提交 PR 时的两条硬性要求不要包含合并后的单文件发行包amalgamated distribution filesCatch2 通过generateAmalgamatedFiles.py生成extras/catch_amalgamated.cpp/catch_amalgamated.hpp这类聚合文件仓库中extras/目录下可确认提交 PR 时请勿把对这些文件的改动纳入 git 提交。回应 review 意见时不要立即 rebase/squash立即压缩提交会让审阅者难以追踪新增改动、拖慢合入节奏。正确做法是在分支上追加新提交仅在 MR 准备合入时才压缩。官方推荐用git commit --fixup或--squash创建新提交最后用git rebase --autosquash自动完成压缩。二、测试你的变更Catch2 的分层测试体系运行 Catch2 自身的测试依赖 Python3。Catch2 的测试分为多层全部由 CI 驱动执行层级载体说明单元测试SelfTest二进制最基础的测试层绝大多数新测试默认放在这里审批测试Approval Tests用特定 reporter 跑几乎全部SelfTest用例将输出与已知正确基线Baseline逐字节对比集成测试CTest无法写成普通单元测试的场景如验证随机排序测试用例且排序结果对子集不变通过 CTest 直接执行命令 成功/失败正则或委托给 Python 校验脚本可编译示例examples/小而自包含的代码片段演示 Catch2 某类特性的用法目前只要编译通过即视为通过ExtraTestsextras/之外的高成本测试运行或编译耗时长不适合每次 CI 都跑例如需要独立编译的编译期配置测试CMake 配置测试CMake 选项同名测试验证通过 CMake 选项设置 Catch2 编译期配置的行为构建基础测试basic-testspreset在 Catch2 根目录执行cmake -B basic-test-build -S . -DCMAKE_BUILD_TYPEDebug --preset basic-tests从仓库的 CMakePresets.json 可以看到basic-testspreset 的实质是仅开启CATCH_DEVELOPMENT_BUILDON即构建成本低的开发构建。按需开启各类测试通过 CMake 选项逐类启用-DCATCH_BUILD_EXAMPLESON # 启用 examples 编译示例 -DCATCH_BUILD_EXTRA_TESTSON # 启用高成本 ExtraTests -DCATCH_ENABLE_CONFIGURE_TESTSON # 启用 CMake 配置测试一键构建并运行全部测试all-testspresetall-tests继承basic-tests并额外开启CATCH_BUILD_EXAMPLES、CATCH_BUILD_EXTRA_TESTS、CATCH_BUILD_SURROGATES、CATCH_ENABLE_CONFIGURE_TESTS与CATCH_ENABLE_CMAKE_HELPER_TESTS见 CMakePresets.json。官方给出的完整流程Debug 模式构建并运行全部测试为# 1. 重新生成聚合发行文件部分测试基于它构建 ./tools/scripts/generateAmalgamatedFiles.py # 2. 配置全量测试构建 cmake -B debug-build -S . -DCMAKE_BUILD_TYPEDebug --preset all-tests # 3. 执行实际构建 cmake --build debug-build # 4. 用 CTest 运行测试 ctest -j 4 --output-on-failure -C Debug --test-dir debug-build以上命令与仓库中 buildAndTest.sh 的catch2-build-and-test代码片段完全一致可直接运行该脚本完成同样操作cd Catch2 ./tools/scripts/buildAndTest.shWindows 用户可使用同目录下的tools\scripts\buildAndTest.cmd。新测试的审批Approval流程如果你新增了测试大概率会看到ApprovalTests失败——这是正常的因为新输出与基线不同。确认输出差异符合预期后运行tools/scripts/approve.py将新输出确认为基线并把基线变更一并提交。三、编写文档的规范为 Catch2 新增特性必须有文档否则其他用户无法使用。官方文档规范分为技术细节与内容建议两部分。技术细节新文档模板新页面应使用固定模板提供页面顶部锚点#top及返回文档首页的反链a idtop/a # Cool feature [Introduced](https://github.com/catchorg/Catch2/pull/123456) in Catch2 X.Y.Z Text that explains how to use the cool feature. --- [Home](https://link.gitcode.com/i/73272e13e5eeb01b0dfb26ba91008ee6)此处 PR 链接仅示意实际编写时替换为对应 issue/PR 地址。跨页链接链接到其他页面时应指向其top锚点形如[link to contributing](https://link.gitcode.com/i/a956110d1f044cf9c34aeb43dbe863a2)。版本标签文档需标记特性的引入版本新写文档使用占位符发布时替换为真实版本。两种风格小节标题后 Introduced in Catch2 X.Y.Z子部分如列表项内 X (Y and Z) was introduced in Catch2 X.Y.Z目录ToC超过 4 个子标题的页面须在顶部提供目录。由于 GitHub Markdown 不支持自动生成 ToC需半手动维护新增子标题后手动或在scripts/目录下运行updateDocumentToC.py仓库实际位于 tools/scripts/updateDocumentToC.py更新。内容建议示例宜短行内代码片段保持简短以免降低可读性更复杂、可编译的示例应新增.cpp文件放入examples/目录。敢于开新页现有文档偏长部分是历史遗留不必在过长的旧页面上硬塞内容。风格一致在已有页面上增补信息时格式与行文应与该页其余部分保持一致。面向三类读者初学者需要更贴近的用法指导、进阶用户想自定义用法、专家需要完整能力参考文档应尽量兼顾。四、编写代码的规范C 标准版本C14 为底线Catch2 目前以C14 为最低支持版本更高标准的特性仅在收益明显超过维护成本时克制地使用。文档给出了正反两例好的 polyfill 示例对conjunction的处理——可用时用std::conjunction否则提供自有实现。维护面很小且std::conjunction能直接用编译器内建函数编译收益显著。坏的 polyfill 示例在字符串化实现里同时维护两套模板元编程一套 C14 兼容 TMP、一套 C17if constexpr。尽管 C17 版本编译更快但维护成本过高得不偿失。格式化clang-format 只作用于新改代码Catch2 提供自己的clang-format配置但目前无法用 clang-format 完整还原现有 Catch2 格式对整文件重排会产生巨大 diff。因此只对新修改的代码运行 clang-format保持 diff 规模可控。需要警惕的代码构造这部分列出的问题构造很不幸地不完整且不一定被 CI 捕获需要贡献者自觉裸异常与异常相关函数抛异常必须通过internal/catch_enforce.hpp中的CATCH_ERROR或CATCH_RUNTIME_ERROR宏。从源码catch_enforce.hpp可见其内部根据CATCH_CONFIG_DISABLE_EXCEPTIONS区分编译路径统一处理启用/禁用异常两种编译模式。某些平台如 IAR对std::current_exception这类异常相关函数也有问题如确需使用应放在CATCH_CONFIG_DISABLE_EXCEPTIONS宏之后。避免std::move与std::forward它们本质上是特定static_cast的语义化名称但作为函数模板编译开销惊人在低优化级别构建下还有负面性能影响。应改用 catch_move_and_forward.hpp 中的CATCH_MOVE/CATCH_FORWARD宏其实现直接展开为对应static_cast避开函数模板开销#define CATCH_MOVE(...) static_caststd::remove_reference_tdecltype(__VA_ARGS__)(__VA_ARGS__) #define CATCH_FORWARD(...) static_castdecltype(__VA_ARGS__)(__VA_ARGS__)C 标准库函数必须限定调用使用 C stdlib 函数时应以cfoo形式包含头文件并限定调用如std::printf。两者没区别的常识是错的——QNX 与 VxWorks 上若以cfoo包含头文件却不限定调用将无法编译。为 Catch2 类型声明用户自定义字面量UDL的写法受-Wreserved-identifier在 Clang 上的不理想实现影响应避免Approx operator _a(long double);这种在与后缀之间有空格的声明改为无空格写法Approx operator _a(long double);新源文件模板每个新源文件必须以许可头开始// Copyright Catch2 Authors // Distributed under the Boost Software License, Version 1.0. // (See accompanying file LICENSE.txt or copy at // https://www.boost.org/LICENSE_1_0.txt) // SPDX-License-Identifier: BSL-1.0头文件的 include guard 遵循{FILENAME}_INCLUDED模式catch_matchers_foo.hpp对应CATCH_MATCHERS_FOO_HPP_INCLUDEDcatch_generators_bar.hpp对应CATCH_GENERATORS_BAR_HPP_INCLUDED以此类推。新增CATCH_CONFIG选项的完整流程新增编译期配置选项需要同时改动多处官方清单如下文件作用CMake/CatchConfigOptions.cmake生成 CMake 配置选项供 CMake 前端感知仓库中 CatchConfigOptions.cmake 通过AddOverridableConfigOption/AddConfigOption宏批量声明CATCH_CONFIG_*与CATCH_CONFIG_NO_*选项如CATCH_CONFIG_DISABLE_EXCEPTIONS、CATCH_CONFIG_FAST_COMPILE等默认全部 OFF交给 Catch2 自动探测docs/configuration.md在文档中说明该选项src/catch2/catch_user_config.hpp.in配置模板用于生成物化的catch_user_config.hpp仓库中该模板用#cmakedefine逐项生成宏定义并对正反选项同时定义的情况给出编译期检测BUILD.bazelBazel 不支持 CMake 式配置所有展开需手动处理见 BUILD.bazel其他按需文件如catch2/internal/catch_config_foo.hpp承载守卫配置的逻辑五、行为准则与结语本项目有 行为准则CoC贡献期间请遵守。Catch2 官方文档自述永远处于进行中状态——随着新信息的出现会持续更新因此这份指南也应被当作活文档对待。回到本仓库的实践视角Catch2 以第三方依赖形式存在于 third_party/clingo-sys/clingo/third_party/catch/其SelfTest单元测试、CTest 集成测试与 Approval 基线对比的分层测试思想以及CATCH_MOVE/CATCH_FORWARD宏避免编译开销、CATCH_ERROR宏统一异常处理路径等工程技巧都可作为阅读与借鉴对象——无论是向上游提交补丁还是在本项目内复用其测试组织方式这份规范都提供了清晰可执行的标准。赞分享人工智能AI Agent多模态语音AI 应用【免费下载链接】ten-frameworkOpen-source framework for conversational voice AI agents项目地址https://gitcode.com/TEN-framework/ten-framework点击查看免费下载相关推荐brpc 开源贡献实战指南构建、测试、代码规范与 CI 全流程详解brpc 开源贡献实战指南构建、测试、代码规范与 CI 全流程详解 本文基于 brpc 仓库根目录下的贡献者指南 AGENTS.md https://link后端RPC框架通信网络JUnit 4 贡献指南详解构建流程、编码规范与 Pull Request 提交流程JUnit 4 贡献指南详解构建流程、编码规范与 Pull Request 提交流程 本指南以仓库根目录的 CONTRIBUTING.md https://l测试开发工具Codon 贡献指南开发工作流、编码规范与测试编写实战Codon 贡献指南开发工作流、编码规范与测试编写实战 本文是 Codon 编译器项目A high performance, zero overhead,编译器编程语言语言运行时上一篇MicroK8s集群监控终极指南Grafana仪表盘自定义与智能告警配置下一篇WMPFDebugger源码解析深入理解RemoteDebug协议转换机制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考