Deterministic Proof For Web Applications

Zero-Friction Getting Started

You don't need to install large browser binaries or modify your package dependencies. Run StateProof directly using npx against any running local dev server:

# 1. Initialize StateProof configuration for your app
npx @stateproof-dev/cli init --url http://localhost:5173

# 2. Run deterministic validation against all scenarios in parallel
npx @stateproof-dev/cli run --workers 4

# 3. Export Markdown PR proof card with timestamped artifacts
npx @stateproof-dev/cli export --format md

Wire-Level Interception: Pure CDP

Traditional testing tools rely on Mock Service Worker (MSW), proxy daemons, or monkey-patching window.fetch. These approaches distort the application environment, fail on WebSockets, and require editing source files.

StateProof takes a fundamentally different path:

Framework & Tool Compatibility Matrix

Because StateProof operates strictly from the outside at the browser wire, it is completely framework-agnostic. If it renders in Chromium, StateProof can prove it.

The 4 Canonical Edge States

AI agents routinely generate the "happy path" — but real users face network latency, zero-item states, server exceptions, and dropped connections. StateProof forces and captures all four:

Scenario Specification Guide (stateproof.scenarios.json)

Scenarios are declared in a declarative, machine-readable JSON file at the root of your project:

{
  "$schema": "https://unpkg.com/@stateproof-dev/core@0.2.2/schema/v1.json",
  "name": "dashboard-app",
  "baseUrl": "http://localhost:5173",
  "route": "/dashboard",
  "viewports": [
    { "name": "desktop", "width": 1440, "height": 1024 },
    { "name": "mobile", "width": 390, "height": 844, "isMobile": true }
  ],
  "scenarios": [
    {
      "id": "loading-state",
      "label": "Dashboard loading skeleton renders during latency",
      "request": { "method": "GET", "urlPattern": "**/api/analytics" },
      "response": { "mode": "delay", "milliseconds": 1500 },
      "expect": {
        "visible": ["[data-testid=\"skeleton-chart\"]", "[aria-busy=\"true\"]"]
      }
    },
    {
      "id": "empty-state",
      "label": "Empty project banner and onboarding CTA",
      "request": { "method": "GET", "urlPattern": "**/api/projects" },
      "response": { "mode": "inline", "status": 200, "body": { "projects": [] } },
      "expect": {
        "visible": ["[data-state=\"empty\"]", "button#create-project"],
        "text": { "h2": "No projects found" }
      }
    },
    {
      "id": "error-recovery",
      "label": "500 failure triggers error card and retry recovery cycle",
      "request": { "method": "GET", "urlPattern": "**/api/billing" },
      "response": { "mode": "error", "status": 500 },
      "expect": {
        "visible": ["[data-state=\"error\"]", "button#retry-billing"]
      },
      "recovery": {
        "action": { "type": "click", "selector": "button#retry-billing" },
        "response": { "mode": "fixture", "path": "fixtures/billing-active.json" },
        "expect": { "visible": ["[data-state=\"ready\"]"] }
      }
    },
    {
      "id": "offline-banner",
      "label": "Offline banner appears on network disconnect",
      "request": { "method": "GET", "urlPattern": "**/api/feed" },
      "response": { "mode": "offline" },
      "expect": {
        "visible": [".offline-notice"]
      }
    }
  ]
}

Recovery Loops & WebSocket Interception

Testing error states is only half the proof — you must verify that the user can recover without refreshing the page.

StateProof's recovery block orchestrates this full lifecycle:

1. Injects the failing response (e.g. 500 Internal Server Error).
2. Asserts error banner visibility and captures failure screenshot.
3. Emulates user click on the retry CTA selector.
4. Dynamically switches CDP response interception to healthy fixture (200 OK).
5. Asserts recovery state and captures resolved screenshot.

Empirical Performance & Benchmarks

StateProof is measured on real workloads (tested on Node v22, Chromium 151, Linux, 4 vCPU / 7.5 GB RAM against a full 4-state × 2-viewport suite):

AI Agent Token Economics: 3–5x Token Savings

When an AI coding assistant diagnoses failing UI states through the first-party StateProof MCP server, it avoids reading massive DOM trees or executing multi-step browser loops:

StateProof vs Traditional Testing Matrix

CLI Command Reference

MCP Server for AI Coding Agents

StateProof provides a standard Model Context Protocol (MCP) server so coding agents like Claude Code, Cursor, Windsurf, Cline, and Antigravity can run runtime proofs, inspect DOM diagnostics, and self-heal missing selectors autonomously.

{
  "mcpServers": {
    "stateproof": {
      "command": "npx",
      "args": ["-y", "@stateproof-dev/mcp-server@0.2.3"]
    }
  }
}

Continuous Integration (GitHub Actions)

Add deterministic runtime proof gates to your PR pipeline. If an AI agent or engineer breaks the offline fallback or error recovery, the build fails before reaching production:

name: StateProof Gate
on: [pull_request]

jobs:
  prove-states:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - name: Start Preview Server
        run: npx serve -s dist -l 5173 &
      - name: Run StateProof Validation
        run: npx @stateproof-dev/cli run --headless --workers 4
      - name: Export PR Proof Card
        if: always()
        run: npx @stateproof-dev/cli export --format md >> $GITHUB_STEP_SUMMARY

Security Model & Operational Boundaries

When StateProof Operates Best

• Client-Side Network Requests: StateProof intercepts client fetch, XHR, WebSocket, and SSE calls in Chromium.
• SSR Initial Data: If data is baked statically into HTML at build time without client fetch, test the client mutations, re-validations, or page transitions instead.
• Zero Telemetry: No accounts, no API keys, zero cloud metrics. Everything executes 100% on your workstation.