Catch2 自定义 main() 完全指南：用 Session API 接管测试运行器与扩展 Clara 命令行

Catch2 默认会为测试可执行文件生成一个 main 函数，自动完成命令行参数解析与测试运行；但在某些场景下（如需要在测试前后执行资源初始化/清理、程序化修改测试配置、或为测试程序增加自定义命令行选项），你需要自己编写 main。本文基于本仓库 vendored 的 Catch2 文档 own-main.md，结合仓库内实际源码（catch_session.hpp、catch_session.cpp、catch_main.cpp 及官方示例），系统讲解自定义 main 的三种典型方案、版本检测宏、构建链接方式与退出码语义，让你能够在自己的测试程序中完全掌控 Catch2 的运行流程。

Catch2 默认 main 是如何工作的

Catch2 最容易的使用方式是直接使用它自带的 main 函数：链接 Catch2Main 库（CMake 目标 Catch2::Catch2WithMain，产物名为 Catch2Main，见 src/CMakeLists.txt）或 pkg-config 文件即可。默认 main 的实现位于 catch_main.cpp：

int main (int argc, char * argv[]) {
    // We want to force the linker not to discard the global variable
    // and its constructor, as it (optionally) registers leak detector
    (void)&Catch::leakDetector;
    return Catch::Session().run( argc, argv );
}

可以看到，默认 main 的核心只有一行：构造一个 Catch::Session 实例并调用 run(argc, argv)。Session 类的完整接口定义在 catch_session.hpp，其中关键的公开方法包括：

方法	作用
int applyCommandLine(int argc, char const* const* argv)	用 Clara 解析命令行参数，出错时返回非零值（解析失败返回 UnspecifiedErrorExitCode = 1）
int run(int argc, CharT const* const argv[])	模板重载：先 applyCommandLine，成功后再调用无参 run()
int run()	真正执行测试运行流程
ConfigData& configData()	返回配置数据结构的引用，可在不同时机读写配置
Config& config()	返回已构造的 Config 对象（惰性构造，见 catch_session.cpp）
Clara::Parser const& cli() const / void cli(Clara::Parser const&)	获取或替换 Catch2 内置的命令行解析器
void useConfigData(ConfigData const&)	整体替换配置数据并重建 Config

Session 继承自 Detail::NonCopyable，且构造函数内部通过静态变量检查强制"同一进程只允许一个 Catch::Session 实例"，违反会触发内部错误（见 catch_session.cpp）。因此在自定义 main 时，请确保只构造一个 Session。

方案一：让 Catch2 全权处理参数与配置

如果你只是需要在测试运行之前/之后插入一段自己的代码，这是最简单的方案：

#include <catch2/catch_session.hpp>

int main( int argc, char* argv[] ) {
  // your setup ...

  int result = Catch::Session().run( argc, argv );

  // your clean-up...

  return result;
}

Catch::Session().run(argc, argv) 内部等价于"解析命令行 + 执行测试"两步（见 catch_session.hpp）：

template<typename CharT>
int run(int argc, CharT const * const argv[]) {
    if (m_startupExceptions)
        return 1;
    int returnCode = applyCommandLine(argc, argv);
    if (returnCode == 0)
        returnCode = run();
    return returnCode;
}

即：命令行解析失败时直接返回错误码，不会运行任何测试。这种写法下，setup/clean-up 代码在解析参数与运行测试的"前后"执行，适合加载外部配置、初始化资源句柄、统一收尾等场景。

更轻量的替代方案：文档明确提示——如果只是想在测试运行前做一些准备工作，使用 事件监听器（event listeners） 往往比自定义 main 更简单，不需要接触命令行解析层。

方案二：程序化修改 Catch2 配置

如果希望 Catch2 正常处理命令行参数，同时又想以编程方式修改运行配置，可以分两个时机写入配置：

int main( int argc, char* argv[] ) {
  Catch::Session session; // There must be exactly one instance

  // writing to session.configData() here sets defaults
  // this is the preferred way to set them

  int returnCode = session.applyCommandLine( argc, argv );
  if( returnCode != 0 ) // Indicates a command line error
        return returnCode;

  // writing to session.configData() or session.Config() here
  // overrides command line args
  // only do this if you know you need to

  int numFailed = session.run();

  // numFailed is clamped to 255 as some unices only use the lower 8 bits.
  // This clamping has already been applied, so just return it here
  // You can also do any post run clean-up here
  return numFailed;
}

关键时机语义：

• applyCommandLine 之前写 configData()：这些值作为默认值，会被命令行参数覆盖——这是官方推荐的设置默认值方式；
• applyCommandLine 之后写 configData() / config()：这些值作为最终强制值，覆盖命令行解析结果——仅在明确需要时使用；
• 如果希望完全控制配置：不要调用 applyCommandLine，直接修改 configData() 后调用 session.run() 即可。

配置数据在 run() 内部经 Config 对象落地生效：runInternal() 中通过 config() 强制构造 Config、seedRng(*m_config) 初始化随机数种子、getCurrentMutableContext().setConfig(m_config.get()) 把配置挂到全局上下文后，再创建 reporter 并执行测试（见 catch_session.cpp）。

关于返回码：注释中特别提醒，失败计数已钳制到 255（部分 Unix 系统只使用退出码低 8 位），因此直接返回即可。从 catch_session.cpp 可以看到 Catch2 定义了一组语义化的退出码常量：

