Zig 测试与调试

基于 std.testing 和 std.debug 的质量保障工具（Zig 0.16.0）。

Capability Boundaries

✅ 强项

1. 单元测试编写与断言
2. 测试组织（test 声明、doctest、测试过滤器）
3. 内存泄漏检测
4. 日志输出（std.log）
5. 调试工具（panic、断言、堆栈回溯、hex dump）

⚠️ 前置要求

1. 确认 Zig 版本（zig version）

❌ 不适用范围

1. 构建系统测试配置 → 使用 zig-build-system 技能
2. 集成测试框架 → 使用 zig-0.16 技能
3. 性能基准测试 → 暂不涉及（Zig 尚未内置 benchmark）

何时使用

• "帮我写单元测试"
• "调试这个函数的输出"
• "检查内存泄漏"

Data Privacy

本技能不收集、存储或传输任何用户数据。

Workflow — 测试

步骤 1. 声明测试 — test "name" { ... } 步骤 2. 使用断言 — expect, expectEqual, expectEqualStrings 步骤 3. 运行测试 — zig test src/main.zig 或 zig build test 步骤 4. 检查结果 — 通过/失败/泄漏

断言速查

| 断言 | 用途 | |------|------| | expect(bool) | 条件为真 | | expectEqual(expected, actual) | 浅相等（peer type） | | expectEqualDeep(expected, actual) | 深相等（递归比较） | | expectEqualStrings(expected, actual) | 字符串相等（带 diff） | | expectEqualSlices(T, expected, actual) | 切片相等 | | expectError(error, result) | 返回特定错误 | | expectApproxEqAbs(expected, actual, eps) | 浮点近似（绝对误差） | | expectApproxEqRel(expected, actual, eps) | 浮点近似（相对误差） | | expectFmt(expected, template, args) | 格式化输出匹配 | | expectStringStartsWith(actual, prefix) | 字符串前缀 | | expectStringEndsWith(actual, suffix) | 字符串后缀 |

基本断言

test "basic assertions" {
    try std.testing.expect(true);

    try std.testing.expectEqual(@as(u32, 42), @as(u32, 42));

    try std.testing.expectEqualStrings("hello", "hello");

    try std.testing.expectEqualSlices(u8, &[_]u8{ 1, 2 }, &[_]u8{ 1, 2 });

    try std.testing.expectEqualDeep(
        struct{ x: i32, y: i32 }{ .x = 1, .y = 2 },
        struct{ x: i32, y: i32 }{ .x = 1, .y = 2 },
    );
}

浮点比较

test "float comparison" {
    try std.testing.expectApproxEqAbs(@as(f32, 1.0), 1.0001, 0.001);
    try std.testing.expectApproxEqRel(@as(f64, 100.0), 99.5, 0.01);
}

错误检查

test "error handling" {
    const result: anyerror!i32 = error.SomeError;
    try std.testing.expectError(error.SomeError, result);
}

测试组织

内联测试

const std = @import("std");
const expect = std.testing.expect;

test "inline test" {
    try expect(1 + 1 == 2);
}

doctest（文档中的测试）

/// Adds two numbers.
///
/// ```
/// const result = add(2, 3);
/// try std.testing.expectEqual(@as(i32, 5), result);
/// ```
fn add(a: i32, b: i32) i32 {
    return a + b;
}

测试过滤器

# 运行名称包含 "http" 的测试
zig test src/main.zig --test-filter "http"

# 在 build.zig 中过滤
const tests = b.addTest(.{
    .root_module = mod,
    .filters = &.{"specific_test"},
});

测试模块

// 在文件末尾使用 test 块
test "module tests" {
    // 引用当前模块
    _ = @import("main.zig");
    // 或者单独引用测试文件
    _ = @import("tests/tests.zig");
}

内存泄漏检测

使用 DebugAllocator

test "memory leak detection" {
    var gpa: std.heap.DebugAllocator(.{}) = .init;
    defer {
        const leaked = gpa.deinit();
        // leaked 为 true 表示有泄漏
        if (leaked) @panic("Memory leak detected!");
    }
    const allocator = gpa.allocator();

    const buf = try allocator.alloc(u8, 100);
    // ⚠️ 忘记 allocator.free(buf) 会导致泄漏
    // defer allocator.free(buf);
}

使用 testing.allocator

test "use testing allocator" {
    const allocator = std.testing.allocator;
    // testing.allocator 会自动检测泄漏
    const buf = try allocator.alloc(u8, 10);
    defer allocator.free(buf); // 不 free 会报告泄漏
}

检测日志

# 测试失败时输出泄漏信息
zig test src/main.zig
# Memory leak detected: 1 allocations remaining (100 bytes)

日志与调试

等级化日志

std.log.debug("debug message: {}", .{value});    // 编译时可用
std.log.info("info: {}", .{value});              // 默认显示
std.log.warn("warning: {}", .{value});           // 重要警告
std.log.err("error: {}", .{value});              // 错误

自定义日志作用域

const log = std.log.scoped(.http_client);
log.info("request to {s}", .{url});
// 输出: [http_client] request to https://example.com

运行时日志级别

# 设置日志级别（默认 .info）
zig build -Dlog-level=debug
# 或按作用域过滤
zig build -Dlog-scope-override=http_client=debug

panic 和断言

// 调试断言（仅在安全模式下检查）
std.debug.assert(x > 0);

// 不可达（标记不可能执行的代码路径）
unreachable;

// 主动 panic
@panic("something went wrong");

堆栈回溯

// 在 panic 或断言失败时自动打印堆栈
// 手动打印：
std.debug.dumpCurrentStackTrace(null);

Hex Dump

const bytes = [_]u8{ 0x48, 0x65, 0x6C, 0x6C, 0x6F };
std.debug.hexDump("data", &bytes);
// 输出:
// data:
// 00000000: 48 65 6C 6C 6F                                Hello

测试配置（build.zig）

标准测试步骤

const tests = b.addTest(.{
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    }),
});

const run_tests = b.addRunArtifact(tests);
const test_step = b.step("test", "运行单元测试");
test_step.dependOn(&run_tests.step);

多模块测试聚合

const test_step = b.step("test", "运行所有测试");
for ([_]*std.Build.Module{ mod_a, mod_b, mod_c }) |mod| {
    const t = b.addTest(.{ .root_module = mod });
    test_step.dependOn(&b.addRunArtifact(t).step);
}

Gotchas

1. expectEqual 使用 peer type — 两参数必须显式类型一致，推荐 expectEqual(@as(u32, 42), value)
2. testing.allocator 只用于测试 — 它自动检测泄漏，但性能较差，生产环境用 DebugAllocator
3. test 声明不能嵌套 — test "..." { test "..." {} } 不合法
4. doctest 只验证不输出 — 文档中的代码块默认被测试，但如果 panic 不会显示详细信息
5. std.log.debug 默认不显示 — 需要在构建时启用 -Dlog-level=debug

FAQ

Q：如何只运行特定的测试？ A：命令行 zig test src/main.zig --test-filter "http"，或通过 build.zig 的 filters 选项。

Q：测试依赖的初始化代码怎么写？ A：在 test 块内部初始化，或创建一个全局的测试辅助函数 fn testUtil() !void。

Q：Zig 有基准测试吗？ A：Zig 标准库尚未内置 benchmark 工具。可以在测试中手动计时：const start = std.time.Timer.start()?。