Run browser tests locally with the CLI

The optional Zerocheck CLI runs repository tests on your machine, in CI or in a hosted browser. The web app remains available for authoring and hosted runs with no local installation.

Prerequisites

• Node.js 20.19 or newer.
• Access to a provisioned Zerocheck instance and project.
• A running target app and any required test accounts or fixtures.

Local browser execution still uses Zerocheck's AI service and uploads results and artifacts. It needs network access and authentication. The local browser can reach localhost and private networks available to your machine; the hosted browser needs a URL reachable from the instance.

Install and authorize

Run these commands from your app's repository. The examples use CLI version 0.1.1.

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

Replace the URL with your app's address. login authorizes the machine. init writes zerocheck.yaml and creates an empty test directory; it does not create or execute a test. install downloads Chromium for local runs.

For a dedicated instance using a different service address, set ZEROCHECK_API to the URL supplied during onboarding before logging in. In CI, use a project API token in ZEROCHECK_TOKEN.

Import, review and save

Create release-checklist.md using the checklist format, then run:

npx zerocheck import release-checklist.md --env dev --runner local

Read the output states and the exact drafted YAML. Open Recent drafts in your Zerocheck instance to inspect the imported tests, screenshots and failed steps. Import prints a draft identifier rather than a results URL. Import exits nonzero while any item is not verified passing; the draft remains available for review.

After reviewing, replace DRAFT_ID with the identifier from your import and save its drafted tests:

npx zerocheck import --draft DRAFT_ID
npx zerocheck validate
npx zerocheck run --env dev --runner local

Adoption saves the available drafted definitions; it does not make failed tests pass. Check the draft before adopting it, and resolve missing inputs or edit the saved YAML as needed. Do not skip saving: run needs tests in the configured test directory.

Choose where the browser runs

npx zerocheck run --env staging --runner hosted

Configure the selected environment's URL and login steps first. Local and hosted describe browser location; dev, staging and production describe which environment to test. There is no automatic tunnel from a hosted browser to localhost.

Save reports and inspect a run

npx zerocheck run --env dev --json .zerocheck/latest-run.json --junit .zerocheck/junit.xml
npx zerocheck results RUN_ID --json

The CLI prints test outcomes, failed steps and a results URL. JSON and the web app contain full attempts and artifact links. --fail-on-flaky can make a blocking test that passed after a transient retry fail your CI policy.

Exit code	Meaning
0	Execution completed within the merge policy.
1	A blocking test failed, or a blocking flaky test failed the --fail-on-flaky policy.
2	Setup, configuration, policy, infrastructure, cancellation or incomplete execution prevented a complete result.

Use npx zerocheck doctor --env dev --runner local to check setup. See GitHub Actions, MCP and the test reference.