ProcessHarness: builder, lifecycle, stdout/stderr capture

charles commented

2026-04-11 10:55:37 +00:00

Owner

User story

As a test author, I want to declaratively configure and start an application binary with one builder call, so that I can run end-to-end tests against it without writing process-management plumbing.

Acceptance criteria

Builder

HarnessBuilder exposes: command(impl Into<String>), arg, args, env(K, V), working_dir, health_url, ws_url, startup_timeout (default 15 s), shutdown_timeout (default 10 s), health_poll_interval (default 100 ms), build().
ProcessHarness::builder() returns a fresh HarnessBuilder.

Start

start() spawns the configured child process.
DISPLAY and XDG_RUNTIME_DIR are forwarded automatically from the parent env if set (for GUI apps).
User-set env vars are applied on top and can override the auto-forwarded ones.
working_dir is set on the child if provided.

Stop

stop() sends SIGTERM, waits up to shutdown_timeout for graceful exit, then escalates to SIGKILL.
Returns the final exit status.
Drop triggers a synchronous best-effort SIGTERM + SIGKILL so a panicking test never leaks the child.

Restart

restart() calls stop() then start() and only returns Ok once the health check passes again (delegated to the health-polling story).

Stdout/stderr capture

stdout and stderr are captured into bounded in-memory ring buffers (default 1 MiB each, oldest dropped).
stdout() -> &str and stderr() -> &str accessors return current content.
On startup or shutdown failure the returned error includes the last 50 lines of captured stderr.

Platform

Linux is the primary target. Windows may be gated with #[cfg(unix)] and an unimplemented! on Windows (clearly documented).

Out of scope

HTTP health polling (separate issue).
Authentication / token forwarding to the WS client.

References

Spec §1 (Process harness), §3.1 (ProcessHarness), §5.1–5.3 (process management details)

## User story As a **test author**, I want to declaratively configure and start an application binary with one builder call, so that I can run end-to-end tests against it without writing process-management plumbing. ## Acceptance criteria ### Builder - [ ] `HarnessBuilder` exposes: `command(impl Into<String>)`, `arg`, `args`, `env(K, V)`, `working_dir`, `health_url`, `ws_url`, `startup_timeout` (default 15 s), `shutdown_timeout` (default 10 s), `health_poll_interval` (default 100 ms), `build()`. - [ ] `ProcessHarness::builder()` returns a fresh `HarnessBuilder`. ### Start - [ ] `start()` spawns the configured child process. - [ ] `DISPLAY` and `XDG_RUNTIME_DIR` are forwarded automatically from the parent env if set (for GUI apps). - [ ] User-set env vars are applied on top and can override the auto-forwarded ones. - [ ] `working_dir` is set on the child if provided. ### Stop - [ ] `stop()` sends `SIGTERM`, waits up to `shutdown_timeout` for graceful exit, then escalates to `SIGKILL`. - [ ] Returns the final exit status. - [ ] `Drop` triggers a synchronous best-effort `SIGTERM` + `SIGKILL` so a panicking test never leaks the child. ### Restart - [ ] `restart()` calls `stop()` then `start()` and only returns `Ok` once the health check passes again (delegated to the health-polling story). ### Stdout/stderr capture - [ ] stdout and stderr are captured into bounded in-memory ring buffers (default 1 MiB each, oldest dropped). - [ ] `stdout() -> &str` and `stderr() -> &str` accessors return current content. - [ ] On startup or shutdown failure the returned error includes the **last 50 lines of captured stderr**. ### Platform - [ ] Linux is the primary target. Windows may be gated with `#[cfg(unix)]` and an `unimplemented!` on Windows (clearly documented). ## Out of scope - HTTP health polling (separate issue). - Authentication / token forwarding to the WS client. ## References - Spec §1 (Process harness), §3.1 (ProcessHarness), §5.1–5.3 (process management details)

charles added this to the v0.1.0 milestone

2026-04-11 10:55:37 +00:00

charles added the

area:harness

type:user-story

labels

2026-04-11 10:55:37 +00:00

charles referenced this issue

2026-04-11 11:01:11 +00:00

Screenshot capture on test failure (GNOME, focused-window) #18

charles referenced this issue from a commit

2026-04-11 12:04:19 +00:00