Zerocheck

Zerocheck turns your team’s manual release checklist into repeatable browser tests.

Paste a checklist, review one drafted check and browser verification result per actionable item, then save readable YAML in your repository. Run those same files locally, in GitHub Actions, or in a hosted browser. Results, recordings, attempts and healing history are available in the web app, with screenshots and a summary in your pull request.

Setup

Requires Node.js 20.19 or newer and a Zerocheck project/account. Create a project in the web app’s Settings, then authorize a device or create a project token.

npm install --save-dev [email protected]
npx zerocheck login
npx zerocheck init --project your-project-id --url http://localhost:3000
npx zerocheck install

install downloads Chromium for local execution. Linux CI can use zerocheck install --with-deps. Hosted execution does not require a browser on your machine, but still uses the CLI and your Zerocheck account.

For unattended use, set ZEROCHECK_TOKEN to the project token. It overrides the device token saved in ~/.zerocheck/config.json. ZEROCHECK_API selects your Zerocheck server and defaults to https://app.tryzerocheck.com. Never commit tokens or resolved test credentials.

Import your release checklist

npx zerocheck import release-checklist.md --env dev
cat release-checklist.md | npx zerocheck import - --env staging
npx zerocheck import --env dev

The last command accepts an interactive paste; finish with Ctrl+D on a new line. Import supports text and Markdown. Each item retains its source line and one of these states:

• Verified passing: the exact draft completed in a browser and its expected outcome passed.
• Check failed: the requested outcome failed. Review the check and captured result; this alone does not diagnose a product bug.
• Needs input: an essential outcome, account, route or fixture is missing, or the item still needs a browser-executable interpretation.
• Could not run: execution could not complete; inspect the recorded reason.

Headings, notes, duplicates and unsupported items remain visible. Import does not silently discard difficult items or weaken a failed expectation.

The command prints the exact YAML for review. Save it with the single adoption command displayed at the end, or use --save when you want the import to save its displayed drafts immediately:

npx zerocheck import --draft IMPORT_ID
npx zerocheck import release-checklist.md --env dev --save

The same --draft command adopts a reviewed import from the web app. Drafted checks are saved in a unique import folder beneath the configured test directory. Their YAML bytes and revision are preserved. Existing conflicting files are never overwritten. Partial imports may be saved, but unresolved/failed items remain in the import report and the command exits nonzero.

Answer missing inputs together in a JSON file keyed by the displayed item IDs:

{"item-3":"Use the existing demo product with SKU DEMO-1; expect a total of $12.00."}

npx zerocheck import --draft IMPORT_ID --answers answers.json

Only the answered unresolved items are drafted/verified again. Already completed items are preserved. Edit a drafted test’s expected behavior as a reviewed YAML change; changed YAML needs a new verification.

One repository format, named environments

zerocheck.yaml configures the project. It is separate from the readable check files:

project: your-project-id
default_environment: dev
test_directory: zerocheck/tests
environments:
  dev:
    url: http://localhost:3000
  staging:
    url: https://staging.example.com
    secrets:
      EMAIL: ${ZEROCHECK_EMAIL}
      PASSWORD: ${ZEROCHECK_PASSWORD}
    login_steps:
      - Navigate to /login
      - Enter "${EMAIL}" into the Email field
      - Enter "${PASSWORD}" into the Password field
      - Click the Sign in button
      - Verify the dashboard is visible
  production:
    url: https://example.com
execution:
  retries: 1

Only explicitly referenced secret variables are read for execution. Missing variables fail clearly. Listing, reading, saving and validating checks do not require execution secrets.

Each check is one zerocheck/v1 YAML file:

version: zerocheck/v1
name: Release notes are available
blocks_merge: true
steps:
  - Navigate to /releases
  - Verify the Release notes heading is visible

Repository files are authoritative. The web app shows synced revisions and exact run snapshots; it does not maintain a second independently edited suite. A run always uses the selected files’ current contents. Empty, missing, duplicate or invalid selections fail before execution; run never invents starter checks.

Run and inspect

npx zerocheck validate
npx zerocheck run --env dev
npx zerocheck run zerocheck/tests/release.yaml --env staging --runner hosted
npx zerocheck run --env production --runner local --fail-on-flaky
npx zerocheck run --env staging --json .zerocheck/latest-run.json --junit .zerocheck/junit.xml
npx zerocheck results RUN_ID
npx zerocheck doctor --env staging

local is the default runner and can reach localhost and private networks available to your machine/CI job. hosted uses Zerocheck’s existing hosted browser and can reach targets available to that worker; it cannot reach your laptop’s localhost, and Zerocheck does not create a network tunnel. Runner location, environment and trigger are independent. Hosted interruptions produce an explicit error and require a new user-triggered run.

