🎓 A1Learner
🔍
0 of 46 lessons completed

Zig Test Assertions

A test assertion is a check inside a test block that compares a real value with an expected value. When the two differ, the test fails.

Numbers with expectEqual

expectEqual is the right choice for numbers. The expected value comes first, then the real value.

const std = @import("std");
fn add(a: i32, b: i32) i32 {
    return a + b;
}
fn double(n: i32) i32 {
    return n * 2;
}
fn square(n: i32) i32 {
    return n * n;
}
test "add works" {
    try std.testing.expectEqual(@as(i32, 5), add(2, 3));
}
test "double works" {
    try std.testing.expectEqual(@as(i32, 8), double(4));
}
test "square works" {
    try std.testing.expectEqual(@as(i32, 9), square(3));
}

Strings with expectEqualStrings

Strings need a string comparison, not a number comparison. expectEqualStrings checks every character.

const std = @import("std");
fn greeting() []const u8 {
    return "hello, zig";
}
fn farewell() []const u8 {
    return "goodbye, zig";
}
test "greeting matches" {
    try std.testing.expectEqualStrings("hello, zig", greeting());
}
test "farewell matches" {
    try std.testing.expectEqualStrings("goodbye, zig", farewell());
}

Booleans with expect

A boolean value needs no expected value beside it. expect passes when the value is true.

const std = @import("std");
fn isPositive(n: i32) bool {
    return n > 0;
}
test "positive number passes" {
    try std.testing.expect(isPositive(7));
}
test "zero is not positive" {
    try std.testing.expect(!isPositive(0));
}
test "negative number is not positive" {
    try std.testing.expect(!isPositive(-3));
}

Example

const std = @import("std");
fn add(a: i32, b: i32) i32 {
    return a + b;
}
fn isPositive(n: i32) bool {
    return n > 0;
}
fn greeting() []const u8 {
    return "hello, zig";
}
fn farewell() []const u8 {
    return "goodbye, zig";
}
test "add works" {
    try std.testing.expectEqual(@as(i32, 9), add(4, 5));
}
test "positive check works" {
    try std.testing.expect(isPositive(2));
}
test "greeting matches" {
    try std.testing.expectEqualStrings("hello, zig", greeting());
}
test "farewell matches" {
    try std.testing.expectEqualStrings("goodbye, zig", farewell());
}

Key points

  • Assertion: an assertion is a check that a value is what you expect.
  • expectEqual compares two values of the same type and fails when they differ.
  • expectEqualStrings compares two strings and fails when any character differs.
  • expect checks a boolean value and fails when the value is false.
  • Put the expected value first in expectEqual, so a failure reads expected against actual.
  • Choose the most exact assertion for the value, so a failure points at the exact mismatch.

This run mixes all three assertion kinds, one per test. Each test uses the assertion that fits its value. The number test uses expectEqual, the boolean test uses expect, and the string tests use expectEqualStrings.

Try it Yourself

Edit the code, then press Run.

Running is simulated

Exercise

In expectEqual, which value comes first?