authorgravatar for k4@noreply.codeberg.orgK4 <k4@noreply.codeberg.org> 2026-07-28 23:26:46+03:00
committergravatar for k4@noreply.codeberg.orgK4 <k4@noreply.codeberg.org> 2026-08-05 11:17:45+03:00
log5ce96175327328f4b039ce44e646653a5b2725ba
treef21548131b495f5dc912c6d5d8b20f6b40eb0c3c
parentf7bb482ff38973a94ef693d558993aeac26fc991

std.testing: improve doc comments

1 files changed, 13 insertions(+), 5 deletions(-)

lib/std/testing.zig+13-5
......@@ -50,8 +50,8 @@ pub fn failPrint(comptime fmt: []const u8, args: anytype) void {
5050 }
5151}
5252
53/// This function is intended to be used only in tests. It prints diagnostics to stderr
54/// and then returns a test failure error when actual_error_union is not expected_error.
53/// This function is intended to be used only in tests. When `actual_error_union` is not
54/// `expected_error`, it prints diagnostics to stderr, then returns a test failure error.
5555pub fn expectError(expected_error: anyerror, actual_error_union: anytype) !void {
5656 if (actual_error_union) |actual_payload| {
5757 failPrint("expected error.{s}, found {any}\n", .{ @errorName(expected_error), actual_payload });
......@@ -358,7 +358,7 @@ test expectApproxEqRel {
358358}
359359
360360/// This function is intended to be used only in tests. When the two slices are
361/// not equal, prints diagnostics to stderr to show exactly how they are not
361/// not equal, it prints diagnostics to stderr to show exactly how they are not
362362/// equal (with the differences highlighted in red), then returns a test
363363/// failure error.
364364pub fn expectEqualSlices(comptime T: type, expected: []const T, actual: []const T) !void {
......@@ -567,8 +567,10 @@ test {
567567 );
568568}
569569
570/// This function is intended to be used only in tests. Checks that two slices or two arrays are equal,
571/// including that their sentinel (if any) are the same. Will error if given another type.
570/// This function is intended to be used only in tests. When the two slices or two arrays are not equal,
571/// or their sentinel (if any) are not the same, it prints diagnostics to stderr to show exactly how
572/// they are not equal (with the differences highlighted in red), then returns a test failure error.
573/// It partially depends on `expectEquaSlices` for printing diagnostics.
572574pub fn expectEqualSentinel(comptime T: type, comptime sentinel: T, expected: [:sentinel]const T, actual: [:sentinel]const T) !void {
573575 try expectEqualSlices(T, expected, actual);
574576
......@@ -654,6 +656,8 @@ pub fn tmpDir(opts: Io.Dir.OpenOptions) TmpDir {
654656 };
655657}
656658
659/// This function is intended to be used only in test. When the two strings are not equal,
660/// it prints diagnostics to stderr to show how they are not equal, then returns an error.
657661pub fn expectEqualStrings(expected: []const u8, actual: []const u8) !void {
658662 if (std.mem.findDiff(u8, actual, expected)) |diff_index| {
659663 if (@inComptime()) {
......@@ -683,6 +687,8 @@ pub fn expectEqualStrings(expected: []const u8, actual: []const u8) !void {
683687 }
684688}
685689
690/// This function is intended to be used only in test. When the start of `actual` and `expected_starts_with`
691/// are not equal, it prints diagnostics to stderr to show how they are not equal, then returns an error.
686692pub fn expectStringStartsWith(actual: []const u8, expected_starts_with: []const u8) !void {
687693 if (std.mem.startsWith(u8, actual, expected_starts_with))
688694 return;
......@@ -703,6 +709,8 @@ pub fn expectStringStartsWith(actual: []const u8, expected_starts_with: []const
703709 return error.TestExpectedStartsWith;
704710}
705711
712/// This function is intended to be used only in test. When the end of `actual` and `expected_ends_with`
713/// are not equal, it prints diagnostics to stderr to show how they are not equal, then returns an error.
706714pub fn expectStringEndsWith(actual: []const u8, expected_ends_with: []const u8) !void {
707715 if (std.mem.endsWith(u8, actual, expected_ends_with))
708716 return;