Results retain every attempt. A failed attempt followed by a pass, or a transient grounding failure recovered in the same browser, is flaky / passed on retry, even when CI succeeds. Step recovery details remain visible. --fail-on-flaky makes blocking flaky checks fail CI. blocks_merge: false explicitly makes a check non-blocking; setup errors and incomplete execution still fail the command.

Exit codes: 0 completed within the selected merge policy; 1 blocking test failure (or strict flaky result); 2 setup, incomplete execution or infrastructure error. Import exits nonzero while any actionable item remains unverified.

Learned targets persist in .zerocheck/cache. Local CLI and MCP share this cache; hosted execution uses its own persistent cache. A healed target is separate from a retry, and the result records target changes and their validation. Forms and login do not block target repairs. The engine saves only independently validated targets after a complete unchanged check; model-only outcomes leave repairs pending. It never reruns a submission solely to validate healing. Recovery before dispatch stays in the current browser. A full restart after application activity needs a trusted isolated-state integration; retries: 1 does not itself establish safe replay. Include .zerocheck/ in .gitignore; init adds it.

GitHub Actions and PR comments

npx zerocheck init --github-actions

The generated .github/workflows/zerocheck.yml pins the CLI version, restores the local target cache, runs staging checks, and runs the reporter and artifact upload even if checks fail. Set the repository secret ZEROCHECK_TOKEN, configure staging in zerocheck.yaml, and add only the test-secret variables referenced there. For localhost testing, add your app startup and fixture setup before the run step.

The workflow uses pull_request, not pull_request_target. It grants contents: read and pull-requests: write; it does not execute fork code with elevated secrets. Fork or read-only-token jobs keep their job summary and explain why a PR comment could not be posted.

The comment contains pass/fail/flaky results, failing steps, selected screenshots, recordings, environment, commit and a link to full results. One Zerocheck bot comment is updated per PR. Results from older commits cannot replace the current comment. report explicitly creates unguessable share links for the selected PR screenshots/recordings, so GitHub can render them without a Zerocheck login; other artifacts retain normal access controls.

npx zerocheck report --file .zerocheck/latest-run.json

GITHUB_TOKEN, GITHUB_EVENT_PATH and GITHUB_STEP_SUMMARY come from Actions. Outside Actions, supply --repo owner/repository --pr NUMBER and GITHUB_TOKEN. Without PR context the same formatter produces a job summary.

The template also supports a manual choice of runner and environment. Uncomment its schedule to run the same checks against staging on weekdays, or edit that explicit environment for a production schedule. Schedules do not enable a separate monitoring product.

MCP for coding agents

Use the installed CLI as a stdio MCP server, with an explicit project directory:

{
  "mcpServers": {
    "zerocheck": {
      "command": "npx",
      "args": ["--yes", "[email protected]", "mcp", "--project-dir", "/absolute/path/to/project"]
    }
  }
}

Authenticate with zerocheck login first or provide ZEROCHECK_TOKEN through the MCP host’s environment/secret settings. stdout contains only MCP protocol messages; diagnostics use stderr.

Tools: list_checks, read_check, save_check, import_checklist, answer_import, adopt_import, verify_check, run_checks, get_results, and cancel. Existing check replacements require their current expectedRevision. File operations stay within the configured project, including symbolic-link checks.

Browser operations return job handles. Poll get_results with kind: "job" and waitMs up to 30000; inspect the returned run/draft ID for durable retrieval. kind: "run" reads a saved run after process restart; kind: "import" reads an uploaded import. Cancel with the job ID. Each MCP process permits one active browser job. Closing it cancels that job; cancellation cannot undo actions already performed.

Data sent to Zerocheck

Local execution sends selected check YAML, the page context needed for AI (including screenshots/accessibility content), and run results/artifacts to Zerocheck. The browser still runs on your machine. Hosted execution additionally sends the URL, login steps and explicitly configured test secrets needed to run the check. The CLI never uploads your entire process environment. Browser screenshots may contain visible application data, and report shares the selected PR assets as described above.

Repository development

The CLI bundles the shared engine source into dist/index.js; it has no unpublished engine-package dependency. From this repository, run npm run build, npm run check, and npm test in packages/cli. Tests include a real MCP client communicating with the bundled CLI over stdio. The generated workflow and documentation use version 0.1.6; update that pin together with the package version for a release.

Hosted runs and imports return a queued handle when browsers are occupied; CLI and MCP keep polling until they finish. The queue holds 20 waiting jobs for up to five minutes and never automatically resumes interrupted jobs after restart. Recent imports is available in the web app’s Checks page.