test-runner

Active contributors: andrewrk, mlugg

Purpose

lib/compiler/test_runner.zig (~16 KB) is the program embedded in every test executable. When zig test foo.zig is run, the compiler builds an executable that links the user's code with this runner; executing the runner discovers test "..." blocks via @import("builtin").test_functions, runs them, and reports results.

What it does

• Iterates builtin.test_functions, which the compiler populates with a name + function pointer for every test "..." block.
• Runs each test in order, capturing stdout/stderr.
• Tracks pass/fail/skip and, on failure, prints the source location (mapped via debug info) and the captured output.
• Returns a non-zero exit code if any test failed.
• Cooperates with std.testing to count expectEqual/expectEqualSlices/etc. assertions and to handle error.SkipZigTest.
• Honors --listen from the caller (used by std.Build.Step.Run to capture structured results).

How zig test chooses a runner

zig test accepts --test-runner <path>. By default, zig uses lib/compiler/test_runner.zig. Users with custom needs (special filtering, JSON output, integration with another harness) can supply their own.

Companion: Step.Run integration

When std.Build.Step.Run invokes a test executable, it speaks a small protocol with this runner so that the build runner can collect structured test results into its summary output.

Key source files

File	Purpose
lib/compiler/test_runner.zig	The runner.
lib/std/testing.zig	Test assertions and helpers.
lib/std/Build/Step/Run.zig	The Run step that consumes the runner's protocol.
lib/compiler/build_runner.zig	Parent build runner; hands off to Step.Run.

See Testing for which zig build test-* step exercises which test tree.