builtinstdIoEnvironassertmathrandom_seedFailingAllocatorfailing_allocatorfailing_allocator_instancebase_allocator_instanceallocator_instanceallocatorio_instanceioenvironlog_levelbackend_can_printfailPrintexpectEqualexpectEqualInnerexpectApproxEqAbsexpectApproxEqAbsInnerexpectApproxEqRelexpectApproxEqRelInnerexpectEqualSlicesfailEqualSlicesSliceDifferBytesDifferexpectEqualSentinelexpectTmpDirtmpDirexpectErrorreturnErrorUnionexpectFmtexpectEqualStringsexpectStringStartsWithexpectStringEndsWithexpectEqualDeepexpectEqualDeepInnerfooformatABCfailPrintIndicatorLinefailPrintWithVisibleNewlinesfailPrintLinecheckAllAllocationFailuresCheckAllAllocationFailuresExtraArgsffrefAllDeclsSmithFuzzInputOptionsfuzzReaderReaderIndirectWriterIndirect
std.testing.A
container
Fields
std.testing.allocator
constant
std.testing.allocator_instance
variable
std.heap.SafeAllocator
std.testing.assert
alias
Alias of std.debug.assert
std.testing.B
namespace
std.testing.backend_can_print
constant
std.testing.base_allocator_instance
variable
std.testing.builtin
constant
std.testing.BytesDiffer
container
Fields
std.testing.BytesDiffer.terminal
function
fn terminal(self: *const BytesDiffer, writer: *Io.Writer) Io.Terminal
Parameters
self: *const BytesDiffer
writer: *Io.Writer
std.testing.BytesDiffer.write
function
pub fn write(self: BytesDiffer, writer: *Io.Writer) !void
Parameters
self: BytesDiffer
writer: *Io.Writer
std.testing.BytesDiffer.writeDiff
function
fn writeDiff(self: BytesDiffer, writer: *Io.Writer, comptime fmt: []const u8, args: anytype, diff: bool) !void
Parameters
std.testing.C
container
Fields
a: *const A
std.testing.checkAllAllocationFailures
function
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, buttest_fndidn't returnerror.OutOfMemory, thenerror.SwallowedOutOfMemoryErroris returned fromcheckAllAllocationFailures. You may want to ignore this depending on whether or not the code you're testing includes some strategies for recovering fromerror.OutOfMemory. - If a run of
test_fnwith an expected allocation failure executes without an allocation failure being induced, thenerror.NondeterministicMemoryUsageis 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 oftest_fndetects).
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
fn CheckAllAllocationFailuresExtraArgs(comptime TestFn: type) type
Parameters
TestFn: type
std.testing.environ
variable
Environ
std.testing.Environ
alias
Alias of std.process.Environ
std.testing.expect
function
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
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
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
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
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
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
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
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
fn expectEqualInner(comptime T: type, expected: T, actual: T) !void
Parameters
T: type
expected: T
actual: T
std.testing.expectEqualSentinel
function
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
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
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
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
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
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
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
fn f(ally: std.mem.Allocator, params: struct { foo_len: u32, bar_len: u32, }) !void
Parameters
std.testing.f
function
fn f(gpa: std.mem.Allocator) !void
Parameters
std.testing.failEqualSlices
function
fn failEqualSlices( comptime T: type, expected: []const T, actual: []const T, diff_index: usize, w: *Io.Writer, terminal_mode: Io.Terminal.Mode, ) !void
Parameters
std.testing.failing_allocator
constant
std.testing.failing_allocator_instance
variable
std.testing.FailingAllocator
alias
Alias of std.testing.FailingAllocator
std.testing.failPrint
function
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
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
Helper function for printing test failure information.
pub fn failPrintLine(line: []const u8) void
Parameters
line: []const u8
std.testing.failPrintWithVisibleNewlines
function
Helper function for printing test failure information.
pub fn failPrintWithVisibleNewlines(source: []const u8) void
Parameters
source: []const u8
std.testing.foo
function
fn foo() void
std.testing.format
function
pub fn format(self: @This(), writer: *Io.Writer) !void
Parameters
std.testing.fuzz
function
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
Fields
corpus: []const []const u8 = &.{}
std.testing.io
constant
std.testing.Io
alias
Alias of std.Io
std.testing.io_instance
variable
Io.Threaded
std.testing.log_level
variable
std.testing.math
alias
Alias of std.math
std.testing.random_seed
variable
Provides deterministic randomness in unit tests. Initialized on startup. Read-only after that.
u32
std.testing.Reader
container
Fields
std.testing.Reader.Call
container
Fields
buffer: []const u8
std.testing.Reader.init
function
pub fn init(buffer: []u8, calls: []const Call) Reader
Parameters
buffer: []u8
calls: []const Call
std.testing.Reader.stream
function
fn stream(io_r: *Io.Reader, w: *Io.Writer, limit: Io.Limit) Io.Reader.StreamError!usize
Parameters
Errors
std.testing.ReaderIndirect
container
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
std.testing.ReaderIndirect.init
function
pub fn init(in: *Io.Reader, buffer: []u8) ReaderIndirect
Parameters
std.testing.ReaderIndirect.readVec
function
fn readVec(r: *Io.Reader, _: [][]u8) Io.Reader.Error!usize
Parameters
Errors
- EndOfStream
- ReadFailed
See the
Readerimplementation for detailed diagnostics.
std.testing.ReaderIndirect.stream
function
fn stream(r: *Io.Reader, _: *Io.Writer, _: Io.Limit) Io.Reader.StreamError!usize
Parameters
Errors
std.testing.ReaderIndirect.streamInner
function
fn streamInner(r: *Io.Reader) Io.Reader.Error!void
Parameters
Errors
- EndOfStream
- ReadFailed
See the
Readerimplementation for detailed diagnostics.
std.testing.refAllDecls
function
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
fn returnErrorUnion() !u8
std.testing.SliceDiffer
type-function
fn SliceDiffer(comptime T: type) type
Parameters
T: type
Fields
std.testing.SliceDiffer.Self
alias
Alias of std.testing.SliceDiffer
std.testing.SliceDiffer.write
function
pub fn write(self: Self, writer: *Io.Writer) !void
Parameters
std.testing.Smith
alias
Alias of std.testing.Smith
std.testing.std
alias
Alias of std
std.testing.tmpDir
function
pub fn tmpDir(opts: Io.Dir.OpenOptions) TmpDir
Parameters
opts: Io.Dir.OpenOptions
std.testing.TmpDir
container
Fields
std.testing.TmpDir.cleanup
function
pub fn cleanup(self: *TmpDir) void
Parameters
self: *TmpDir
std.testing.TmpDir.parent_dir_path
constant
Deprecated.
[]const u8
std.testing.TmpDir.random_bytes_count
constant
std.testing.TmpDir.sub_path_len
constant
std.testing.WriterIndirect
container
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
std.testing.WriterIndirect.drain
function
fn drain(w: *Io.Writer, data: []const []const u8, splat: usize) std.Io.Writer.Error!usize
Parameters
Errors
- WriteFailed
See the
Writerimplementation for detailed diagnostics.
std.testing.WriterIndirect.init
function
pub fn init(out: *Io.Writer, buffer: []u8) WriterIndirect
Parameters
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;
}