runtime-proof-kit

Proof bundles for apps that are supposed to run.

runtime-proof-kit is a tiny Playwright-powered CLI that opens a URL, checks expected text, captures a screenshot, and writes a structured proof report. It is built for AI-assisted coding, PR handoffs, demos, and lightweight QA where "the code changed" is less useful than "the app started, rendered, and left evidence."

Get Started

Choose the path that fits your workflow:

Run a one-off proof from npm:

npx --yes runtime-proof-kit check \
  --url https://example.com \
  --expect-text "Example Domain"

After installing in a project:

npm install --save-dev runtime-proof-kit
npx runtime-proof check --url https://example.com --expect-text "Example Domain"

That creates a proof bundle:

proof/
  runtime-proof/
    proof.json
    summary.md
    screenshot.png

Check A Local App

Start a local app, wait for it to respond, assert page text, and keep screenshots/logs:

npx runtime-proof check \
  --name basic-smoke \
  --command "npm run dev" \
  --url http://127.0.0.1:3000 \
  --expect-text "Dashboard" \
  --fail-on-console-error

For this repository's bundled example:

npm install
npm run proof:example

Use A Config File

Keep repeatable checks in JSON:

npx runtime-proof check --config runtime-proof.config.json

{
  "name": "basic-smoke",
  "command": "node examples/basic/server.mjs",
  "url": "http://127.0.0.1:4173",
  "expectText": ["Runtime Proof Kit", "expected text"],
  "failOnConsoleError": true,
  "outDir": "proof",
  "timeoutMs": 30000,
  "viewport": {
    "width": 1440,
    "height": 900
  }
}

CLI flags override config values.

CLI Reference

runtime-proof check --url <url> [options]
runtime-proof check --config runtime-proof.config.json

Options:
  --config <path>       JSON config file
  --command <cmd>       Command to start before checking the URL
  --expect-text <text>  Text that must appear on the page; repeatable
  --fail-on-console-error
                        Fail if the page logs a console error
  --name <name>         Proof run name, default: runtime-proof
  --out <dir>           Artifact directory, default: proof
  --timeout-ms <ms>     Startup/check timeout, default: 30000
  --viewport <WxH>      Browser viewport, default: 1440x900

Proof Report

proof.json is designed for machines. summary.md is designed for PR comments, CI artifacts, and agent handoffs.

Example summary.md:

# Runtime Proof: basic-smoke

Status: PASSED
URL: http://127.0.0.1:4173
Duration: 1.42s

## Checks

- PASS url-reachable: http://127.0.0.1:4173 responded before timeout
- PASS screenshot: Captured screenshot.png
- PASS expect-text:Runtime Proof Kit: Found expected text: Runtime Proof Kit

{
  "name": "basic-smoke",
  "status": "passed",
  "url": "http://127.0.0.1:4173",
  "checks": [
    {
      "name": "url-reachable",
      "status": "passed",
      "message": "http://127.0.0.1:4173 responded before timeout"
    },
    {
      "name": "screenshot",
      "status": "passed",
      "message": "Captured screenshot.png"
    }
  ],
  "artifacts": {
    "proof": "proof.json",
    "summary": "summary.md",
    "screenshot": "screenshot.png",
    "stdout": "stdout.log",
    "stderr": "stderr.log"
  }
}

GitHub Actions

Use runtime-proof as a small runtime gate in CI:

- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npm run check
- run: npx runtime-proof check --config runtime-proof.config.json

This repository's CI also uploads the generated proof/ directory as a workflow artifact.

Why This Exists

AI coding agents can produce a lot of code quickly, but teams still need simple evidence that the app:

• starts cleanly
• serves the intended page
• renders in a browser
• contains expected user-facing state
• leaves behind artifacts someone else can inspect

This project is intentionally narrower than a full end-to-end test framework. It is a receipt generator for runtime sanity.

Development

npm install
npm run check
npm run proof:example

Regenerate the README screenshot and GIF:

npm run assets:readme

Proof bundles can include screenshots and logs. Review them before sharing publicly.

Roadmap

• Multiple URL checks per run
• Mobile and desktop screenshot sets
• Console and network event logs
• Markdown summary output
• Video capture for short walkthroughs
• Redaction rules for logs and screenshots

License

MIT