Skip to content
Standard libraryZig 0.17.1Official documentation
Sourcestd/testing.zig

Source line 1

std.testing.A

container

Source line 1020

Fields

b: B
c: C

std.testing.allocator

constant

Source line 21

std.testing.allocator_instance

variable

Source line 20

std.heap.SafeAllocator

std.testing.assert

alias

Source line 6

Alias of std.debug.assert

std.testing.B

namespace

Source line 1021

std.testing.backend_can_print

constant

Source line 32

std.testing.base_allocator_instance

variable

Source line 18

std.testing.builtin

constant

Source line 1

std.testing.BytesDiffer

container

Source line 461

Fields

expected: []const u8
actual: []const u8
terminal_mode: Io.Terminal.Mode

std.testing.BytesDiffer.terminal

function

Source line 512

fn terminal(self: *const BytesDiffer, writer: *Io.Writer) Io.Terminal

Parameters

self: *const BytesDiffer
writer: *Io.Writer

std.testing.BytesDiffer.write

function

Source line 466

pub fn write(self: BytesDiffer, writer: *Io.Writer) !void

Parameters

self: BytesDiffer
writer: *Io.Writer

std.testing.BytesDiffer.writeDiff

function

Source line 516

fn writeDiff(self: BytesDiffer, writer: *Io.Writer, comptime fmt: []const u8, args: anytype, diff: bool) !void

Parameters

self: BytesDiffer
writer: *Io.Writer
fmt: []const u8
diff: bool

std.testing.C

container

Source line 1022

Fields

a: *const A

std.testing.checkAllAllocationFailures

function

Source line 1145

Exhaustively check that allocation failures within test_fn are handled without introducing memory leaks. If used with the testing.allocator as the backing_allocator, it will also be able to detect double frees, etc (when runtime safety is enabled).

The provided test_fn must have a std.mem.Allocator as its first argument, and must have a return type of !void. Any extra arguments of test_fn can be provided via the extra_args tuple.

Any relevant state shared between runs of test_fn must be reset within test_fn.

The strategy employed is to:

  • Run the test function once to get the total number of allocations.
  • Then, iterate and run the function X more times, incrementing the failing index each iteration (where X is the total number of allocations determined previously)

Expects that test_fn has a deterministic number of memory allocations:

  • If an allocation was made to fail during a run of test_fn, but test_fn didn't return error.OutOfMemory, then error.SwallowedOutOfMemoryError is returned from checkAllAllocationFailures. You may want to ignore this depending on whether or not the code you're testing includes some strategies for recovering from error.OutOfMemory.
  • If a run of test_fn with an expected allocation failure executes without an allocation failure being induced, then error.NondeterministicMemoryUsage is returned. This error means that there are allocation points that won't be tested by the strategy this function employs (that is, there are sometimes more points of allocation than the initial run of test_fn detects).

Here's an example using a simple test case that will cause a leak when the allocation of bar fails (but will pass normally):

test {
    const length: usize = 10;
    const allocator = std.testing.allocator;
    var foo = try allocator.alloc(u8, length);
    var bar = try allocator.alloc(u8, length);

    allocator.free(foo);
    allocator.free(bar);
}

The test case can be converted to something that this function can use by doing:

fn testImpl(allocator: std.mem.Allocator, length: usize) !void {
    var foo = try allocator.alloc(u8, length);
    var bar = try allocator.alloc(u8, length);

    allocator.free(foo);
    allocator.free(bar);
}

test {
    const length: usize = 10;
    const allocator = std.testing.allocator;
    try std.testing.checkAllAllocationFailures(allocator, testImpl, .{length});
}

Running this test will show that foo is leaked when the allocation of bar fails. The simplest fix, in this case, would be to use defer like so:

fn testImpl(allocator: std.mem.Allocator, length: usize) !void {
    var foo = try allocator.alloc(u8, length);
    defer allocator.free(foo);
    var bar = try allocator.alloc(u8, length);
    defer allocator.free(bar);
}
pub fn checkAllAllocationFailures( backing_allocator: std.mem.Allocator, comptime test_fn: anytype, extra_args: CheckAllAllocationFailuresExtraArgs(@TypeOf(test_fn)), ) !void

Parameters

backing_allocator: std.mem.Allocator
extra_args: CheckAllAllocationFailuresExtraArgs(@TypeOf(test_fn))

std.testing.CheckAllAllocationFailuresExtraArgs

type-function

Source line 1197

fn CheckAllAllocationFailuresExtraArgs(comptime TestFn: type) type

Parameters

TestFn: type

std.testing.environ

variable

Source line 26

Environ

std.testing.Environ

alias

Source line 5

Alias of std.process.Environ

std.testing.expect

function

Source line 583

This function is intended to be used only in tests. When ok is false, returns a test failure error.

pub fn expect(ok: bool) !void

Parameters

ok: bool

std.testing.expectApproxEqAbs

function

Source line 258

This function is intended to be used only in tests. When the actual value is not approximately equal to the expected value, prints diagnostics to stderr to show exactly how they are not equal, then returns a test failure error. See math.approxEqAbs for more information on the tolerance parameter. The types must be floating-point. actual and expected are coerced to a common type using peer type resolution.

pub inline fn expectApproxEqAbs(expected: anytype, actual: anytype, tolerance: anytype) !void

Example usage

test expectApproxEqAbs {
    inline for ([_]type{ f16, f32, f64, f128 }) |T| {
        const pos_x: T = 12.0;
        const pos_y: T = 12.06;
        const neg_x: T = -12.0;
        const neg_y: T = -12.06;

        try expectApproxEqAbs(pos_x, pos_y, 0.1);
        try expectApproxEqAbs(neg_x, neg_y, 0.1);
    }
}

std.testing.expectApproxEqAbsInner

function

Source line 263

fn expectApproxEqAbsInner(comptime T: type, expected: T, actual: T, tolerance: T) !void

Parameters

T: type
expected: T
actual: T
tolerance: T

std.testing.expectApproxEqRel

function

Source line 294

This function is intended to be used only in tests. When the actual value is not approximately equal to the expected value, prints diagnostics to stderr to show exactly how they are not equal, then returns a test failure error. See math.approxEqRel for more information on the tolerance parameter. The types must be floating-point. actual and expected are coerced to a common type using peer type resolution.

pub inline fn expectApproxEqRel(expected: anytype, actual: anytype, tolerance: anytype) !void

Example usage

test expectApproxEqRel {
    inline for ([_]type{ f16, f32, f64, f128 }) |T| {
        const eps_value = comptime math.floatEps(T);
        const sqrt_eps_value = comptime @sqrt(eps_value);

        const pos_x: T = 12.0;
        const pos_y: T = pos_x + 2 * eps_value;
        const neg_x: T = -12.0;
        const neg_y: T = neg_x - 2 * eps_value;

        try expectApproxEqRel(pos_x, pos_y, sqrt_eps_value);
        try expectApproxEqRel(neg_x, neg_y, sqrt_eps_value);
    }
}

std.testing.expectApproxEqRelInner

function

Source line 299

fn expectApproxEqRelInner(comptime T: type, expected: T, actual: T, tolerance: T) !void

Parameters

T: type
expected: T
actual: T
tolerance: T

std.testing.expectEqual

function

Source line 55

This function is intended to be used only in tests. When the two values are not equal, prints diagnostics to stderr to show exactly how they are not equal, then returns a test failure error. actual and expected are coerced to a common type using peer type resolution.

pub inline fn expectEqual(expected: anytype, actual: anytype) !void

std.testing.expectEqualDeep

function

Source line 769

This function is intended to be used only in tests. When the two values are not deeply equal, prints diagnostics to stderr to show exactly how they are not equal, then returns a test failure error. actual and expected are coerced to a common type using peer type resolution.

Deeply equal is defined as follows: Primitive types are deeply equal if they are equal using == operator. Struct values are deeply equal if their corresponding fields are deeply equal. Container types(like Array/Slice/Vector) deeply equal when their corresponding elements are deeply equal. Pointer values are deeply equal if values they point to are deeply equal.

Note: Self-referential structs are supported (e.g. things like std.SinglyLinkedList) but may cause infinite recursion or stack overflow when a container has a pointer to itself.

pub inline fn expectEqualDeep(expected: anytype, actual: anytype) error{TestExpectedEqual}!void

Errors

TestExpectedEqual

std.testing.expectEqualDeepInner

function

Source line 774

fn expectEqualDeepInner(comptime T: type, expected: T, actual: T) error{TestExpectedEqual}!void

Parameters

T: type
expected: T
actual: T

Errors

TestExpectedEqual

std.testing.expectEqualInner

function

Source line 60

fn expectEqualInner(comptime T: type, expected: T, actual: T) !void

Parameters

T: type
expected: T
actual: T

std.testing.expectEqualSentinel

function

Source line 541

This function is intended to be used only in tests. When the two slices or two arrays are not equal, or their sentinel (if any) are not the same, it prints diagnostics to stderr to show exactly how they are not equal (with the differences highlighted in red), then returns a test failure error. It partially depends on expectEquaSlices for printing diagnostics.

