运行测试 {#run-tests}

Xmake 提供了内置的 xmake test 命令用于运行单元测试和测试用例。从 v2.8.5 版本开始，你可以通过 add_tests 在需要测试的目标上配置测试用例，然后自动执行所有测试。

这为自动化测试提供了极大的便利，即使目标被设置为 set_default(false)，xmake 在执行测试时仍会自动编译它，然后运行所有测试。

命令格式

$ xmake test [options] [target/testname]

基本用法

配置测试用例

首先，我们需要使用 add_tests 为目标配置测试用例：

add_rules("mode.debug", "mode.release")

for _, file in ipairs(os.files("src/test_*.cpp")) do
    local name = path.basename(file)
    target(name)
        set_kind("binary")
        set_default(false)
        add_files("src/" .. name .. ".cpp")
        add_tests("default")
        add_tests("args", {runargs = {"foo", "bar"}})
        add_tests("pass_output", {trim_output = true, runargs = "foo", pass_outputs = "hello foo"})
        add_tests("fail_output", {fail_outputs = {"hello2 .*", "hello xmake"}})
end

:::tip 详细 API 关于 add_tests 的完整参数和使用说明，请参考：add_tests 接口文档 :::

运行所有测试

只需执行 xmake test 即可运行所有配置的测试用例：

$ xmake test
running tests ...
[  2%]: test_1/args        .................................... passed 7.000s
[  5%]: test_1/default     .................................... passed 5.000s
[  8%]: test_1/fail_output .................................... passed 5.000s
[ 11%]: test_1/pass_output .................................... passed 6.000s
[ 13%]: test_2/args        .................................... passed 7.000s
[ 16%]: test_2/default     .................................... passed 6.000s
[ 19%]: test_2/fail_output .................................... passed 6.000s
[ 22%]: test_2/pass_output .................................... passed 6.000s
[ 25%]: test_3/args        .................................... passed 7.000s
[ 27%]: test_3/default     .................................... passed 7.000s
[ 30%]: test_3/fail_output .................................... passed 6.000s
[ 33%]: test_3/pass_output .................................... passed 6.000s
[ 36%]: test_4/args        .................................... passed 6.000s
[ 38%]: test_4/default     .................................... passed 6.000s
[ 41%]: test_4/fail_output .................................... passed 5.000s
[ 44%]: test_4/pass_output .................................... passed 6.000s
[ 47%]: test_5/args        .................................... passed 5.000s
[ 50%]: test_5/default     .................................... passed 6.000s
[ 52%]: test_5/fail_output .................................... failed 6.000s
[ 55%]: test_5/pass_output .................................... failed 5.000s
[ 58%]: test_6/args        .................................... passed 7.000s
[ 61%]: test_6/default     .................................... passed 6.000s
[ 63%]: test_6/fail_output .................................... passed 6.000s
[ 66%]: test_6/pass_output .................................... passed 6.000s
[ 69%]: test_7/args        .................................... failed 6.000s
[ 72%]: test_7/default     .................................... failed 7.000s
[ 75%]: test_7/fail_output .................................... failed 6.000s
[ 77%]: test_7/pass_output .................................... failed 5.000s
[ 80%]: test_8/args        .................................... passed 7.000s
[ 83%]: test_8/default     .................................... passed 6.000s
[ 86%]: test_8/fail_output .................................... passed 6.000s
[ 88%]: test_8/pass_output .................................... failed 5.000s
[ 91%]: test_9/args        .................................... passed 6.000s
[ 94%]: test_9/default     .................................... passed 6.000s
[ 97%]: test_9/fail_output .................................... passed 6.000s
[100%]: test_9/pass_output .................................... passed 6.000s

80% tests passed, 7 tests failed out of 36, spent 0.242s

运行指定的测试目标

你可以指定运行特定的测试：

$ xmake test targetname/testname

或者通过模式匹配运行一个目标的所有测试或批量测试：

$ xmake test targetname/*
$ xmake test targetname/foo*

你也可以运行所有目标中同名的测试：

$ xmake test */testname

测试配置选项

add_tests 支持以下配置参数：

参数	描述
`runargs`	测试运行参数字符串或数组
`runenvs`	测试运行环境变量表
`timeout`	测试超时时间（秒）
`trim_output`	是否修剪输出空白字符
`pass_outputs`	测试通过的预期输出模式
`fail_outputs`	应导致测试失败的输出模式
`build_should_pass`	测试应该构建成功
`build_should_fail`	测试应该构建失败
`files`	额外的测试文件编译
`defines`	测试编译的额外定义
`realtime_output`	实时显示测试输出

配置示例

带参数的测试

target("mytest")
    set_kind("binary")
    add_files("src/*.cpp")
    add_tests("with_args", {runargs = {"--verbose", "--mode=test"}})

:::tip 相关 API

set_runargs: 设置目标运行参数
set_rundir: 设置运行工作目录
add_runenvs: 添加运行环境变量 :::

带预期输出的测试

target("mytest")
    set_kind("binary")
    add_files("src/*.cpp")
    add_tests("output_test", {pass_outputs = ".*success.*", trim_output = true})

带超时的测试

target("mytest")
    set_kind("binary")
    add_files("src/*.cpp")
    add_tests("timeout_test", {timeout = 5}) -- 5秒超时

带环境变量的测试

target("mytest")
    set_kind("binary")
    add_files("src/*.cpp")
    add_tests("env_test", {runenvs = {TEST_MODE = "1", DEBUG = "true"}})

:::tip 相关 API

add_runenvs: 添加运行环境变量
set_runenv: 设置运行环境变量 :::

构建失败测试

target("compile_fail_test")
    set_kind("binary")
    add_files("src/invalid.cpp")
    add_tests("should_fail", {build_should_fail = true})

:::tip 相关 API

set_default: 设置目标默认构建
set_kind: 设置目标类型 :::

添加额外代码文件

add_tests 支持通过 files 参数添加额外的代码文件进行编译，这对于单元测试非常有用：

target("mytest")
    set_kind("binary")
    add_files("src/*.cpp")
    add_tests("test_with_stub", {
        files = "tests/stub_*.cpp",  -- 添加额外的测试文件
        defines = "TEST_MODE",
        remove_files = "src/main.cpp"  -- 移除不需要的文件
    })

:::tip 使用场景

单元测试：添加测试代码文件而不修改原始源码
桩代码：为测试提供模拟的实现
条件编译：通过 defines 添加测试特定的宏定义
文件替换：使用 remove_files 移除不需要的文件（如 main.cpp） :::

以 doctest 为例，可以在不修改任何 main.cpp 的情况下外置单元测试：

target("doctest")
    set_kind("binary")
    add_files("src/*.cpp")
    for _, testfile in ipairs(os.files("tests/*.cpp")) do
        add_tests(path.basename(testfile), {
            files = testfile,
            remove_files = "src/main.cpp",
            languages = "c++11",
            defines = "DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN"
        })
    end
end

集成第三方测试框架

xmake test 可以很好地集成 doctest、gtest 等第三方测试框架，实现更强大的测试功能。

doctest 集成示例

add_rules("mode.debug", "mode.release")
add_requires("doctest")

target("doctest")
    set_kind("binary")
    add_files("src/*.cpp")
    for _, testfile in ipairs(os.files("tests/*.cpp")) do
        add_tests(path.basename(testfile), {
            files = testfile,
            remove_files = "src/main.cpp",
            languages = "c++11",
            packages = "doctest",  -- 集成 doctest 包
            defines = "DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN"
        })
    end

测试文件示例 (tests/test_1.cpp)：

#include "doctest/doctest.h"

static int factorial(int number) {
    return number <= 1 ? number : factorial(number - 1) * number;
}

TEST_CASE("testing the factorial function") {
    CHECK(factorial(1) == 1);
    CHECK(factorial(2) == 2);
    CHECK(factorial(3) == 6);
    CHECK(factorial(10) == 3628800);
}

gtest 集成示例

add_rules("mode.debug", "mode.release")
add_requires("gtest")

target("mytest")
    set_kind("binary")
    add_files("src/*.cpp")
    for _, testfile in ipairs(os.files("tests/*.cpp")) do
        add_tests(path.basename(testfile), {
            files = testfile,
            remove_files = "src/main.cpp",
            packages = "gtest",  -- 集成 gtest 包
            defines = "TEST_MAIN"
        })
    end

:::tip 框架优势

doctest：轻量级，仅头文件，易于集成
gtest：功能丰富，Google 维护，社区活跃
Catch2：现代 C++ 风格，功能强大 :::

动态库测试

也可以对动态库进行测试：

target("mylib")
    set_kind("shared")
    add_files("src/*.cpp")

target("mylib_test")
    set_kind("binary")
    add_deps("mylib")
    add_files("tests/*.cpp")
    add_packages("gtest")
    add_tests("default")

## 详细输出

使用 `-v` 获取详细输出：

sh $ xmake test -v


使用 `-vD` 查看详细的测试失败错误信息：

sh $ xmake test -vD


`-vD` 参数会显示更详细的日志输出，包括每个测试的输出文件路径和错误信息：

sh report of tests: [ 2%]: test_10/compile_fail .... passed 0.001s [ 4%]: test_11/compile_pass .... failed 0.001s errors: build/.gens/test_11/macosx/x86_64/release/tests/test_11/compile_pass.errors.log [ 7%]: test_1/args ............. passed 0.045s stdout: build/.gens/test_1/macosx/x86_64/release/tests/test_1/args.stdout.log [ 9%]: test_1/default .......... passed 0.046s stdout: build/.gens/test_1/macosx/x86_64/release/tests/test_1/default.stdout.log [ 11%]: test_1/fail_output ...... passed 0.046s stdout: build/.gens/test_1/macosx/x86_64/release/tests/test_1/fail_output.stdout.log [ 14%]: test_1/pass_output ...... passed 0.047s stdout: build/.gens/test_1/macosx/x86_64/release/tests/test_1/pass_output.stdout.log ... [100%]: test_timeout/run_timeout failed 1.007s errors: build/.gens/test_timeout/macosx/x86_64/release/tests/test_timeout/run_timeout.errors.log

Detailed summary: Failed tests:

test_11/compile_pass
test_5/fail_output
test_5/pass_output
test_7/args
test_7/default
test_7/fail_output
test_7/pass_output
test_8/pass_output
test_timeout/run_timeout

78% tests passed, 9 test(s) failed out of 42, spent 1.212s


### 日志文件说明

使用 `-vD` 时，xmake 会生成以下日志文件：

- **stdout 日志**：`build/.gens/{target}/tests/{testname}.stdout.log` - 测试的标准输出
- **errors 日志**：`build/.gens/{target}/tests/{testname}.errors.log` - 测试的错误输出
- **构建错误日志**：编译失败时的详细错误信息

这些日志文件对于调试测试失败问题非常有用，可以查看具体的输出内容和错误信息。

## 分组测试

你可以使用模式匹配对测试进行分组：

运行所有以 "unit_" 开头的测试

$ xmake test /unit_

运行所有以 "test_" 开头的目标的测试

$ xmake test test_/

运行所有目标中的特定测试

$ xmake test */default


## 持续集成

对于 CI/CD 环境，可以使用以下模式：

运行测试，失败时返回错误码

$ xmake test

运行测试并提供详细输出用于 CI 日志

$ xmake test -v

运行特定测试组

$ xmake test unit_tests/* $ xmake test integration_tests/* ```

测试命令在任何测试失败时都会返回非零退出码，这使其适合用于 CI 流水线。

run-tests.md 12 KB Permalink History Raw

运行测试 {#run-tests}

命令格式

基本用法

配置测试用例

运行所有测试

运行指定的测试目标

测试配置选项

配置示例

带参数的测试

带预期输出的测试

带超时的测试

带环境变量的测试

构建失败测试

添加额外代码文件

集成第三方测试框架

doctest 集成示例

gtest 集成示例

动态库测试

运行所有以 "unit_" 开头的测试

运行所有以 "test_" 开头的目标的测试

运行所有目标中的特定测试

运行测试，失败时返回错误码

运行测试并提供详细输出用于 CI 日志

运行特定测试组

run-tests.md 12 KB

Permalink History Raw