Zig std.testing: No Built‑in Mocking for Integration Tests Without Production Credentials

Direct Answer

Zig’s std.testing provides only test discovery, reporting, and per-test test blocks. It has no built-in mocking framework, no suite-level setup/teardown hooks, and no documented mechanism for injecting test-only implementations or credentials. The standard library treats tests as ordinary code; isolation is entirely the developer’s responsibility.

How to Structure a Test-Only Binary with Mocks

The supported, idiomatic approach uses the build system to swap implementations at compile time:

1. Define a stable interface (e.g., service.zig) that declares the external dependency’s public API.
2. Provide two implementations:
   • service_prod.zig – talks to the real service, reads production credentials from environment variables.
   • service_mock.zig – returns canned data, performs no network I/O.
3. In build.zig, add a build flag (e.g., -Dmock=true or --define TEST_MODE) that controls which implementation is linked.
4. Create a dedicated test step that sets optimize = .Debug, defines the flag, and links the mock module.

Minimal build.zig Example

const std = @import("std");
pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Production library
    const lib = b.addStaticLibrary(.{
        .name = "mysvc",
        .root_source_file = .{ .path = "src/service.zig" },
        .target = target,
        .optimize = optimize,
    });

    // Mock implementation (only compiled when flag is set)
    const mock = b.addStaticLibrary(.{
        .name = "mysvc_mock",
        .root_source_file = .{ .path = "src/service_mock.zig" },
        .target = target,
        .optimize = optimize,
    });

    // Test executable – chooses implementation via flag
    const test_exe = b.addTest(.{
        .root_source_file = .{ .path = "src/integration_test.zig" },
        .target = target,
        .optimize = .Debug,
    });

    const mock_flag = b.option(bool, "mock", "Link mock service instead of production") orelse false;
    if (mock_flag) {
        test_exe.linkLibrary(mock);
    } else {
        test_exe.linkLibrary(lib);
    }

    const test_step = b.step("test", "Run integration tests with mock service");
    test_step.dependOn(&test_exe.step);
}

Credential Isolation Practices

• Never hard-code credentials. Production code reads from std.process.getEnvVar("PROD_API_KEY") (or a config file).
• Test runs inject safe values via the shell: TEST_API_KEY=mock zig build test -Dmock=true.
• Document required variables in tests/credentials.md or the project README; list each variable, its purpose, and the safe test value.
• Exclude test binaries from releases by not adding them to b.installArtifact().

Verification Checklist

1. Create service_mock.zig implementing the same interface.
2. Run zig build test -Dmock=true --verbose and confirm the mock module appears in the link line.
3. Set TEST_API_KEY=mockvalue and run the test binary directly; verify logs show the mock credential and no outbound connections (e.g., with strace -f -e network or tcpdump).
4. Ensure zig build --help documents the -Dmock flag and required env vars.

One Diagnostic Detail That Changes the Recommendation

If your integration tests must exercise multiple external services simultaneously (e.g., a database and an HTTP API), you may need a more granular flag per service (-Dmock_db, -Dmock_http) or a test harness that spawns the real service in a container. Does your test suite target a single external dependency or several?