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
    console.ndjson
    network.ndjson

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.

Run Multiple Checks

Use checks when one proof should cover more than one route, viewport, or page assertion. Top-level values act as defaults; each check can override url, expectText, viewport, timeoutMs, or failOnConsoleError.

{
  "name": "multi-smoke",
  "command": "npm run dev",
  "url": "http://127.0.0.1:3000",
  "failOnConsoleError": true,
  "checks": [
    {
      "name": "desktop-home",
      "expectText": ["Dashboard"],
      "viewport": { "width": 1440, "height": 900 }
    },
    {
      "name": "mobile-home",
      "expectText": ["Dashboard"],
      "viewport": { "width": 390, "height": 844 }
    },
    {
      "name": "health",
      "url": "http://127.0.0.1:3000/health",
      "expectText": ["ok"]
    }
  ]
}

Run it the same way:

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

That writes an aggregate suite report plus one proof bundle per check:

proof/
  multi-smoke/
    proof.json
    summary.md
    desktop-home/
      proof.json
      summary.md
      screenshot.png
      console.ndjson
      network.ndjson
    mobile-home/
      proof.json
      summary.md
      screenshot.png
      console.ndjson
      network.ndjson

Initialize A Project

Generate a starter config and GitHub Actions workflow:

npx --yes runtime-proof-kit init --template next

Templates:

Then edit runtime-proof.config.json and replace the placeholder expected text with something visible on your page.

Useful options:

npx --yes runtime-proof-kit init --template vite --expect-text "Dashboard" --force
npx --yes runtime-proof-kit init --no-ci

CLI Reference

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

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

Config:
  checks               Optional array of named checks for one multi-page proof run

Init Options:
  --template <name>     generic, next, or vite; default: generic
  --config <path>       Config file to write, default: runtime-proof.config.json
  --workflow <path>     CI workflow to write, default: .github/workflows/runtime-proof.yml
  --url <url>           Override the generated URL
  --command <cmd>       Override the generated dev command
  --expect-text <text>  Override generated expected text; repeatable
  --no-ci               Only write the config file
  --force               Overwrite generated files

Proof Report

proof.json is designed for machines. summary.md is designed for PR comments, CI artifacts, and agent handoffs. console.ndjson and network.ndjson are newline-delimited JSON streams for debugging browser console output, page errors, requests, responses, and failed requests.

Example network.ndjson lines:

{"timestamp":"2026-06-09T04:02:43.069Z","event":"request","method":"GET","url":"http://127.0.0.1:4173/","resourceType":"document"}
{"timestamp":"2026-06-09T04:02:43.081Z","event":"response","method":"GET","url":"http://127.0.0.1:4173/","resourceType":"document","status":200,"statusText":"OK"}

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",
    "console": "console.ndjson",
    "network": "network.ndjson",
    "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 --yes runtime-proof-kit 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

• Video capture for short walkthroughs
• Redaction rules for logs and screenshots

License

MIT