常量	值	触发场景
UnspecifiedErrorExitCode	1	命令行解析错误、运行时未捕获异常、shard 参数非法等
NoTestsRunExitCode	2	没有运行任何测试且未开启 zero-tests-ok
UnmatchedTestSpecExitCode	3	存在未匹配任何测试的 spec，且开启了 -w UnmatchedTestSpec 警告
AllTestsSkippedExitCode	4	所有测试均被跳过且未开启 zero-tests-ok
InvalidTestSpecExitCode	5	存在非法测试 spec
TestFailureExitCode	42	存在失败的断言

方案三：添加你自己的命令行选项

Catch2 的命令行解析器名为 Clara（仓库内 Catch::Clara 命名空间）。你可以在 Catch2 预置解析器之上组合出自己的 CLI，挂接任意自定义变量：

int main( int argc, char* argv[] ) {
  Catch::Session session; // There must be exactly one instance

  int height = 0; // Some user variable you want to be able to set

  // Build a new parser on top of Catch2's
  using namespace Catch::Clara;
  auto cli
    = session.cli()           // Get Catch2's command line parser
    | Opt( height, "height" ) // bind variable to a new option, with a hint string
        ["-g"]["--height"]    // the option names it will respond to
        ("how high?");        // description string for the help output

  // Now pass the new composite back to Catch2 so it uses that
  session.cli( cli );

  // Let Catch2 (using Clara) parse the command line
  int returnCode = session.applyCommandLine( argc, argv );
  if( returnCode != 0 ) // Indicates a command line error
      return returnCode;

  // if set on the command line then 'height' is now set at this point
  if( height > 0 )
      std::cout << "height: " << height << std::endl;

  return session.run();
}

要点拆解：

1. session.cli() 取出 Catch2 预置的 Clara 解析器（内部由 makeCommandLineParser(m_configData) 构造，见 catch_session.cpp）；
2. 用 Clara 的 Opt 绑定自定义变量：Opt(variable, "hint") 绑定变量与帮助提示字符串，["-g"]["--height"] 声明短/长选项名，("how high?") 是 -?/--help 输出中的描述；
3. 用 | 运算符把新选项组合进原有解析器，再通过 session.cli(cli) 交还给 Catch2（对应源码中的 void cli(Clara::Parser const& newParser)，见 catch_session.hpp）；
4. applyCommandLine 解析成功后，绑定变量即为命令行传入值。

该模式与仓库内置示例 examples/232-Cfg-CustomMain.cpp 完全一致（该示例只声明了 --height 长选项，未声明 -g 短选项），可以作为可编译的参考样板。

版本检测

Catch2 提供一组宏用于获取头文件对应版本号：

• CATCH_VERSION_MAJOR
• CATCH_VERSION_MINOR
• CATCH_VERSION_PATCH

它们各自展开为对应版本段的单个整数。文档给出的例子是单头文件版本 v2.3.4 时分别展开为 2、3、4；在当前仓库中，宏定义位于 catch_version_macros.hpp，实际展开值为 CATCH_VERSION_MAJOR=3、CATCH_VERSION_MINOR=8、CATCH_VERSION_PATCH=0（即 Catch2 3.8.0）。这些宏可用于编译期判断版本特性，例如根据大版本分支选择不同的 API 调用方式。

构建链接：Catch2 与 Catch2WithMain 目标的选择

是否自定义 main 直接决定你该链接哪个 CMake 目标（详见 cmake-integration.md）：

• 使用默认 main：链接 Catch2::Catch2WithMain（底层库产物为 Catch2Main，定义见 src/CMakeLists.txt）；
• 自定义 main：只链接静态库目标 Catch2::Catch2，自行编写 main 并手动调用测试运行器。

链接到无 main 的 Catch2 目标时，你的翻译单元只需 #include <catch2/catch_session.hpp> 即可访问 Catch::Session、Catch::Clara 等接口；如需组合其他测试能力（宏、断言等），可同时包含 catch_all.hpp。另外，如果使用 amalgamated（合并单文件）版本，可以通过定义 CATCH_AMALGAMATED_CUSTOM_MAIN 让其中内置的 main 失效，转而提供自己的 main（见 catch_main.cpp）。

平台与宽字符注意事项

在 Windows + UNICODE 环境下，Session 额外提供了 applyCommandLine(int argc, wchar_t const* const* argv) 重载（见 catch_session.hpp），其实现会把宽字符参数转换为 UTF-8 后再走统一解析流程（见 catch_session.cpp）。默认 main 在 CATCH_CONFIG_WCHAR && CATCH_PLATFORM_WINDOWS && _UNICODE 时也会选择 wmain 入口（见 catch_main.cpp）。如果你的自定义 main 需要在 Windows 上接收宽字符参数，可以直接调用该重载，无需自行做编码转换。

小结：三种方案的取舍

方案	适用场景	关键 API
Session().run(argc, argv)	仅在测试前后执行自定义逻辑	Session::run
修改配置	需要程序化控制测试配置（默认值 / 强制覆盖）	configData()、applyCommandLine、config()
扩展 CLI	需要为测试程序增加自定义命令行选项	cli()、cli(newParser)、Catch::Clara::Opt

无论选择哪种方式，核心都是通过 catch_session.hpp 暴露的 Session 单实例 API 与 Catch2 内置运行器交互；结合本文给出的退出码语义表与 CMake 链接方式，即可在保持 Catch2 完整命令行能力的同时，将测试程序的主入口完全掌握在自己手中。完整示例可参考 examples/232-Cfg-CustomMain.cpp，入门级用法见 tutorial.md。