pub fn expectEqualSentinel(comptime T: type, comptime sentinel: T, expected: [:sentinel]const T, actual: [:sentinel]const T) !void

Parameters

T: type
sentinel: T
expected: [:sentinel]const T
actual: [:sentinel]const T

std.testing.expectEqualSlices

function

Source line 331

This function is intended to be used only in tests. When the two slices are not equal, it prints diagnostics to stderr to show exactly how they are not equal (with the differences highlighted in red), then returns a test failure error.

pub fn expectEqualSlices(comptime T: type, expected: []const T, actual: []const T) !void

Parameters

T: type
expected: []const T
actual: []const T

Example usage

test expectEqualSlices {
    try expectEqualSlices(u8, "foo\x00", "foo\x00");
    try expectEqualSlices(u16, &[_]u16{ 100, 200, 300, 400 }, &[_]u16{ 100, 200, 300, 400 });
    const E = enum { foo, bar };
    const S = struct {
        v: E,
    };
    try expectEqualSlices(
        S,
        &[_]S{ .{ .v = .foo }, .{ .v = .bar }, .{ .v = .foo }, .{ .v = .bar } },
        &[_]S{ .{ .v = .foo }, .{ .v = .bar }, .{ .v = .foo }, .{ .v = .bar } },
    );
}

std.testing.expectEqualStrings

function

Source line 671

it prints diagnostics to stderr to show how they are not equal, then returns an error.

pub fn expectEqualStrings(expected: []const u8, actual: []const u8) !void

Parameters

expected: []const u8
actual: []const u8

Example usage

test expectEqualStrings {
    try expectEqualStrings("foo", "foo");
}

std.testing.expectError

function

Source line 631

This function is intended to be used only in tests. When actual_error_union is not expected_error, it prints diagnostics to stderr, then returns a test failure error.

pub fn expectError(expected_error: anyerror, actual_error_union: anytype) !void

Parameters

expected_error: anyerror

Example usage

test expectError {
    const actualErrorUnion = returnErrorUnion();
    try expectError(error.Expected, actualErrorUnion);
}

std.testing.expectFmt

function

Source line 659

This function is intended to be used only in tests. When the formatted result of the template and its arguments does not equal the expected text, it prints diagnostics to stderr to show how they are not equal, then returns an error. It depends on expectEqualStrings for printing diagnostics.

pub fn expectFmt(expected: []const u8, comptime template: []const u8, args: anytype) !void

Parameters

expected: []const u8
template: []const u8

std.testing.expectStringEndsWith

function

Source line 732

This function is intended to be used only in test. When the end of actual and expected_ends_with are not equal, it prints diagnostics to stderr to show how they are not equal, then returns an error.

pub fn expectStringEndsWith(actual: []const u8, expected_ends_with: []const u8) !void

Parameters

actual: []const u8
expected_ends_with: []const u8

Example usage

test expectStringEndsWith {
    try expectStringEndsWith("foobar", "bar");
}

std.testing.expectStringStartsWith

function

Source line 706

This function is intended to be used only in test. When the start of actual and expected_starts_with are not equal, it prints diagnostics to stderr to show how they are not equal, then returns an error.

pub fn expectStringStartsWith(actual: []const u8, expected_starts_with: []const u8) !void

Parameters

actual: []const u8
expected_starts_with: []const u8

Example usage

test expectStringStartsWith {
    try expectStringStartsWith("foobar", "foo");
}

std.testing.f

function

Source line 1226

fn f(ally: std.mem.Allocator, params: struct { foo_len: u32, bar_len: u32, }) !void

Parameters

ally: std.mem.Allocator
params: struct {
    foo_len: u32,
    bar_len: u32,
}

std.testing.f

function

Source line 1249

fn f(gpa: std.mem.Allocator) !void

Parameters

std.testing.failEqualSlices

function

Source line 349

fn failEqualSlices( comptime T: type, expected: []const T, actual: []const T, diff_index: usize, w: *Io.Writer, terminal_mode: Io.Terminal.Mode, ) !void

Parameters

T: type
expected: []const T
actual: []const T
diff_index: usize
w: *Io.Writer
terminal_mode: Io.Terminal.Mode

std.testing.failing_allocator

constant

Source line 14

std.testing.failing_allocator_instance

variable

Source line 15

std.testing.FailingAllocator

alias

Source line 13

Alias of std.testing.FailingAllocator

std.testing.failPrint

function

Source line 43

Helper function for printing test failure information.

pub fn failPrint(comptime fmt: []const u8, args: anytype) void

Parameters

fmt: []const u8

std.testing.failPrintIndicatorLine

function

Source line 1033

Helper function for printing test failure information.

pub fn failPrintIndicatorLine(source: []const u8, indicator_index: usize) void

Parameters

source: []const u8
indicator_index: usize

std.testing.failPrintLine

function

Source line 1062

Helper function for printing test failure information.

pub fn failPrintLine(line: []const u8) void

Parameters

line: []const u8

std.testing.failPrintWithVisibleNewlines

function

Source line 1053

Helper function for printing test failure information.

pub fn failPrintWithVisibleNewlines(source: []const u8) void

Parameters

source: []const u8

std.testing.foo

function

Source line 963

fn foo() void

std.testing.format

function

Source line 975

pub fn format(self: @This(), writer: *Io.Writer) !void

Parameters

self: @This()
writer: *Io.Writer

std.testing.fuzz

function

Source line 1278

Inline to avoid coverage instrumentation.

pub inline fn fuzz( context: anytype, comptime testOne: fn (context: @TypeOf(context), smith: *Smith) anyerror!void, options: FuzzInputOptions, ) anyerror!void

Parameters

testOne: fn (context: @TypeOf(context), smith: *Smith) anyerror!void
options: FuzzInputOptions

std.testing.FuzzInputOptions

container

Source line 1273

Fields

corpus: []const []const u8 = &.{}

std.testing.io

constant

Source line 24

std.testing.Io

alias

Source line 4

Alias of std.Io

std.testing.io_instance

variable

Source line 23

Io.Threaded

std.testing.log_level

variable

Source line 29

std.testing.math

alias

Source line 7

Alias of std.math

std.testing.random_seed

variable

Source line 11

Provides deterministic randomness in unit tests. Initialized on startup. Read-only after that.

u32

std.testing.Reader

container

Source line 1287

A Io.Reader that writes a predetermined list of buffers during stream.

Fields

calls: []const Call
interface: Io.Reader
next_call_index: usize
next_offset: usize
artificial_limit: Io.Limit = .unlimited

Further reduces how many bytes are written in each stream call.

std.testing.Reader.Call

container

Source line 1295

Fields

buffer: []const u8

std.testing.Reader.init

function

Source line 1299

pub fn init(buffer: []u8, calls: []const Call) Reader

Parameters

buffer: []u8
calls: []const Call

std.testing.Reader.stream

function

Source line 1313

