Setup snapshot testings Behavior matching tests is helpful, but it prevents me from adding, changing or improving existing functionality. Snapshot testing solves this problem. Here is my plan: 1. Add a way to fix time (new CLI arg or C API something) 2. Create snapshots for behavior matching tests 3. Delete behavior matching tests This file-based snapshotting works great with external tools. In a future when I add a structured output (e.g. JSON,) difftastic would help diff-ing a lot. The reason I choose "version" command is it does not rely on system time. Even "report" command prints current time to output and that messes snapshot testing up.

Changes

6 changed files (+174/-0)

• REUSE.toml
  • @@ -20,3 +20,10 @@ "(c) Paul Schlyter, 1989, 1992",
    "(c) 2000,2004,2022 Daniel Risacher", ] SPDX-License-Identifier = "GPL-3.0-only" + + [[annotations]] + path = [ + "tests/snapshot/**.txt", + ] + SPDX-FileCopyrightText = "Copyright (C) 2025 Shota FUJI" + SPDX-License-Identifier = "GPL-3.0-only"
• build.zig
  • @@ -23,6 +23,7 @@ const optimize = b.standardOptimizeOption(.{});
    const man_opt = b.option(bool, "man", "Builds and installs man pages") orelse false; const legacy = b.option(bool, "legacy", "Build legacy C program") orelse false; const version = b.option([]const u8, "version", "Application version, without \"v\" prefix") orelse "dev"; + const update_snapshot = b.option(bool, "update-snapshot", "Update snapshot on snapshot tests") orelse false; const exe = addExe(b, .{ .target = target,
  • @@ -162,6 +163,30 @@
    break :e2e_tests step; }; + // "zig build snapshot-test" + const snapshot_tests = snapshot_test: { + const step = b.step("snapshot-test", "Run snapshot tests"); + + const t = b.addTest(.{ + .name = "snapshot_test", + .target = target, + .optimize = optimize, + .root_source_file = b.path("tests/snapshot/main.zig"), + }); + + const config = b.addOptions(); + config.addOptionPath("bin", exe.getEmittedBin()); + config.addOptionPath("test_src_root", b.path("tests/snapshot/")); + config.addOption(bool, "update_snapshot", update_snapshot); + + t.root_module.addOptions("config", config); + + const run = b.addRunArtifact(t); + step.dependOn(&run.step); + + break :snapshot_test step; + }; + // "zig build test" { const step = b.step("test", "Run all tests");
  • @@ -169,6 +194,7 @@
    step.dependOn(unit_tests); step.dependOn(behavior_tests); step.dependOn(e2e_tests); + step.dependOn(snapshot_tests); } }
• tests/snapshot/main.zig (new)
  • @@ -0,0 +1,20 @@
    + // Copyright (C) 2025 Shota FUJI + // + // This program is free software: you can redistribute it and/or modify + // it under the terms of the GNU General Public License as published by + // the Free Software Foundation, either version 3 of the License, or + // (at your option) any later version. + // + // This program is distributed in the hope that it will be useful, + // but WITHOUT ANY WARRANTY; without even the implied warranty of + // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + // GNU General Public License for more details. + // + // You should have received a copy of the GNU General Public License + // along with this program. If not, see <https://www.gnu.org/licenses/>. + // + // SPDX-License-Identifier: GPL-3.0-only + + test { + _ = @import("./version.zig"); + }
• tests/snapshot/snapshot.zig (new)
  • @@ -0,0 +1,81 @@
    + // Copyright (C) 2025 Shota FUJI + // + // This program is free software: you can redistribute it and/or modify + // it under the terms of the GNU General Public License as published by + // the Free Software Foundation, either version 3 of the License, or + // (at your option) any later version. + // + // This program is distributed in the hope that it will be useful, + // but WITHOUT ANY WARRANTY; without even the implied warranty of + // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + // GNU General Public License for more details. + // + // You should have received a copy of the GNU General Public License + // along with this program. If not, see <https://www.gnu.org/licenses/>. + // + // SPDX-License-Identifier: GPL-3.0-only + + const std = @import("std"); + + const config = @import("config"); + + pub const SnapshotError = error{ + ProcessNotExited, + }; + + const test_name_prefix = "test."; + + pub fn expectMatchSnapshot( + location: std.builtin.SourceLocation, + run: *const std.process.Child.RunResult, + ) !void { + var arena = std.heap.ArenaAllocator.init(std.testing.allocator); + defer arena.deinit(); + + const allocator = arena.allocator(); + + switch (run.term) { + .Exited => {}, + else => { + std.debug.print("Program did not exit: {s}\n", .{@tagName(run.term)}); + return SnapshotError.ProcessNotExited; + }, + } + + const filename = if (std.mem.startsWith(u8, location.fn_name, test_name_prefix)) + location.fn_name[test_name_prefix.len..] + else + location.fn_name; + + var src_dir = try std.fs.openDirAbsolute(config.test_src_root, .{ .no_follow = true }); + defer src_dir.close(); + + const current = src_dir.readFileAlloc(allocator, filename, std.math.maxInt(usize)) catch |err| { + if (config.update_snapshot) { + std.debug.print("Writing snapshot to {s}\n", .{filename}); + try src_dir.writeFile(.{ + .data = run.stdout, + .sub_path = filename, + }); + return; + } + + std.debug.print( + "Unable to open snapshot file {s}. Create using -Dupdate-snapshot option\n", + .{filename}, + ); + return err; + }; + + if (!std.mem.eql(u8, current, run.stdout) and config.update_snapshot) { + std.debug.print("Writing snapshot to {s}\n", .{filename}); + try src_dir.writeFile(.{ + .data = run.stdout, + .sub_path = filename, + }); + return; + } + + // Let std.testing print diffs + try std.testing.expectEqualStrings(current, run.stdout); + }
• tests/snapshot/version.zig (new)
  • @@ -0,0 +1,39 @@
    + // Copyright (C) 2025 Shota FUJI + // + // This program is free software: you can redistribute it and/or modify + // it under the terms of the GNU General Public License as published by + // the Free Software Foundation, either version 3 of the License, or + // (at your option) any later version. + // + // This program is distributed in the hope that it will be useful, + // but WITHOUT ANY WARRANTY; without even the implied warranty of + // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + // GNU General Public License for more details. + // + // You should have received a copy of the GNU General Public License + // along with this program. If not, see <https://www.gnu.org/licenses/>. + // + // SPDX-License-Identifier: GPL-3.0-only + + const std = @import("std"); + + const config = @import("config"); + + const snapshot = @import("./snapshot.zig"); + + test "version_snapshot.txt" { + var env = std.process.EnvMap.init(std.testing.allocator); + defer env.deinit(); + + try env.put("TZ", "UTC"); + + const result = try std.process.Child.run(.{ + .allocator = std.testing.allocator, + .argv = &.{ config.bin, "--version" }, + .env_map = &env, + }); + defer std.testing.allocator.free(result.stderr); + defer std.testing.allocator.free(result.stdout); + + try snapshot.expectMatchSnapshot(@src(), &result); + }
• tests/snapshot/version_snapshot.txt (new)
  • @@ -0,0 +1,1 @@
    + dev