Testing

The test driver is test/tests.zig (~85 KB). It exposes a number of build steps from build.zig that you can run individually.

Build-level test steps

Step	What it covers	Source
zig build test	Run everything below.	test/tests.zig
zig build test-behavior	Behavior tests across backends.	test/behavior.zig, test/behavior/
zig build test-cases	Compile-error and codegen cases.	test/cases.zig, test/cases/, test/cases/compile_errors/, test/cases/safety/
zig build test-compile-errors	Subset of cases that must fail to compile with a specific message.	test/compile_errors.zig, test/cases/compile_errors/
zig build test-standalone	Self-contained build.zig projects.	test/standalone/* (67 directories)
zig build test-link	Linker tests (ELF, MachO, COFF, Wasm).	test/link/, plus test_cases in build.zig.zon
zig build test-cli	CLI smoke tests.	test/cli/
zig build test-c-abi	C ABI conformance.	test/c_abi/
zig build test-fmt	zig fmt --check over the tree.	Driven by test/tests.zig
zig build test-translate-c	C → Zig translation.	test/cases.zig driver
zig build test-stack-traces	Stack trace formatting.	test/stack_traces.zig, test/error_traces.zig
zig build test-llvm-ir	LLVM IR golden output.	test/llvm_ir.zig
zig build test-llvm-targets	LLVM target enumeration matches std.Target.	test/llvm_targets.zig
zig build test-libc	libc detection / install record parsing.	test/libc.zig
zig build test-incremental	Incremental compilation.	test/incremental/, driven by tools/incr-check.zig
zig build test-gen-h	C-header generation.	test/gen_h.zig

The exact step names available depend on test/tests.zig — zig build --help lists everything live.

Where new tests go

Kind of change	Add a test under
Language semantics or stdlib	test/behavior/
New compile error / improved diagnostic	test/cases/compile_errors/
Safety check	test/cases/safety/
Linker (ELF/MachO/COFF/Wasm)	test/link/<format>/
Standalone end-to-end project	test/standalone/<name>/ (each is a self-contained build.zig)
C ABI	test/c_abi/
CLI behavior	test/cli/
Stack traces / error returns	test/error_traces.zig, test/stack_traces.zig
Incremental compile	test/incremental/, plus driver flags in tools/incr-check.zig
C → Zig translation	test/cases.zig's translate-c slice
Compiler-generated docs	tools/docgen.zig, tools/doctest.zig (the source of doc/langref.html)

How test-cases works

test/cases.zig and the matching directories under test/cases/ are the "small input + expected output" suite. Each file is a Zig snippet plus, in the case of error tests, an inline error spec. The driver compiles each one and asserts on stderr or compile success.

test/cases/compile_errors/ alone contains thousands of files; the directory listing is one of the largest in the repository.

Standalone tests

test/standalone/ is the right place for anything that needs its own build.zig. Each subdirectory is registered in test/tests.zig and built/run as part of zig build test-standalone. These tests are how you exercise downstream-visible behavior — packaging, linking, cross-compilation, custom build steps.

Linker tests

test/link/ has a sub-directory per linker (elf/, macho/, wasm/, coff/, plus shared helpers). Each test compiles a small input and asserts that the produced binary has the expected symbols, sections, or imports. These run against the in-tree linkers (src/link/Elf.zig, src/link/MachO.zig, etc.).

Incremental compilation

tools/incr-check.zig is the harness behind test-incremental. It applies a sequence of edits to a fixture, asks the compiler to rebuild incrementally, and compares the result against a clean build. Edits, expected diagnostics, and expected outputs are all in the fixture file.

Format check

zig build test-fmt runs zig fmt --check across lib/, src/, test/, and the build files. CI fails on any formatting drift.