cmdtest

cmdtest

CLI testing for Zig.

Installation

1. Fetch the latest release:

    zig fetch --save=cmdtest https://github.com/pyk/cmdtest/archive/v0.3.0.tar.gz
   

   This updates build.zig.zon.

2. Write your test file. Example: test/mycli.zig.

     const std = @import("std");
     const cmdtest = @import("cmdtest");
     const testing = std.testing;
   
     test "via exe name" {
         const argv = &[_][]const u8{"mycli"};
         var result = try cmdtest.run(testing.io, .{ .argv = argv });
         defer result.deinit();
   
         try testing.expectEqualStrings("project-exe\n", result.stderr);
     }
   
     test "via path" {
         const argv = &[_][]const u8{"./zig-out/bin/mycli"};
         var result = try cmdtest.run(testing.io, .{ .argv = argv });
         defer result.deinit();
   
         try testing.expectEqualStrings("project-exe\n", result.stderr);
     }
   

3. Register the test in build.zig:

     const std = @import("std");
     const cmdtest = @import("cmdtest");
   
     pub fn build(b: *std.Build) void {
         const target = b.standardTargetOptions(.{});
   
         // Your CLI
         const cli = b.addExecutable(.{
             .name = "mycli",
             .root_module = b.createModule(.{
                 .root_source_file = b.path("src/main.zig"),
                 .target = target,
             }),
         });
         b.installArtifact(cli);
   
         // Register new test
         const cli_test = cmdtest.add(b, .{
             .name = "mycli",
             .test_file = b.path("test/mycli.zig"),
         });
   
         const test_step = b.step("test", "Run tests");
         test_step.dependOn(&cli_test.step);
     }
   

4. Run the tests:

    zig build test --summary all
   

See minimal Zig project cmdtest-example.

Usage

There are only 2 functions:

• add(b, options) registers a CLI test step in build.zig. zig build test will run the tests.
• run(io, options) spawns a child process, captures stdout and stderr (up to a limit), waits for the child to finish, and returns a RunResult.

Basic run and stdout assertion:

const std = @import("std");
const cmdtest = @import("cmdtest");
const testing = std.testing;

test "echo" {
    const argv = &[_][]const u8{"echo", "hello"};
    var result = try cmdtest.run(testing.io, .{ .argv = argv });
    defer result.deinit();

    try testing.expectEqualStrings("hello\n", result.stdout);
}

Write to stdin and capture stdout:

const std = @import("std");
const cmdtest = @import("cmdtest");
const testing = std.testing;

test "cat" {
    const argv = &[_][]const u8{"cat"};
    const input = "a\nb\n";
    var result = try cmdtest.run(testing.io, .{ .argv = argv, .stdin = input });
    defer result.deinit();

    try testing.expectEqualStrings(input, result.stdout);
}

Limit how many stdin bytes are sent:

const payload = large_slice; // some []const u8
var result = try cmdtest.run(testing.io, .{
  .argv = argv,
  .stdin = payload,
  .max_stdin_bytes = 1024, // truncate to 1 KiB
});
defer result.deinit();

And you can do much more:

• Automatically discover built artifacts.
• Capture stderr output.
• Limit how much output is captured.
• Run with a custom working directory.
• Run with a custom environment map.
• Handle exit status and signals.
• Detect spawn errors.

See src/test_exe.zig.

Some additional notes about the usage of allocator:

• run uses testing.allocator by default.
• You can pass a different allocator in RunOptions.allocator to control where captured buffers are allocated.

Development

Install the Zig toolchain via mise (optional):

mise trust
mise install

Run tests:

make test

Build library:

make build

License

See LICENSE.