feat: add support for interactive mode

Author: pyk

src/root.zig

@@ -1,6 +1,9 @@
 const std = @import("std");
 const testing = std.testing;
 const Child = std.process.Child;
+const Writer = std.Io.Writer;
+const Reader = std.Io.Reader;
+const ArrayList = std.ArrayList;
 
 /// Options for `run` controlling I/O, allocator, and output limits.
 pub const RunOptions = struct {
@@ -151,3 +154,85 @@ pub fn run(options: RunOptions) !RunResult {
         .allocator = options.allocator,
     };
 }
+
+/// Options for `spawn` controlling the child process environment.
+pub const SpawnOptions = struct {
+    argv: []const []const u8,
+    allocator: std.mem.Allocator = testing.allocator,
+    cwd: ?[]const u8 = null,
+    env_map: ?*const std.process.EnvMap = null,
+};
+
+/// Manages a long-running, interactive child process for testing.
+pub const InteractiveProcess = struct {
+    child: Child,
+    stdout_buffer: [1024]u8 = undefined,
+    stdin_buffer: [1024]u8 = undefined,
+    stderr_buffer: [1024]u8 = undefined,
+
+    /// Cleans up resources and ensures the child process is terminated.
+    /// This should always be called, typically with `defer`.
+    pub fn deinit(self: *InteractiveProcess) void {
+        if (self.child.stdin) |stdin_file| {
+            stdin_file.close();
+            self.child.stdin = null;
+        }
+        _ = self.child.wait() catch {};
+    }
+
+    /// Writes bytes to the child process's stdin.
+    pub fn writeToStdin(self: *InteractiveProcess, bytes: []const u8) !void {
+        const stdin_file = self.child.stdin orelse return error.MissingStdin;
+        var stdin_writer = stdin_file.writer(&self.stdin_buffer);
+        var stdin = &stdin_writer.interface;
+        try stdin.writeAll(bytes);
+        try stdin.flush();
+    }
+
+    /// Reads from the child's stdout until a newline is found or the buffer is full.
+    /// The returned slice does not include the newline character.
+    pub fn readLineFromStdout(self: *InteractiveProcess) ![]const u8 {
+        const stdout_file = self.child.stdout orelse return error.MissingStdout;
+        var stdout_reader = stdout_file.reader(&self.stdout_buffer);
+        var stdout = &stdout_reader.interface;
+        const line = try stdout.takeDelimiter('\n') orelse return error.EmptyLine;
+        // Handle potential CR on Windows if the child outputs CRLF
+        const trimmed = std.mem.trimEnd(u8, line, "\r");
+        return trimmed;
+    }
+
+    /// Reads from the child's stderr until a newline is found.
+    pub fn readLineFromStderr(self: *InteractiveProcess) ![]const u8 {
+        const stderr_file = self.child.stderr orelse return error.MissingStderr;
+        var stderr_reader = stderr_file.reader(&self.stderr_buffer);
+        var stderr = &stderr_reader.interface;
+        const line = try stderr.takeDelimiter('\n') orelse return error.EmptyLine;
+        // Handle potential CR on Windows if the child outputs CRLF
+        const trimmed = std.mem.trimEnd(u8, line, "\r");
+        return trimmed;
+    }
+};
+
+/// Spawns an executable for interactive testing.
+///
+/// Returns an `InteractiveProcess` object to manage the child process's
+/// lifecycle and I/O. The caller is responsible for calling `deinit()`
+/// on the returned object to ensure cleanup.
+pub fn spawn(options: SpawnOptions) !InteractiveProcess {
+    var child = Child.init(options.argv, options.allocator);
+    child.cwd = options.cwd;
+    child.env_map = options.env_map;
+
+    // We need pipes for all streams to interact with them
+    child.stdin_behavior = .Pipe;
+    child.stdout_behavior = .Pipe;
+    child.stderr_behavior = .Pipe;
+
+    try child.spawn();
+    errdefer {
+        // If anything fails after spawn, ensure we kill the process
+        _ = child.kill() catch {};
+    }
+
+    return InteractiveProcess{ .child = child };
+}

src/test.zig

@@ -124,11 +124,7 @@ test "run: executable not found" {
         defer tmp.deinit();
         try testing.expect(false);
     } else |err| {
-        // Got an error as expected. Nothing more to assert (error kinds vary by platform).
-        // Print the error (to reference it) and consider this test successful
-        // because an error was expected.
-        std.debug.print("spawn error: {any}\n", .{err});
-        try testing.expect(true);
+        try testing.expectEqual(error.FileNotFound, err);
     }
 }
 
@@ -173,3 +169,20 @@ test "run: with env_map" {
 
     try testing.expectEqualStrings("hello-env\n", result.stdout);
 }
+
+test "spawn: interactive mode" {
+    const argv = &[_][]const u8{ "cmdtest", "--interactive" };
+    var proc = try cmdtest.spawn(.{ .argv = argv });
+    defer proc.deinit();
+
+    try proc.writeToStdin("PING\n");
+    try testing.expectEqualStrings("PONG", try proc.readLineFromStdout());
+
+    try proc.writeToStdin("ECHO works\n");
+    try testing.expectEqualStrings("works", try proc.readLineFromStdout());
+
+    try proc.writeToStdin("EXIT\n");
+
+    const term = try proc.child.wait();
+    try testing.expectEqual(@as(u8, 0), term.Exited);
+}

src/test_exe.zig

@@ -21,12 +21,17 @@ pub fn main() !void {
     var abort_requested = false;
     var print_cwd = false;
     var getenv_name: ?[]const u8 = null;
+    var interactive = false;
     while (i < args.len) : (i += 1) {
         const s = args[i];
         if (std.mem.eql(u8, s, "--stderr")) {
             use_stderr = true;
             continue;
         }
+        if (std.mem.eql(u8, s, "--interactive")) {
+            interactive = true;
+            continue;
+        }
         if (std.mem.eql(u8, s, "--abort")) {
             abort_requested = true;
             continue;
@@ -69,6 +74,36 @@ pub fn main() !void {
     var writer = if (use_stderr) std.fs.File.stderr().writer(&buf) else std.fs.File.stdout().writer(&buf);
     const io = &writer.interface;
 
+    if (interactive) {
+        var stdin_buffer: [1024]u8 = undefined;
+        var stdin_reader = std.fs.File.stdin().reader(&stdin_buffer);
+        var stdin = &stdin_reader.interface;
+
+        while (stdin.takeDelimiterExclusive('\n')) |line| {
+            const trimmed = std.mem.trimRight(u8, line, "\r");
+            if (std.mem.eql(u8, trimmed, "PING")) {
+                try io.writeAll("PONG\n");
+            } else if (std.mem.startsWith(u8, trimmed, "ECHO ")) {
+                try io.writeAll(trimmed[5..]);
+                try io.writeAll("\n");
+            } else if (std.mem.eql(u8, trimmed, "EXIT")) {
+                break;
+            } else {
+                try io.print("UNKNOWN: {s}\n", .{trimmed});
+            }
+            try io.flush();
+            // NOTE: this is required in order to prevents the program loop forever
+            _ = try stdin.take(1);
+        } else |err| switch (err) {
+            error.EndOfStream => {
+                std.debug.print("END OF STREAM\n", .{});
+            },
+            else => |e| return e,
+        }
+
+        return;
+    }
+
     if (getenv_name) |name| {
         var env_map = std.process.getEnvMap(allocator) catch @panic("fails to get map");
         defer env_map.deinit();