Zig Test

    introducing_zig_test.zig

    Shell

    1. $ zig test introducing_zig_test.zig
    2. 1/1 test "expect addOne adds one to 41"... OK
    3. All 1 tests passed.

    The introducing_zig_test.zig code sample tests the addOne to ensure that it returns 42 given the input 41. From this test’s perspective, the addOne function is said to be code under test.

    zig test is a tool that creates and runs a test build. By default, it builds and runs an executable program using the default test runner provided by the Zig Standard Library as its main entry point. During the build, test declarations found while the given Zig source file are included for the default test runner to run and report on.

    This documentation discusses the features of the default test runner as provided by the Zig Standard Library. Its source code is located in lib/std/special/test_runner.zig.

    The shell output shown above displays two lines after the zig test command. These lines are printed to standard error by the default test runner:

    Test [1/1] test “expect addOne adds one to 41”…

    Lines like this indicate which test, out of the total number of tests, is being run. In this case, [1/1] indicates that the first test, out of a total of one test, is being run. Note that, when the test runner program’s standard error is output to the terminal, these lines are cleared when a test succeeds.

    All 1 tests passed.

    This line indicates the total number of tests that have passed.

    Test declarations contain the keyword test, followed by an optional name written as a , followed by a block containing any valid Zig code that is allowed in a .

    By convention, non-named tests should only be used to make other tests run. Non-named tests cannot be .

    Test declarations are similar to Functions: they have a return type and a block of code. The implicit return type of test is the anyerror!void, and it cannot be changed. When a Zig source file is not built using the zig test tool, the test declarations are omitted from the build.

    See also:

    When the zig test tool is building a test runner, only resolved test declarations are included in the build. Initially, only the given Zig source file’s top-level declarations are resolved. Unless nested containers are referenced from a top-level test declaration, nested container tests will not be resolved.

    The code sample below uses the std.testing.refAllDecls(@This()) function call to reference all of the containers that are in the file including the imported Zig source file. The code sample also shows an alternative way to reference containers using the _ = C; syntax. This syntax tells the compiler to ignore the result of the expression on the right side of the assignment operator.

    testdecl_container_top_level.zig

    1. const std = @import("std");
    2. const expect = std.testing.expect;
    4. // Imported source file tests will run when referenced from a top-level test declaration.
    5. // The next line alone does not cause "introducing_zig_test.zig" tests to run.
    6. const imported_file = @import("introducing_zig_test.zig");
    8. test {
    9.     // To run nested container tests, either, call `refAllDecls` which will
    10.     // reference all declarations located in the given argument.
    11.     // `@This()` is a builtin function that returns the innermost container it is called from.
    12.     // In this example, the innermost container is this file (implicitly a struct).
    13.     std.testing.refAllDecls(@This());
    15.     // or, reference each container individually from a top-level test declaration.
    16.     // The `_ = C;` syntax is a no-op reference to the identifier `C`.
    17.     _ = S;
    18.     _ = U;
    19.     _ = @import("introducing_zig_test.zig");
    20. }
    22. const S = struct {
    23.     test "S demo test" {
    24.         try expect(true);
    25.     }
    27.     const SE = enum {
    28.         V,
    30.         // This test won't run because its container (SE) is not referenced.
    31.         test "This Test Won't Run" {
    32.             try expect(false);
    33.         }
    34.     };
    35. };
    37. const U = union { // U is referenced by the file's top-level test declaration
    38.     s: US,        // and US is referenced here; therefore, "U.Us demo test" will run
    40.     const US = struct {
    41.         test "U.US demo test" {
    42.             // This test is a top-level test declaration for the struct.
    43.             // The struct is nested (declared) inside of a union.
    44.             try expect(true);
    45.     };
    47.     test "U demo test" {
    48.         try expect(true);
    49.     }
    50. };

    Shell

    1. $ zig test testdecl_container_top_level.zig
    2. 1/5 test ""... OK
    3. 2/5 S.test "S demo test"... OK
    4. 3/5 U.test "U demo test"... OK
    5. 4/5 introducing_zig_test.test "expect addOne adds one to 41"... OK
    6. 5/5 US.test "U.US demo test"... OK
    7. All 5 tests passed.

    The default test runner checks for an error returned from a test. When a test returns an error, the test is considered a failure and its is output to standard error. The total number of failures will be reported after all tests have run.

    test.zig

    1. const std = @import("std");
    3. test "expect this to fail" {
    4.     try std.testing.expect(false);
    5. }
    7. test "expect this to succeed" {
    8.     try std.testing.expect(true);
    9. }

    Shell

    One way to skip tests is to filter them out by using the zig test command line parameter --test-filter [text]. This makes the test build only include tests whose name contains the supplied filter text. Note that non-named tests are run even when using the --test-filter [text] command line parameter.

    To programmatically skip a test, make a test return the error error.SkipZigTest and the default test runner will consider the test as being skipped. The total number of skipped tests will be reported after all tests have run.

    test.zig

    1. test "this will be skipped" {
    2.     return error.SkipZigTest;
    3. }

    Shell

    1. $ zig test test.zig
    2. 1/1 test "this will be skipped"... test "this will be skipped"... SKIP
    3. SKIP
    4. 0 passed; 1 skipped; 0 failed.

    The default test runner skips tests containing a suspend point while the test is running using the default, blocking IO mode. (The evented IO mode is enabled using the --test-evented-io command line parameter.)

    1. const std = @import("std");
    3. test "async skip test" {
    4.     var frame = async func();
    5.     const result = await frame;
    6.     try std.testing.expect(result == 1);
    7. }
    9. fn func() i32 {
    10.     suspend {
    11.         resume @frame();
    12.     }
    13.     return 1;
    14. }

    Shell

    1. $ zig test async_skip.zig
    2. 1/1 test "async skip test"... test "async skip test"... SKIP (async test)
    3. SKIP (async test)
    4. 0 passed; 1 skipped; 0 failed.

    In the code sample above, the test would not be skipped in blocking IO mode if the nosuspend keyword was used (see ).

    When code allocates Memory using the ‘s testing allocator, std.testing.allocator, the default test runner will report any leaks that are found from using the testing allocator:

    test.zig

    Shell

    1. $ zig test test.zig
    2. 1/1 test "detect leak"... OK
    3. [gpa] (err): memory address 0x7fc140eb0000 leaked:
    4. /home/andy/Downloads/zig/lib/std/array_list.zig:325:69: 0x20d9d9 in std.array_list.ArrayListAligned(u21,null).ensureTotalCapacityPrecise (test)
    5.                 const new_memory = try self.allocator.reallocAtLeast(self.allocatedSlice(), new_capacity);
    6.                                                                     ^
    7. /home/andy/Downloads/zig/lib/std/array_list.zig:310:55: 0x20d7de in std.array_list.ArrayListAligned(u21,null).ensureTotalCapacity (test)
    8.                 return self.ensureTotalCapacityPrecise(better_capacity);
    9.                                                       ^
    11.             try self.ensureTotalCapacity(newlen);
    12. /home/andy/Downloads/zig/lib/std/array_list.zig:161:49: 0x209d54 in std.array_list.ArrayListAligned(u21,null).append (test)
    13.             const new_item_ptr = try self.addOne();
    14.                                                 ^
    15. /home/andy/Downloads/zig/docgen_tmp/test.zig:6:20: 0x209730 in test "detect leak" (test)
    16.     try list.append('☔');
    17.                    ^
    18. /home/andy/Downloads/zig/lib/std/special/test_runner.zig:80:28: 0x23bd83 in std.special.main (test)
    19.         } else test_fn.func();
    20.                            ^
    21. /home/andy/Downloads/zig/lib/std/start.zig:543:22: 0x233cac in std.start.callMain (test)
    22.             root.main();
    23.                      ^
    24. /home/andy/Downloads/zig/lib/std/start.zig:495:12: 0x20e7ce in std.start.callMainWithArgs (test)
    25.     return @call(.{ .modifier = .always_inline }, callMain, .{});
    26.            ^
    29. All 1 tests passed.
    30. 1 errors were logged.
    31. 1 tests leaked memory.
    32. error: the following test command failed with exit code 1:
    33. docgen_tmp/zig-cache/o/8e4964e05ddaf866e77360a551b3c05b/test /home/andy/Downloads/zig/build-release/zig

    See also:

    Use the compile variable @import("builtin").is_test to detect a test build:

    detect_test.zig

    1. const std = @import("std");
    2. const builtin = @import("builtin");
    3. const expect = std.testing.expect;
    5. test "builtin.is_test" {
    6.     try expect(isATest());
    7. }
    9. fn isATest() bool {
    10.     return builtin.is_test;
    11. }

    Shell

    1. $ zig test detect_test.zig
    2. 1/1 test "builtin.is_test"... OK
    3. All 1 tests passed.

    The default test runner and the Zig Standard Library’s testing namespace output messages to standard error.

    The Testing Namespace

    The Zig Standard Library’s testing namespace contains useful functions to help you create tests. In addition to the expect function, this document uses a couple of more functions as exemplified here:

    testing_functions.zig

    1. const std = @import("std");
    3. test "expectEqual demo" {
    4.     const expected: i32 = 42;
    5.     const actual = 42;
    7.     // The first argument to `expectEqual` is the known, expected, result.
    8.     // The second argument is the result of some expression.
    9.     // The actual's type is casted to the type of expected.
    10.     try std.testing.expectEqual(expected, actual);
    11. }
    13. test "expectError demo" {
    14.     const expected_error = error.DemoError;
    15.     const actual_error_union: anyerror!void = error.DemoError;
    17.     // `expectError` will fail when the actual error is different than
    18.     // the expected error.
    19.     try std.testing.expectError(expected_error, actual_error_union);

    Shell

    Test Tool Documentation

    zig test has a few command line parameters which affect the compilation. See zig test —help for a full list.