Skip to content

Tests and proofs

Every fork writes a timeline as it is used: created, ready, each command, each test run, each shell session, destroyed. When the fork ends, that timeline becomes a proof: a document that outlives the fork and is kept 30 days.

A proof has:

  • A headline such as “Ran in a copy of orders-api. 1 test run passed. 3 commands.”
  • A stamp: all passed, N failed, or ran (no tests).
  • Facts: stack, fork id, repository, branch, commit, who or what ran it, time to ready, start time, total time.
  • Test runs: name, command, result, counts, duration.
  • The timeline: time in UTC, what ran and where, exit code, duration, and the last lines of output for anything that produced some.

A proof with one failed command: the red stamp, the test runs table, and the failing output open in the timeline.

  • forkstage down from the CLI writes one for the fork it strikes, and publishes it to the workspace.
  • An agent finishing through the MCP server does the same.
  • The GitHub App writes one per pull request run and posts its summary as the comment.
  • forkstage proof <id> prints a fork’s proof as Markdown (--json for the document), including after it is gone.

forkstage test runs the recipe’s tests list inside the fork. Each is a command in a service; Forkstage records exit code, duration, and counts when it recognises the output:

Tool Counts read
Jest, Vitest Tests: 24 passed, 1 failed
node:test # pass 3 / # fail 0
pytest 24 passed, 1 failed
Go ok / FAIL per package
JUnit / Maven Surefire Tests run: 24, Failures: 1
Custom scripts print tests 6 · pass 6 · fail 0 and it is read too

A test run whose command exits non-zero is a failure whatever its output says.

The timeline opens the first failing command’s output by default. The output tail is the last lines only (never more than a few kilobytes); run the command again with forkstage exec inside a live fork for the full picture.

It replaces “the agent said the tests pass” with the record. On a pull request it is the comment; in the dashboard it is the row under Proofs; from the CLI it is the Markdown you paste anywhere.