fn stream(io_r: *Io.Reader, w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize

Parameters

io_r: *Io.Reader
w: *Io.Writer
limit: Io.Limit

Errors

EndOfStream

End of stream indicated from the Reader. This error cannot originate from the Writer.

ReadFailed

See the Reader implementation for detailed diagnostics.

WriteFailed

See the Writer implementation for detailed diagnostics.

std.testing.ReaderIndirect

container

Source line 1331

A Io.Reader that gets its data from another Io.Reader, and always writes to its own buffer (and returns 0) during stream and readVec. Note: zero length buffers are not supported.

Fields

in: *Io.Reader
interface: Io.Reader

std.testing.ReaderIndirect.init

function

Source line 1335

pub fn init(in: *Io.Reader, buffer: []u8) ReaderIndirect

Parameters

in: *Io.Reader
buffer: []u8

std.testing.ReaderIndirect.readVec

function

Source line 1352

fn readVec(r: *Io.Reader, _: [][]u8) Io.Reader.Error!usize

Parameters

r: *Io.Reader
_: [][]u8

Errors

EndOfStream
ReadFailed

See the Reader implementation for detailed diagnostics.

std.testing.ReaderIndirect.stream

function

Source line 1357

fn stream(r: *Io.Reader, _: *Io.Writer, _: Io.Limit) Io.Reader.StreamError!usize

Parameters

r: *Io.Reader
_: *Io.Writer
_: Io.Limit

Errors

EndOfStream

End of stream indicated from the Reader. This error cannot originate from the Writer.

ReadFailed

See the Reader implementation for detailed diagnostics.

WriteFailed

See the Writer implementation for detailed diagnostics.

std.testing.ReaderIndirect.streamInner

function

Source line 1362

fn streamInner(r: *Io.Reader) Io.Reader.Error!void

Parameters

r: *Io.Reader

Errors

EndOfStream
ReadFailed

See the Reader implementation for detailed diagnostics.

std.testing.refAllDecls

function

Source line 1264

Given a type, references all the declarations inside, so that the semantic analyzer sees them.

pub fn refAllDecls(comptime T: type) void

Parameters

T: type

std.testing.returnErrorUnion

function

Source line 646

fn returnErrorUnion() !u8

std.testing.SliceDiffer

type-function

Source line 435

fn SliceDiffer(comptime T: type) type

Parameters

T: type

Fields

start_index: usize
expected: []const T
actual: []const T
terminal_mode: Io.Terminal.Mode

std.testing.SliceDiffer.Self

alias

Source line 442

Alias of std.testing.SliceDiffer

std.testing.SliceDiffer.write

function

Source line 444

pub fn write(self: Self, writer: *Io.Writer) !void

Parameters

self: Self
writer: *Io.Writer

std.testing.Smith

alias

Source line 1271

Alias of std.testing.Smith

std.testing.std

alias

Source line 3

Alias of std

std.testing.tmpDir

function

Source line 606

pub fn tmpDir(opts: Io.Dir.OpenOptions) TmpDir

Parameters

std.testing.TmpDir

container

Source line 587

Fields

dir: Io.Dir
parent_dir: Io.Dir
sub_path: [sub_path_len]u8

std.testing.TmpDir.cleanup

function

Source line 598

pub fn cleanup(self: *TmpDir) void

Parameters

self: *TmpDir

std.testing.TmpDir.parent_dir_path

constant

Source line 596

Deprecated.

[]const u8

std.testing.TmpDir.random_bytes_count

constant

Source line 592

std.testing.TmpDir.sub_path_len

constant

Source line 593

std.testing.WriterIndirect

container

Source line 1394

A Io.Writer that writes its data to another Io.Writer, and only writes new data to its own buffer during drain. Note: zero length buffers are not supported.

Fields

out: *Io.Writer
interface: Io.Writer

std.testing.WriterIndirect.drain

function

Source line 1413

fn drain(w: *Io.Writer, data: []const []const u8, splat: usize) std.Io.Writer.Error!usize

Parameters

w: *Io.Writer
data: []const []const u8
splat: usize

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.testing.WriterIndirect.init

function

Source line 1398

pub fn init(out: *Io.Writer, buffer: []u8) WriterIndirect

Parameters

out: *Io.Writer
buffer: []u8
Source code

std/testing.zig

const builtin = @import("builtin");

const std = @import("std.zig");
const Io = std.Io;
const Environ = std.process.Environ;
const assert = std.debug.assert;
const math = std.math;

/// Provides deterministic randomness in unit tests.
/// Initialized on startup. Read-only after that.
pub var random_seed: u32 = 0;

pub const FailingAllocator = @import("testing/FailingAllocator.zig");
pub const failing_allocator = failing_allocator_instance.allocator();
var failing_allocator_instance = FailingAllocator.init(base_allocator_instance.allocator(), .{
    .fail_index = 0,
});
var base_allocator_instance = std.heap.FixedBufferAllocator.init("");

pub var allocator_instance: std.heap.SafeAllocator = undefined;
pub const allocator = if (builtin.is_test) allocator_instance.allocator() else @compileError("not testing");

pub var io_instance: Io.Threaded = undefined;
pub const io = if (builtin.is_test) io_instance.io() else @compileError("not testing");

pub var environ: Environ = if (builtin.is_test) undefined else @compileError("not testing");

/// TODO https://github.com/ziglang/zig/issues/5738
pub var log_level = std.log.Level.warn;

// Disable printing in tests for simple backends.
pub const backend_can_print = switch (builtin.zig_backend) {
    .stage2_aarch64,
    .stage2_loongarch,
    .stage2_powerpc,
    .stage2_riscv64,
    .stage2_spirv,
    => false,
    else => true,
};

/// Helper function for printing test failure information.
pub fn failPrint(comptime fmt: []const u8, args: anytype) void {
    if (@inComptime()) {
        @compileError(std.fmt.comptimePrint(fmt, args));
    } else if (backend_can_print) {
        std.debug.print(fmt, args);
    }
}

/// This function is intended to be used only in tests. When the two values are not
/// equal, prints diagnostics to stderr to show exactly how they are not equal,
/// then returns a test failure error.
/// `actual` and `expected` are coerced to a common type using peer type resolution.
pub inline fn expectEqual(expected: anytype, actual: anytype) !void {
    const T = @TypeOf(expected, actual);
    return expectEqualInner(T, expected, actual);
}

fn expectEqualInner(comptime T: type, expected: T, actual: T) !void {
    switch (@typeInfo(@TypeOf(actual))) {
        .noreturn,
        .@"opaque",
        .spirv,
        .frame,
        .@"anyframe",
        => @compileError("value of type " ++ @typeName(@TypeOf(actual)) ++ " encountered"),

        .undefined,
        .null,
        .void,
        => return,

        .type => {
            if (actual != expected) {
                failPrint("expected type {s}, found type {s}\n", .{ @typeName(expected), @typeName(actual) });
                return error.TestExpectedEqual;
            }
        },

        .bool,
        .int,
        .float,
        .comptime_float,
        .comptime_int,
        .enum_literal,
        .@"enum",
        .@"fn",
        .error_set,
        => {
            if (actual != expected) {
                failPrint("expected {any}, found {any}\n", .{ expected, actual });
                return error.TestExpectedEqual;
            }
        },

        .pointer => |pointer| {
            switch (pointer.size) {
                .one, .many, .c => {
                    if (actual != expected) {
                        failPrint("expected {*}, found {*}\n", .{ expected, actual });
                        return error.TestExpectedEqual;
                    }
                },
                .slice => {
                    if (actual.ptr != expected.ptr) {
                        failPrint("expected slice ptr {*}, found {*}\n", .{ expected.ptr, actual.ptr });
                        return error.TestExpectedEqual;
                    }
                    if (actual.len != expected.len) {
                        failPrint("expected slice len {}, found {}\n", .{ expected.len, actual.len });
                        return error.TestExpectedEqual;
                    }
                },
            }
        },

        .array => |array| try expectEqualSlices(array.child, &expected, &actual),

        .vector => |info| {
            const expect_array: [info.len]info.child = expected;
            const actual_array: [info.len]info.child = actual;
            try expectEqualSlices(info.child, &expect_array, &actual_array);
        },

        .@"struct" => |@"struct"| {
            inline for (@"struct".field_names) |field_name| {
                try expectEqual(@field(expected, field_name), @field(actual, field_name));
            }
        },

        .@"union" => |@"union"| if (@"union".backing_integer) |Int| {
            try expectEqual(@as(Int, @bitCast(expected)), @as(Int, @bitCast(actual)));
        } else switch (@"union".layout) {
            .@"packed" => {
                const Int = @Int(.unsigned, @bitSizeOf(T));
                try expectEqual(@as(Int, @bitCast(expected)), @as(Int, @bitCast(actual)));
            },
            .@"extern" => {
                const first_size = @bitSizeOf(@"union".field_types[0]);
                inline for (@"union".field_types) |field_type| {
                    if (@bitSizeOf(field_type) != first_size) {
                        @compileError("Unable to compare extern unions with varying field sizes for type " ++ @typeName(T));
                    }
                }
                const FieldInt = @Int(.unsigned, first_size);
                const expected_field = @field(expected, @"union".field_names[0]);
                const actual_field = @field(actual, @"union".field_names[0]);
                return expectEqual(
                    @as(FieldInt, @bitCast(expected_field)),
                    @as(FieldInt, @bitCast(actual_field)),
                );
            },
            .auto => {
                const Tag = @"union".tag_type orelse @compileError("byteSwapAllFields expects packed, extern, or tagged union");

                try expectEqual(@as(Tag, expected), @as(Tag, actual));
                switch (expected) {
                    inline else => |expected_payload, tag| {
                        const actual_payload = @field(actual, @tagName(tag));
                        try expectEqual(expected_payload, actual_payload);
                    },
                }
            },
        },

        .optional => {
            if (expected) |expected_payload| {
                if (actual) |actual_payload| {
                    try expectEqual(expected_payload, actual_payload);
                } else {
                    failPrint("expected {any}, found null\n", .{expected_payload});
                    return error.TestExpectedEqual;
                }
            } else {
                if (actual) |actual_payload| {
                    failPrint("expected null, found {any}\n", .{actual_payload});
                    return error.TestExpectedEqual;
                }
            }
        },

        .error_union => {
            if (expected) |expected_payload| {
                if (actual) |actual_payload| {
                    try expectEqual(expected_payload, actual_payload);
                } else |actual_err| {
                    failPrint("expected {any}, found {}\n", .{ expected_payload, actual_err });
                    return error.TestExpectedEqual;
                }
            } else |expected_err| {
                if (actual) |actual_payload| {
                    failPrint("expected {}, found {any}\n", .{ expected_err, actual_payload });
                    return error.TestExpectedEqual;
                } else |actual_err| {
                    try expectEqual(expected_err, actual_err);
                }
            }
        },
    }
}

test "expectEqual union(enum)" {
    const T = union(enum) {
        a: i32,
        b: f32,
    };

    const a10 = T{ .a = 10 };

    try expectEqual(a10, a10);
}

test "expectEqual union with comptime-only field" {
    const U = union(enum) {
        a: void,
        b: void,
        c: comptime_int,
    };

    try expectEqual(U{ .a = {} }, .a);
}

test "expectEqual nested array" {
    const a = [2][2]f32{
        [_]f32{ 1.0, 0.0 },
        [_]f32{ 0.0, 1.0 },
    };

    const b = [2][2]f32{
        [_]f32{ 1.0, 0.0 },
        [_]f32{ 0.0, 1.0 },
    };

    try expectEqual(a, b);
}

test "expectEqual vector" {
    const a: @Vector(4, u32) = @splat(4);
    const b: @Vector(4, u32) = @splat(4);

    try expectEqual(a, b);
}

test "expectEqual null" {
    const a = .{null};
    const b = @Vector(1, ?*u8){null};

    try expectEqual(a, b);
}

/// This function is intended to be used only in tests. When the actual value is
/// not approximately equal to the expected value, prints diagnostics to stderr
/// to show exactly how they are not equal, then returns a test failure error.
/// See `math.approxEqAbs` for more information on the tolerance parameter.
/// The types must be floating-point.
/// `actual` and `expected` are coerced to a common type using peer type resolution.
pub inline fn expectApproxEqAbs(expected: anytype, actual: anytype, tolerance: anytype) !void {
    const T = @TypeOf(expected, actual, tolerance);
    return expectApproxEqAbsInner(T, expected, actual, tolerance);
}

fn expectApproxEqAbsInner(comptime T: type, expected: T, actual: T, tolerance: T) !void {
    switch (@typeInfo(T)) {
        .float => if (!math.approxEqAbs(T, expected, actual, tolerance)) {
            failPrint("actual {}, not within absolute tolerance {} of expected {}\n", .{ actual, tolerance, expected });
            return error.TestExpectedApproxEqAbs;
        },

        .comptime_float => @compileError("Cannot approximately compare two comptime_float values"),

        else => @compileError("Unable to compare non floating point values"),
    }
}

test expectApproxEqAbs {
    inline for ([_]type{ f16, f32, f64, f128 }) |T| {
        const pos_x: T = 12.0;
        const pos_y: T = 12.06;
        const neg_x: T = -12.0;
        const neg_y: T = -12.06;

        try expectApproxEqAbs(pos_x, pos_y, 0.1);
        try expectApproxEqAbs(neg_x, neg_y, 0.1);
    }
}

/// This function is intended to be used only in tests. When the actual value is
/// not approximately equal to the expected value, prints diagnostics to stderr
/// to show exactly how they are not equal, then returns a test failure error.
/// See `math.approxEqRel` for more information on the tolerance parameter.
/// The types must be floating-point.
/// `actual` and `expected` are coerced to a common type using peer type resolution.
pub inline fn expectApproxEqRel(expected: anytype, actual: anytype, tolerance: anytype) !void {
    const T = @TypeOf(expected, actual, tolerance);
    return expectApproxEqRelInner(T, expected, actual, tolerance);
}

fn expectApproxEqRelInner(comptime T: type, expected: T, actual: T, tolerance: T) !void {
    switch (@typeInfo(T)) {
        .float => if (!math.approxEqRel(T, expected, actual, tolerance)) {
            failPrint("actual {}, not within relative tolerance {} of expected {}\n", .{ actual, tolerance, expected });
            return error.TestExpectedApproxEqRel;
        },

        .comptime_float => @compileError("Cannot approximately compare two comptime_float values"),

        else => @compileError("Unable to compare non floating point values"),
    }
}

test expectApproxEqRel {
    inline for ([_]type{ f16, f32, f64, f128 }) |T| {
        const eps_value = comptime math.floatEps(T);
        const sqrt_eps_value = comptime @sqrt(eps_value);

        const pos_x: T = 12.0;
        const pos_y: T = pos_x + 2 * eps_value;
        const neg_x: T = -12.0;
        const neg_y: T = neg_x - 2 * eps_value;

        try expectApproxEqRel(pos_x, pos_y, sqrt_eps_value);
        try expectApproxEqRel(neg_x, neg_y, sqrt_eps_value);
    }
}

/// This function is intended to be used only in tests. When the two slices are
/// not equal, it prints diagnostics to stderr to show exactly how they are not
/// equal (with the differences highlighted in red), then returns a test
/// failure error.
pub fn expectEqualSlices(comptime T: type, expected: []const T, actual: []const T) !void {
    const diff_index: usize = diff_index: {
        const shortest = @min(expected.len, actual.len);
        var index: usize = 0;
        while (index < shortest) : (index += 1) {
            if (!std.meta.eql(actual[index], expected[index])) break :diff_index index;
        }
        break :diff_index if (expected.len == actual.len) return else shortest;
    };
    if (!backend_can_print) return error.TestExpectedEqual;
    // Intentionally using the debug Io instance rather than the testing Io instance.
    const stderr = std.debug.lockStderr(&.{});
    defer std.debug.unlockStderr();
    const w = &stderr.file_writer.interface;
    failEqualSlices(T, expected, actual, diff_index, w, stderr.terminal_mode) catch {};
    return error.TestExpectedEqual;
}

fn failEqualSlices(
    comptime T: type,
    expected: []const T,
    actual: []const T,
    diff_index: usize,
    w: *Io.Writer,
    terminal_mode: Io.Terminal.Mode,
) !void {
    try w.print("slices differ. first difference occurs at index {d} (0x{X})\n", .{ diff_index, diff_index });

    // TODO: Should this be configurable by the caller?
    const max_lines: usize = 16;
    const max_window_size: usize = if (T == u8) max_lines * 16 else max_lines;

    // Print a maximum of max_window_size items of each input, starting just before the
    // first difference to give a bit of context.
    var window_start: usize = 0;
    if (@max(actual.len, expected.len) > max_window_size) {
        const alignment = if (T == u8) 16 else 2;
        window_start = std.mem.alignBackward(usize, diff_index - @min(diff_index, alignment), alignment);
    }
    const expected_window = expected[window_start..@min(expected.len, window_start + max_window_size)];
    const expected_truncated = window_start + expected_window.len < expected.len;
    const actual_window = actual[window_start..@min(actual.len, window_start + max_window_size)];
    const actual_truncated = window_start + actual_window.len < actual.len;

    var differ = if (T == u8) BytesDiffer{
        .expected = expected_window,
        .actual = actual_window,
        .terminal_mode = terminal_mode,
    } else SliceDiffer(T){
        .start_index = window_start,
        .expected = expected_window,
        .actual = actual_window,
        .terminal_mode = terminal_mode,
    };

    // Print indexes as hex for slices of u8 since it's more likely to be binary data where
    // that is usually useful.
    const index_fmt = if (T == u8) "0x{X}" else "{}";

    try w.print("\n============ expected this output: =============  len: {} (0x{X})\n\n", .{ expected.len, expected.len });
    if (window_start > 0) {
        if (T == u8) {
            try w.print("... truncated, start index: " ++ index_fmt ++ " ...\n", .{window_start});
        } else {
            try w.print("... truncated ...\n", .{});
        }
    }
    differ.write(w) catch {};
    if (expected_truncated) {
        const end_offset = window_start + expected_window.len;
        const num_missing_items = expected.len - (window_start + expected_window.len);
        if (T == u8) {
            try w.print("... truncated, indexes [" ++ index_fmt ++ "..] not shown, remaining bytes: " ++ index_fmt ++ " ...\n", .{ end_offset, num_missing_items });
        } else {
            try w.print("... truncated, remaining items: " ++ index_fmt ++ " ...\n", .{num_missing_items});
        }
    }

    // now reverse expected/actual and print again
    differ.expected = actual_window;
    differ.actual = expected_window;
    try w.print("\n============= instead found this: ==============  len: {} (0x{X})\n\n", .{ actual.len, actual.len });
    if (window_start > 0) {
        if (T == u8) {
            try w.print("... truncated, start index: " ++ index_fmt ++ " ...\n", .{window_start});
        } else {
            try w.print("... truncated ...\n", .{});
        }
    }
    differ.write(w) catch {};
    if (actual_truncated) {
        const end_offset = window_start + actual_window.len;
        const num_missing_items = actual.len - (window_start + actual_window.len);
        if (T == u8) {
            try w.print("... truncated, indexes [" ++ index_fmt ++ "..] not shown, remaining bytes: " ++ index_fmt ++ " ...\n", .{ end_offset, num_missing_items });
        } else {
            try w.print("... truncated, remaining items: " ++ index_fmt ++ " ...\n", .{num_missing_items});
        }
    }
    try w.print("\n================================================\n\n", .{});

    return error.TestExpectedEqual;
}

fn SliceDiffer(comptime T: type) type {
    return struct {
        start_index: usize,
        expected: []const T,
        actual: []const T,
        terminal_mode: Io.Terminal.Mode,

        const Self = @This();

        pub fn write(self: Self, writer: *Io.Writer) !void {
            const t: Io.Terminal = .{ .writer = writer, .mode = self.terminal_mode };
            for (self.expected, 0..) |value, i| {
                const full_index = self.start_index + i;
                const diff = if (i < self.actual.len) !std.meta.eql(self.actual[i], value) else true;
                if (diff) try t.setColor(.red);
                if (@typeInfo(T) == .pointer) {
                    try writer.print("[{}]{*}: {any}\n", .{ full_index, value, value });
                } else {
                    try writer.print("[{}]: {any}\n", .{ full_index, value });
                }
                if (diff) try t.setColor(.reset);
            }
        }
    };
}

const BytesDiffer = struct {
    expected: []const u8,
    actual: []const u8,
    terminal_mode: Io.Terminal.Mode,

    pub fn write(self: BytesDiffer, writer: *Io.Writer) !void {
        var expected_iterator = std.mem.window(u8, self.expected, 16, 16);
        var row: usize = 0;
        while (expected_iterator.next()) |chunk| {
            // to avoid having to calculate diffs twice per chunk
            var diffs: std.bit_set.Integer(16) = .{ .mask = 0 };
            for (chunk, 0..) |byte, col| {
                const absolute_byte_index = col + row * 16;
                const diff = if (absolute_byte_index < self.actual.len) self.actual[absolute_byte_index] != byte else true;
                if (diff) diffs.set(col);
                try self.writeDiff(writer, "{X:0>2} ", .{byte}, diff);
                if (col == 7) try writer.writeByte(' ');
            }
            try writer.writeByte(' ');
            if (chunk.len < 16) {
                var missing_columns = (16 - chunk.len) * 3;
                if (chunk.len < 8) missing_columns += 1;
                try writer.splatByteAll(' ', missing_columns);
            }
            for (chunk, 0..) |byte, col| {
                const diff = diffs.isSet(col);
                if (std.ascii.isPrint(byte)) {
                    try self.writeDiff(writer, "{c}", .{byte}, diff);
                } else {
                    // TODO: remove this `if` when https://github.com/ziglang/zig/issues/7600 is fixed
                    if (self.terminal_mode == .windows_api) {
                        try self.writeDiff(writer, ".", .{}, diff);
                        continue;
                    }

                    // Let's print some common control codes as graphical Unicode symbols.
                    // We don't want to do this for all control codes because most control codes apart from
                    // the ones that Zig has escape sequences for are likely not very useful to print as symbols.
                    switch (byte) {
                        '\n' => try self.writeDiff(writer, "␊", .{}, diff),
                        '\r' => try self.writeDiff(writer, "␍", .{}, diff),
                        '\t' => try self.writeDiff(writer, "␉", .{}, diff),
                        else => try self.writeDiff(writer, ".", .{}, diff),
                    }
                }
            }
            try writer.writeByte('\n');
            row += 1;
        }
    }

    fn terminal(self: *const BytesDiffer, writer: *Io.Writer) Io.Terminal {
        return .{ .writer = writer, .mode = self.terminal_mode };
    }

    fn writeDiff(self: BytesDiffer, writer: *Io.Writer, comptime fmt: []const u8, args: anytype, diff: bool) !void {
        if (diff) try self.terminal(writer).setColor(.red);
        try writer.print(fmt, args);
        if (diff) try self.terminal(writer).setColor(.reset);
    }
};

test expectEqualSlices {
    try expectEqualSlices(u8, "foo\x00", "foo\x00");
    try expectEqualSlices(u16, &[_]u16{ 100, 200, 300, 400 }, &[_]u16{ 100, 200, 300, 400 });
    const E = enum { foo, bar };
    const S = struct {
        v: E,
    };
    try expectEqualSlices(
        S,
        &[_]S{ .{ .v = .foo }, .{ .v = .bar }, .{ .v = .foo }, .{ .v = .bar } },
        &[_]S{ .{ .v = .foo }, .{ .v = .bar }, .{ .v = .foo }, .{ .v = .bar } },
    );
}

/// This function is intended to be used only in tests. When the two slices or two arrays are not equal,
/// or their sentinel (if any) are not the same, it prints diagnostics to stderr to show exactly how
/// they are not equal (with the differences highlighted in red), then returns a test failure error.
/// It partially depends on `expectEquaSlices` for printing diagnostics.
pub fn expectEqualSentinel(comptime T: type, comptime sentinel: T, expected: [:sentinel]const T, actual: [:sentinel]const T) !void {
    try expectEqualSlices(T, expected, actual);

    const expected_value_sentinel = blk: {
        switch (@typeInfo(@TypeOf(expected))) {
            .pointer => {
                break :blk expected[expected.len];
            },
            .array => |array_info| {
                const indexable_outside_of_bounds = @as([]const array_info.child, &expected);
                break :blk indexable_outside_of_bounds[indexable_outside_of_bounds.len];
            },
            else => {},
        }
    };

    const actual_value_sentinel = blk: {
        switch (@typeInfo(@TypeOf(actual))) {
            .pointer => {
                break :blk actual[actual.len];
            },
            .array => |array_info| {
                const indexable_outside_of_bounds = @as([]const array_info.child, &actual);
                break :blk indexable_outside_of_bounds[indexable_outside_of_bounds.len];
            },
            else => {},
        }
    };

    if (!std.meta.eql(sentinel, expected_value_sentinel)) {
        failPrint("expectEqualSentinel: 'expected' sentinel in memory is different from its type sentinel. type sentinel {}, in memory sentinel {}\n", .{ sentinel, expected_value_sentinel });
        return error.TestExpectedEqual;
    }

    if (!std.meta.eql(sentinel, actual_value_sentinel)) {
        failPrint("expectEqualSentinel: 'actual' sentinel in memory is different from its type sentinel. type sentinel {}, in memory sentinel {}\n", .{ sentinel, actual_value_sentinel });
        return error.TestExpectedEqual;
    }
}

/// This function is intended to be used only in tests.
/// When `ok` is false, returns a test failure error.
pub fn expect(ok: bool) !void {
    if (!ok) return error.TestUnexpectedResult;
}

pub const TmpDir = struct {
    dir: Io.Dir,
    parent_dir: Io.Dir,
    sub_path: [sub_path_len]u8,

    const random_bytes_count = 12;
    const sub_path_len = std.base64.url_safe.Encoder.calcSize(random_bytes_count);

    /// Deprecated.
    pub const parent_dir_path: []const u8 = ".zig-cache" ++ std.fs.path.sep_str ++ "tmp";

    pub fn cleanup(self: *TmpDir) void {
        self.dir.close(io);
        self.parent_dir.deleteTree(io, &self.sub_path) catch {};
        self.parent_dir.close(io);
        self.* = undefined;
    }
};

pub fn tmpDir(opts: Io.Dir.OpenOptions) TmpDir {
    comptime assert(builtin.is_test);
    var random_bytes: [TmpDir.random_bytes_count]u8 = undefined;
    io.random(&random_bytes);
    var sub_path: [TmpDir.sub_path_len]u8 = undefined;
    _ = std.base64.url_safe.Encoder.encode(&sub_path, &random_bytes);

    const cwd = Io.Dir.cwd();
    var cache_dir = cwd.createDirPathOpen(io, ".zig-cache", .{}) catch
        @panic("unable to make tmp dir for testing: unable to make and open .zig-cache dir");
    defer cache_dir.close(io);
    const parent_dir = cache_dir.createDirPathOpen(io, "tmp", .{}) catch
        @panic("unable to make tmp dir for testing: unable to make and open .zig-cache/tmp dir");
    const dir = parent_dir.createDirPathOpen(io, &sub_path, .{ .open_options = opts }) catch
        @panic("unable to make tmp dir for testing: unable to make and open the tmp dir");

    return .{
        .dir = dir,
        .parent_dir = parent_dir,
        .sub_path = sub_path,
    };
}

/// This function is intended to be used only in tests. When `actual_error_union` is not
/// `expected_error`, it prints diagnostics to stderr, then returns a test failure error.
pub fn expectError(expected_error: anyerror, actual_error_union: anytype) !void {
    if (actual_error_union) |actual_payload| {
        failPrint("expected error.{s}, found {any}\n", .{ @errorName(expected_error), actual_payload });
        return error.TestExpectedError;
    } else |actual_error| {
        if (expected_error != actual_error) {
            failPrint("expected error.{s}, found error.{s}\n", .{
                @errorName(expected_error),
                @errorName(actual_error),
            });
            return error.TestUnexpectedError;
        }
    }
}

fn returnErrorUnion() !u8 {
    return error.Expected;
}

test expectError {
    const actualErrorUnion = returnErrorUnion();
    try expectError(error.Expected, actualErrorUnion);
}

/// This function is intended to be used only in tests. When the formatted result of the template
/// and its arguments does not equal the expected text, it prints diagnostics to stderr to show how
/// they are not equal, then returns an error. It depends on `expectEqualStrings` for printing
/// diagnostics.
pub fn expectFmt(expected: []const u8, comptime template: []const u8, args: anytype) !void {
    if (@inComptime()) {
        var buffer: [std.fmt.count(template, args)]u8 = undefined;
        return expectEqualStrings(expected, try std.mem.print(&buffer, template, args));
    }
    const actual = try std.fmt.allocPrint(allocator, template, args);
    defer allocator.free(actual);
    return expectEqualStrings(expected, actual);
}

// This function is intended to be used only in test. When the two strings are not equal,
/// it prints diagnostics to stderr to show how they are not equal, then returns an error.
pub fn expectEqualStrings(expected: []const u8, actual: []const u8) !void {
    if (std.mem.findDiff(u8, actual, expected)) |diff_index| {
        if (@inComptime()) {
            @compileError(std.fmt.comptimePrint("\nexpected:\n{s}\nfound:\n{s}\ndifference starts at index {d}", .{
                expected, actual, diff_index,
            }));
        }
        failPrint("\n====== expected this output: =========\n", .{});
        failPrintWithVisibleNewlines(expected);
        failPrint("\n======== instead found this: =========\n", .{});
        failPrintWithVisibleNewlines(actual);
        failPrint("\n======================================\n", .{});

        var diff_line_number: usize = 1;
        for (expected[0..diff_index]) |value| {
            if (value == '\n') diff_line_number += 1;
        }
        failPrint("First difference occurs on line {d}:\n", .{diff_line_number});

        failPrint("expected:\n", .{});
        failPrintIndicatorLine(expected, diff_index);

        failPrint("found:\n", .{});
        failPrintIndicatorLine(actual, diff_index);

        return error.TestExpectedEqual;
    }
}

test expectEqualStrings {
    try expectEqualStrings("foo", "foo");
}

/// This function is intended to be used only in test. When the start of `actual` and `expected_starts_with`
/// are not equal, it prints diagnostics to stderr to show how they are not equal, then returns an error.
pub fn expectStringStartsWith(actual: []const u8, expected_starts_with: []const u8) !void {
    if (std.mem.startsWith(u8, actual, expected_starts_with))
        return;

    const shortened_actual = if (actual.len >= expected_starts_with.len)
        actual[0..expected_starts_with.len]
    else
        actual;

    failPrint("\n====== expected to start with: =========\n", .{});
    failPrintWithVisibleNewlines(expected_starts_with);
    failPrint("\n====== instead started with: ===========\n", .{});
    failPrintWithVisibleNewlines(shortened_actual);
    failPrint("\n========= full output: ==============\n", .{});
    failPrintWithVisibleNewlines(actual);
    failPrint("\n======================================\n", .{});

    return error.TestExpectedStartsWith;
}

test expectStringStartsWith {
    try expectStringStartsWith("foobar", "foo");
}

/// This function is intended to be used only in test. When the end of `actual` and `expected_ends_with`
/// are not equal, it prints diagnostics to stderr to show how they are not equal, then returns an error.
pub fn expectStringEndsWith(actual: []const u8, expected_ends_with: []const u8) !void {
    if (std.mem.endsWith(u8, actual, expected_ends_with))
        return;

    const shortened_actual = if (actual.len >= expected_ends_with.len)
        actual[(actual.len - expected_ends_with.len)..]
    else
        actual;

    failPrint("\n====== expected to end with: =========\n", .{});
    failPrintWithVisibleNewlines(expected_ends_with);
    failPrint("\n====== instead ended with: ===========\n", .{});
    failPrintWithVisibleNewlines(shortened_actual);
    failPrint("\n========= full output: ==============\n", .{});
    failPrintWithVisibleNewlines(actual);
    failPrint("\n======================================\n", .{});

    return error.TestExpectedEndsWith;
}

test expectStringEndsWith {
    try expectStringEndsWith("foobar", "bar");
}

/// This function is intended to be used only in tests. When the two values are not
/// deeply equal, prints diagnostics to stderr to show exactly how they are not equal,
/// then returns a test failure error.
/// `actual` and `expected` are coerced to a common type using peer type resolution.
///
/// Deeply equal is defined as follows:
/// Primitive types are deeply equal if they are equal using `==` operator.
/// Struct values are deeply equal if their corresponding fields are deeply equal.
/// Container types(like Array/Slice/Vector) deeply equal when their corresponding elements are deeply equal.
/// Pointer values are deeply equal if values they point to are deeply equal.
///
/// Note: Self-referential structs are supported (e.g. things like std.SinglyLinkedList)
/// but may cause infinite recursion or stack overflow when a container has a pointer to itself.
pub inline fn expectEqualDeep(expected: anytype, actual: anytype) error{TestExpectedEqual}!void {
    const T = @TypeOf(expected, actual);
    return expectEqualDeepInner(T, expected, actual);
}

fn expectEqualDeepInner(comptime T: type, expected: T, actual: T) error{TestExpectedEqual}!void {
    switch (@typeInfo(@TypeOf(actual))) {
        .noreturn,
        .@"opaque",
        .spirv,
        .frame,
        .@"anyframe",
        => @compileError("value of type " ++ @typeName(@TypeOf(actual)) ++ " encountered"),

        .undefined,
        .null,
        .void,
        => return,

        .type => {
            if (actual != expected) {
                failPrint("expected type {s}, found type {s}\n", .{ @typeName(expected), @typeName(actual) });
                return error.TestExpectedEqual;
            }
        },

        .bool,
        .int,
        .float,
        .comptime_float,
        .comptime_int,
        .enum_literal,
        .@"enum",
        .@"fn",
        .error_set,
        => {
            if (actual != expected) {
                failPrint("expected {any}, found {any}\n", .{ expected, actual });
                return error.TestExpectedEqual;
            }
        },

        .pointer => |pointer| {
            switch (pointer.size) {
                // We have no idea what is behind those pointers, so the best we can do is `==` check.
                .c, .many => {
                    if (actual != expected) {
                        failPrint("expected {*}, found {*}\n", .{ expected, actual });
                        return error.TestExpectedEqual;
                    }
                },
                .one => {
                    // Length of those pointers are runtime value, so the best we can do is `==` check.
                    switch (@typeInfo(pointer.child)) {
                        .@"fn", .@"opaque" => {
                            if (actual != expected) {
                                failPrint("expected {*}, found {*}\n", .{ expected, actual });
                                return error.TestExpectedEqual;
                            }
                        },
                        else => try expectEqualDeep(expected.*, actual.*),
                    }
                },
                .slice => {
                    if (expected.len != actual.len) {
                        failPrint("Slice len not the same, expected {d}, found {d}\n", .{ expected.len, actual.len });
                        return error.TestExpectedEqual;
                    }
                    var i: usize = 0;
                    while (i < expected.len) : (i += 1) {
                        expectEqualDeep(expected[i], actual[i]) catch |e| {
                            failPrint("index {d} incorrect. expected {any}, found {any}\n", .{
                                i, expected[i], actual[i],
                            });
                            return e;
                        };
                    }
                },
            }
        },

        .array => {
            if (expected.len != actual.len) {
                failPrint("Array len not the same, expected {d}, found {d}\n", .{ expected.len, actual.len });
                return error.TestExpectedEqual;
            }
            var i: usize = 0;
            while (i < expected.len) : (i += 1) {
                expectEqualDeep(expected[i], actual[i]) catch |e| {
                    failPrint("index {d} incorrect. expected {any}, found {any}\n", .{
                        i, expected[i], actual[i],
                    });
                    return e;
                };
            }
        },

        .vector => |info| {
            if (info.len != @typeInfo(@TypeOf(actual)).vector.len) {
                failPrint("Vector len not the same, expected {d}, found {d}\n", .{ info.len, @typeInfo(@TypeOf(actual)).vector.len });
                return error.TestExpectedEqual;
            }
            inline for (0..info.len) |i| {
                expectEqualDeep(expected[i], actual[i]) catch |e| {
                    failPrint("index {d} incorrect. expected {any}, found {any}\n", .{
                        i, expected[i], actual[i],
                    });
                    return e;
                };
            }
        },

        .@"struct" => |structType| {
            inline for (structType.field_names) |field_name| {
                expectEqualDeep(@field(expected, field_name), @field(actual, field_name)) catch |e| {
                    failPrint("Field {s} incorrect. expected {any}, found {any}\n", .{ field_name, @field(expected, field_name), @field(actual, field_name) });
                    return e;
                };
            }
        },

        .@"union" => |union_info| {
            if (union_info.tag_type == null) {
                @compileError("Unable to compare untagged union values for type " ++ @typeName(@TypeOf(actual)));
            }

            const Tag = std.meta.Tag(@TypeOf(expected));

            const expectedTag = @as(Tag, expected);
            const actualTag = @as(Tag, actual);

            try expectEqual(expectedTag, actualTag);

            // we only reach this switch if the tags are equal
            switch (expected) {
                inline else => |val, tag| {
                    try expectEqualDeep(val, @field(actual, @tagName(tag)));
                },
            }
        },

        .optional => {
            if (expected) |expected_payload| {
                if (actual) |actual_payload| {
                    try expectEqualDeep(expected_payload, actual_payload);
                } else {
                    failPrint("expected {any}, found null\n", .{expected_payload});
                    return error.TestExpectedEqual;
                }
            } else {
                if (actual) |actual_payload| {
                    failPrint("expected null, found {any}\n", .{actual_payload});
                    return error.TestExpectedEqual;
                }
            }
        },

        .error_union => {
            if (expected) |expected_payload| {
                if (actual) |actual_payload| {
                    try expectEqualDeep(expected_payload, actual_payload);
                } else |actual_err| {
                    failPrint("expected {any}, found {any}\n", .{ expected_payload, actual_err });
                    return error.TestExpectedEqual;
                }
            } else |expected_err| {
                if (actual) |actual_payload| {
                    failPrint("expected {any}, found {any}\n", .{ expected_err, actual_payload });
                    return error.TestExpectedEqual;
                } else |actual_err| {
                    try expectEqualDeep(expected_err, actual_err);
                }
            }
        },
    }
}

test "expectEqualDeep primitive type" {
    try expectEqualDeep(1, 1);
    try expectEqualDeep(true, true);
    try expectEqualDeep(1.5, 1.5);
    try expectEqualDeep(u8, u8);
    try expectEqualDeep(error.Bad, error.Bad);

    // optional
    {
        const foo: ?u32 = 1;
        const bar: ?u32 = 1;
        try expectEqualDeep(foo, bar);
        try expectEqualDeep(?u32, ?u32);
    }
    // function type
    {
        const fnType = struct {
            fn foo() void {
                unreachable;
            }
        }.foo;
        try expectEqualDeep(fnType, fnType);
    }
    // enum with formatter
    {
        const TestEnum = enum {
            a,
            b,

            pub fn format(self: @This(), writer: *Io.Writer) !void {
                try writer.writeAll(@tagName(self));
            }
        };
        try expectEqualDeep(TestEnum.b, TestEnum.b);
    }
}

test "expectEqualDeep pointer" {
    try comptime expectEqualDeep(&1, &1);
    try expectEqualDeep(&@as(u32, 1), &@as(u32, 1));
}

test "expectEqualDeep composite type" {
    try expectEqualDeep("abc", "abc");
    const s1: []const u8 = "abc";
    const s2 = "abcd";
    const s3: []const u8 = s2[0..3];
    try expectEqualDeep(s1, s3);

    const TestStruct = struct { s: []const u8 };
    try expectEqualDeep(TestStruct{ .s = "abc" }, TestStruct{ .s = "abc" });
    try expectEqualDeep([_][]const u8{ "a", "b", "c" }, [_][]const u8{ "a", "b", "c" });

    // vector
    try expectEqualDeep(@as(@Vector(4, u32), @splat(4)), @as(@Vector(4, u32), @splat(4)));

    // nested array
    {
        const a = [2][2]f32{
            [_]f32{ 1.0, 0.0 },
            [_]f32{ 0.0, 1.0 },
        };

        const b = [2][2]f32{
            [_]f32{ 1.0, 0.0 },
            [_]f32{ 0.0, 1.0 },
        };

        try expectEqualDeep(a, b);
        try expectEqualDeep(&a, &b);
    }

    // inferred union
    const TestStruct2 = struct {
        const A = union(enum) { b: B, c: C };
        const B = struct {};
        const C = struct { a: *const A };
    };

    const union1 = TestStruct2.A{ .b = .{} };
    try expectEqualDeep(
        TestStruct2.A{ .c = .{ .a = &union1 } },
        TestStruct2.A{ .c = .{ .a = &union1 } },
    );
}

/// Helper function for printing test failure information.
pub fn failPrintIndicatorLine(source: []const u8, indicator_index: usize) void {
    const line_begin_index = if (std.mem.findScalarLast(u8, source[0..indicator_index], '\n')) |line_begin|
        line_begin + 1
    else
        0;
    const line_end_index = if (std.mem.findScalar(u8, source[indicator_index..], '\n')) |line_end|
        (indicator_index + line_end)
    else
        source.len;

    failPrintLine(source[line_begin_index..line_end_index]);
    for (line_begin_index..indicator_index) |_|
        failPrint(" ", .{});
    if (indicator_index >= source.len)
        failPrint("^ (end of string)\n", .{})
    else
        failPrint("^ ('\\x{x:0>2}')\n", .{source[indicator_index]});
}

/// Helper function for printing test failure information.
pub fn failPrintWithVisibleNewlines(source: []const u8) void {
    var i: usize = 0;
    while (std.mem.findScalar(u8, source[i..], '\n')) |nl| : (i += nl + 1) {
        failPrintLine(source[i..][0..nl]);
    }
    failPrint("{s}␃\n", .{source[i..]}); // End of Text symbol (ETX)
}

/// Helper function for printing test failure information.
pub fn failPrintLine(line: []const u8) void {
    if (line.len != 0) switch (line[line.len - 1]) {
        ' ', '\t' => return failPrint("{s}⏎\n", .{line}), // Return symbol
        else => {},
    };
    failPrint("{s}\n", .{line});
}

/// Exhaustively check that allocation failures within `test_fn` are handled without
/// introducing memory leaks. If used with the `testing.allocator` as the `backing_allocator`,
/// it will also be able to detect double frees, etc (when runtime safety is enabled).
///
/// The provided `test_fn` must have a `std.mem.Allocator` as its first argument,
/// and must have a return type of `!void`. Any extra arguments of `test_fn` can
/// be provided via the `extra_args` tuple.
///
/// Any relevant state shared between runs of `test_fn` *must* be reset within `test_fn`.
///
/// The strategy employed is to:
/// - Run the test function once to get the total number of allocations.
/// - Then, iterate and run the function X more times, incrementing
///   the failing index each iteration (where X is the total number of
///   allocations determined previously)
///
/// Expects that `test_fn` has a deterministic number of memory allocations:
/// - If an allocation was made to fail during a run of `test_fn`, but `test_fn`
///   didn't return `error.OutOfMemory`, then `error.SwallowedOutOfMemoryError`
///   is returned from `checkAllAllocationFailures`. You may want to ignore this
///   depending on whether or not the code you're testing includes some strategies
///   for recovering from `error.OutOfMemory`.
/// - If a run of `test_fn` with an expected allocation failure executes without
///   an allocation failure being induced, then `error.NondeterministicMemoryUsage`
///   is returned. This error means that there are allocation points that won't be
///   tested by the strategy this function employs (that is, there are sometimes more
///   points of allocation than the initial run of `test_fn` detects).
///
/// ---
///
/// Here's an example using a simple test case that will cause a leak when the
/// allocation of `bar` fails (but will pass normally):
///
/// ```zig
/// test {
///     const length: usize = 10;
///     const allocator = std.testing.allocator;
///     var foo = try allocator.alloc(u8, length);
///     var bar = try allocator.alloc(u8, length);
///
///     allocator.free(foo);
///     allocator.free(bar);
/// }
/// ```
///
/// The test case can be converted to something that this function can use by
/// doing:
///
/// ```zig
/// fn testImpl(allocator: std.mem.Allocator, length: usize) !void {
///     var foo = try allocator.alloc(u8, length);
///     var bar = try allocator.alloc(u8, length);
///
///     allocator.free(foo);
///     allocator.free(bar);
/// }
///
/// test {
///     const length: usize = 10;
///     const allocator = std.testing.allocator;
///     try std.testing.checkAllAllocationFailures(allocator, testImpl, .{length});
/// }
/// ```
///
/// Running this test will show that `foo` is leaked when the allocation of
/// `bar` fails. The simplest fix, in this case, would be to use defer like so:
///
/// ```zig
/// fn testImpl(allocator: std.mem.Allocator, length: usize) !void {
///     var foo = try allocator.alloc(u8, length);
///     defer allocator.free(foo);
///     var bar = try allocator.alloc(u8, length);
///     defer allocator.free(bar);
/// }
/// ```
pub fn checkAllAllocationFailures(
    backing_allocator: std.mem.Allocator,
    comptime test_fn: anytype,
    extra_args: CheckAllAllocationFailuresExtraArgs(@TypeOf(test_fn)),
) !void {
    // Try it once with unlimited memory, make sure it works
    const needed_alloc_count = x: {
        var failing_allocator_inst = std.testing.FailingAllocator.init(backing_allocator, .{
            .resize_fail_index = 0,
        });

        try @call(.auto, test_fn, .{failing_allocator_inst.allocator()} ++ extra_args);
        break :x failing_allocator_inst.alloc_index;
    };

    for (0..needed_alloc_count) |fail_index| {
        var failing_allocator_inst = std.testing.FailingAllocator.init(backing_allocator, .{
            .fail_index = fail_index,
            .resize_fail_index = 0,
        });

        if (@call(.auto, test_fn, .{failing_allocator_inst.allocator()} ++ extra_args)) |_| {
            if (failing_allocator_inst.has_induced_failure) {
                return error.SwallowedOutOfMemoryError;
            } else {
                return error.NondeterministicMemoryUsage;
            }
        } else |err| switch (err) {
            error.OutOfMemory => {
                if (failing_allocator_inst.allocated_bytes != failing_allocator_inst.freed_bytes) {
                    failPrint(
                        "\nfail_index: {d}/{d}\nallocated bytes: {d}\nfreed bytes: {d}\nallocations: {d}\ndeallocations: {d}\nallocation that was made to fail: {f}",
                        .{
                            fail_index,
                            needed_alloc_count,
                            failing_allocator_inst.allocated_bytes,
                            failing_allocator_inst.freed_bytes,
                            failing_allocator_inst.allocations,
                            failing_allocator_inst.deallocations,
                            std.debug.FormatStackTrace{
                                .stack_trace = failing_allocator_inst.getStackTrace(),
                            },
                        },
                    );
                    return error.MemoryLeakDetected;
                }
            },
            else => |e| return e,
        }
    }
}

fn CheckAllAllocationFailuresExtraArgs(comptime TestFn: type) type {
    switch (@typeInfo(@typeInfo(TestFn).@"fn".return_type.?)) {
        .error_union => |info| {
            if (info.payload != void) {
                @compileError("Return type must be !void");
            }
        },
        else => @compileError("Return type must be !void"),
    }

    const ArgsTuple = std.meta.ArgsTuple(TestFn);

    const field_types = @typeInfo(ArgsTuple).@"struct".field_types;
    if (field_types.len == 0 or field_types[0] != std.mem.Allocator) {
        @compileError("The provided function must have an " ++ @typeName(std.mem.Allocator) ++ " as its first argument");
    }

    var extra_args: [field_types.len - 1]type = undefined;
    for (&extra_args, field_types[1..]) |*arg, field_type| {
        arg.* = field_type;
    }

    return @Tuple(&extra_args);
}

test "checkAllAllocationFailures provide result type to 'extra_args' argument" {
    try checkAllAllocationFailures(
        std.testing.allocator,
        struct {
            fn f(ally: std.mem.Allocator, params: struct {
                foo_len: u32,
                bar_len: u32,
            }) !void {
                const foo = try ally.alloc(u8, params.foo_len);
                defer ally.free(foo);
                const bar = try ally.alloc(u8, params.bar_len);
                defer ally.free(bar);
            }
        }.f,
        .{
            .{
                .foo_len = 3,
                .bar_len = 5,
            },
        },
    );
}

test "checkAllAllocationFailures does not depend on in-place resizes" {
    // `std.testing.allocator` never reuses memory, so whether a list can grow in place depends
    // on where in its bucket it landed, which differs from one run to the next.
    const S = struct {
        fn f(gpa: std.mem.Allocator) !void {
            var a: std.ArrayList(u8) = .empty;
            defer a.deinit(gpa);
            var b: std.ArrayList(u8) = .empty;
            defer b.deinit(gpa);
            for (0..2000) |i| {
                try a.append(gpa, @truncate(i));
                try b.append(gpa, @truncate(i));
            }
        }
    };
    try checkAllAllocationFailures(std.testing.allocator, S.f, .{});
}

/// Given a type, references all the declarations inside, so that the semantic analyzer sees them.
pub fn refAllDecls(comptime T: type) void {
    if (!builtin.is_test) return;
    inline for (comptime std.meta.declarations(T)) |decl_name| {
        _ = &@field(T, decl_name);
    }
}

pub const Smith = @import("testing/Smith.zig");

pub const FuzzInputOptions = struct {
    corpus: []const []const u8 = &.{},
};

/// Inline to avoid coverage instrumentation.
pub inline fn fuzz(
    context: anytype,
    comptime testOne: fn (context: @TypeOf(context), smith: *Smith) anyerror!void,
    options: FuzzInputOptions,
) anyerror!void {
    return @import("root").fuzz(context, testOne, options);
}

/// A `Io.Reader` that writes a predetermined list of buffers during `stream`.
pub const Reader = struct {
    calls: []const Call,
    interface: Io.Reader,
    next_call_index: usize,
    next_offset: usize,
    /// Further reduces how many bytes are written in each `stream` call.
    artificial_limit: Io.Limit = .unlimited,

    pub const Call = struct {
        buffer: []const u8,
    };

    pub fn init(buffer: []u8, calls: []const Call) Reader {
        return .{
            .next_call_index = 0,
            .next_offset = 0,
            .interface = .{
                .vtable = &.{ .stream = stream },
                .buffer = buffer,
                .seek = 0,
                .end = 0,
            },
            .calls = calls,
        };
    }

    fn stream(io_r: *Io.Reader, w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize {
        const r: *Reader = @alignCast(@fieldParentPtr("interface", io_r));
        if (r.calls.len - r.next_call_index == 0) return error.EndOfStream;
        const call = r.calls[r.next_call_index];
        const buffer = r.artificial_limit.sliceConst(limit.sliceConst(call.buffer[r.next_offset..]));
        const n = try w.write(buffer);
        r.next_offset += n;
        if (call.buffer.len - r.next_offset == 0) {
            r.next_call_index += 1;
            r.next_offset = 0;
        }
        return n;
    }
};

/// A `Io.Reader` that gets its data from another `Io.Reader`, and always
/// writes to its own buffer (and returns 0) during `stream` and `readVec`.
/// Note: zero length buffers are not supported.
pub const ReaderIndirect = struct {
    in: *Io.Reader,
    interface: Io.Reader,

    pub fn init(in: *Io.Reader, buffer: []u8) ReaderIndirect {
        assert(buffer.len > 0);

        return .{
            .in = in,
            .interface = .{
                .vtable = &.{
                    .stream = stream,
                    .readVec = readVec,
                },
                .buffer = buffer,
                .seek = 0,
                .end = 0,
            },
        };
    }

    fn readVec(r: *Io.Reader, _: [][]u8) Io.Reader.Error!usize {
        try streamInner(r);
        return 0;
    }

    fn stream(r: *Io.Reader, _: *Io.Writer, _: Io.Limit) Io.Reader.StreamError!usize {
        try streamInner(r);
        return 0;
    }

    fn streamInner(r: *Io.Reader) Io.Reader.Error!void {
        const r_indirect: *ReaderIndirect = @alignCast(@fieldParentPtr("interface", r));

        // If there's no room remaining in the buffer at all, make room.
        if (r.buffer.len == r.end) {
            try r.rebase(r.buffer.len);
        }

        var writer: Io.Writer = .{
            .buffer = r.buffer,
            .end = r.end,
            .vtable = &.{
                .drain = Io.Writer.unreachableDrain,
                .rebase = Io.Writer.unreachableRebase,
            },
        };
        defer r.end = writer.end;

        r_indirect.in.streamExact(&writer, r.buffer.len - r.end) catch |err| switch (err) {
            // Only forward EndOfStream if no new bytes were written to the buffer
            error.EndOfStream => |e| if (r.end == writer.end) {
                return e;
            },
            error.WriteFailed => unreachable,
            else => |e| return e,
        };
    }
};

/// A `Io.Writer` that writes its data to another `Io.Writer`, and only
/// writes new data to its own buffer during `drain`.
/// Note: zero length buffers are not supported.
pub const WriterIndirect = struct {
    out: *Io.Writer,
    interface: Io.Writer,

    pub fn init(out: *Io.Writer, buffer: []u8) WriterIndirect {
        assert(buffer.len > 0);

        return .{
            .out = out,
            .interface = .{
                .vtable = &.{
                    .drain = drain,
                },
                .buffer = buffer,
                .end = 0,
            },
        };
    }

    fn drain(w: *Io.Writer, data: []const []const u8, splat: usize) std.Io.Writer.Error!usize {
        const w_indirect: *WriterIndirect = @alignCast(@fieldParentPtr("interface", w));

        // Write all data in the buffer to `out`
        try w_indirect.out.writeAll(w.buffer[0..w.end]);
        w.end = 0;

        // Refill buffer using data
        {
            const end_before_fill = w.end;
            for (data[0 .. data.len - 1]) |bytes| {
                const dest = w.buffer[w.end..];
                const len = @min(bytes.len, dest.len);
                @memcpy(dest[0..len], bytes[0..len]);
                w.end += len;
            }
            const pattern = data[data.len - 1];
            switch (pattern.len) {
                0 => {},
                1 => {
                    const len = @min(w.buffer[w.end..].len, splat);
                    @memset(w.buffer[w.end..][0..len], pattern[0]);
                    w.end += len;
                },
                else => {
                    const dest = w.buffer[w.end..];
                    for (0..splat) |i| {
                        const start_i = i * pattern.len;
                        if (start_i >= dest.len) break;
                        const remaining = dest[start_i..];
                        const len = @min(pattern.len, remaining.len);
                        @memcpy(remaining[0..len], pattern[0..len]);
                        w.end += len;
                    }
                },
            }

            return w.end - end_before_fill;
        }
    }
};

test {
    _ = &Smith;
}