What is a test in zig?

Explain
,
9

The build system invokes zig test to run tests; it passes a special flag --listen=- to enable a communication protocol between the build system and the test runner, then the test results are displayed by the build system.

It is the main function of the test runner that is compiled with the tests.
The source of the test runner is lib/compiler/test_runner.zig

See: ZTAP: TAP 14 Test Runner

No, the tests run sequentially by the test runner.
The build system invokes the build steps in parallel.

The test runner is the sub-process that runs the tests.
The build system invokes the test runner.

The test runner does not cache anything.
The build system caches the test runner. Set the flag has_side_effects in the test run build step to rerun the tests when there are no changes.

    const run_tests = b.addRunArtifact(tests);
    run_tests.has_side_effects = true;

The build system displays information about the tests according to the --summary flag (new and all are the most useful values).

@import("builtin").test_functions returns the list of test functions.
The list is populated from the tests of the root test module namespace and all other tests that are in referenced namespaces.

Because the struct namespace is not referenced.

Yes, the build system can run the test runner under various emulators:

  -fdarling,  -fno-darling     Integration with system-installed Darling to
                               execute macOS programs on Linux hosts
                               (default: no)
  -fqemu,     -fno-qemu        Integration with system-installed QEMU to execute
                               foreign-architecture programs on Linux hosts
                               (default: no)
  --glibc-runtimes [path]      Enhances QEMU integration by providing glibc built
                               for multiple foreign architectures, allowing
                               execution of non-native programs that link with glibc.
  -frosetta,  -fno-rosetta     Rely on Rosetta to execute x86_64 programs on
                               ARM64 macOS hosts. (default: no)
  -fwasmtime, -fno-wasmtime    Integration with system-installed wasmtime to
                               execute WASI binaries. (default: no)
  -fwine,     -fno-wine        Integration with system-installed Wine to execute
                               Windows programs on Linux hosts. (default: no)

Return error.SkipZigTest from your tests.

The doc tests are about defined symbols (functions or declarations) that are displayed as example code in the generated documentation.

Neither a function nor a declaration. It is a test (it is implemented as a function that accepts no arguments and returns anyerror!void).

Yes, using @import("builtin").test_functions. Note that this is not just a list of test names, you can also invoke the test function.

5 Likes