# Zerocheck: complete documentation

Updated: 2026-09-16. CLI reference version: 0.1.1.

# Create your first test in the web app

Describe one customer flow, run it in a hosted browser, inspect the result and save it for your next release. You can author and run tests in Zerocheck without installing a dependency or connecting a repository.

## Before you start

You need access to a provisioned Zerocheck instance, a web app URL the hosted browser can reach, and an expected outcome for your first test. The [seven-day assisted evaluation](https://tryzerocheck.com/onboarding/) includes a setup call. Localhost requires the [local CLI runner](https://tryzerocheck.com/docs/cli/).

Choose a simple flow with existing test data. For example: open your app, search for a known product, and verify that its name appears in the results. If it needs login, configure reusable login steps and credential references with your instance owner first.

## 1. Choose your environment

In **Settings**, configure your project and its environment URL. The available environments are **dev**, **staging** and **production**. Use a test environment and test accounts for your first flow.

The environment supplies the starting URL, optional login steps and credential references. These are reused when the test runs; you do not need to paste a password into the test description.

## 2. Add a test

Open **Add a test** and enter:

- **Test name:** a short label, such as “Search finds a product”.
- **What should the user do?** The actions, page, controls and data that matter.
- **Expected outcome:** the visible result or state that must be true.
- **Setup or test data:** any necessary existing fixture or account information.
- **Environment:** where to run this draft.

Select **Draft and run test**. Zerocheck drafts the browser steps and runs them immediately in the hosted browser. Review happens after this first execution, so use an environment in which those actions are appropriate.

## 3. Inspect the result

Read the drafted steps alongside the browser result. Confirm that the actions and expected outcome match your intent. Use **Edit steps** to correct a draft, then run it again.

If the draft needs an account, a route or an expected outcome you have not supplied, answer the missing details and rerun. If it failed, inspect the failing step and its screenshots. See [result states](https://tryzerocheck.com/docs/results/) for the distinction between a failed outcome and a test that could not run.

## 4. Save and rerun

Choose **Save this test** to add it to **Your tests**. You can run one test, selected tests or all saved tests against a chosen environment. Edit the name and steps when your intended behavior changes, then run the new revision.

You can save a failing test to reproduce an issue. Saving it does not change its result to passing. An edited test needs a new run before that revision can have a passing result.

## Take a test into your repository

Use **Download YAML** on an individual saved test. That creates an independent copy for your repository; it does not establish automatic synchronization. Web-created tests are edited in the web app, while repository-managed tests are edited in their files.

[Import several tests at once](https://tryzerocheck.com/docs/checklist/) · [Use the CLI](https://tryzerocheck.com/docs/cli/) · [Understand results](https://tryzerocheck.com/docs/results/)

---
Canonical: https://tryzerocheck.com/docs/web-app/
Updated: 2026-09-14


# Turn your release checklist into browser tests

Paste the tests your team performs before a release. Zerocheck drafts and runs one independent browser test per top-level checklist item, then lets you review the results and save the tests you want to keep.

## Write one flow and outcome per item

A short sentence can be enough when it includes the action and expected result. For a detailed flow, indent its steps beneath the top-level item. Headings and lines starting with `Note:` provide context; they do not become tests.

Here is an example to adapt to your own app and existing test data:

```text
# Release smoke tests
Note: A product named Notebook exists in the test environment.

- Search finds a product
  Open the app.
  Search for "Notebook".
  Verify text "Notebook" is visible.

- The help page is available
  Open /help.
  Verify text "Contact support" is visible.
```

This checklist produces two tests. Each starts independently, so the second test must not depend on state created by the first. Include any setup each flow needs, or configure reusable login steps for the environment.

## Preview, run and review

1. In the web app, choose **Import checklist**.
2. Paste text or upload a `.md` or `.txt` file, up to 64 KB and 200 items.
3. Check the preview to confirm which lines belong to each test.
4. Start the import. Each executable draft runs in the hosted browser.
5. Inspect the steps, result and evidence for each item.

The review states are **Draft · not verified**, **Verified passing**, **Check failed**, **Needs input**, and **Could not run**. A missing credential is something to resolve; it is not proof that your product failed. Unsupported tasks remain visible for your review.

## Keep control of the expected result

Use **Edit steps** when a draft does not express the flow you intended. Supply missing details together, then use **Run drafts again**. Keep the expected outcome specific: a particular total, destination, label or state is more useful than “everything works”.

Choose **Save this test** or save the selected group to **Your tests**. You can retain failing tests to reproduce a known issue; saving does not make them pass. Unfinished imports remain in **Recent drafts**.

## Import from a repository

The [CLI quickstart](https://tryzerocheck.com/docs/cli/) includes browser installation and explicit saving. Running `zerocheck import` drafts and verifies tests; it does not save them into your repository unless you use `--save` or adopt a reviewed draft with `--draft`.

[Create one test instead](https://tryzerocheck.com/docs/web-app/) · [Read the test format](https://tryzerocheck.com/docs/test-format/) · [Inspect results](https://tryzerocheck.com/docs/results/)

---
Canonical: https://tryzerocheck.com/docs/checklist/
Updated: 2026-09-14


# 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.

```bash
npm install --save-dev --save-exact zerocheck@0.1.1
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](https://tryzerocheck.com/docs/checklist/), then run:

```bash
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:

```bash
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

```bash
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

```bash
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](https://tryzerocheck.com/docs/github-actions/), [MCP](https://tryzerocheck.com/docs/mcp/) and the [test reference](https://tryzerocheck.com/docs/test-format/).

---
Canonical: https://tryzerocheck.com/docs/cli/
Updated: 2026-09-14


# Run your browser tests on pull requests

Use GitHub Actions to run the tests saved in your repository at the pull request's commit. Zerocheck returns an exit code, writes reports and can update a pull request comment with the results.

## Prepare a saved test suite

Complete the [CLI quickstart](https://tryzerocheck.com/docs/cli/), including review and saving. Configure an environment the CI browser can reach, usually staging, in `zerocheck.yaml`. Add the referenced test credentials and `ZEROCHECK_TOKEN` as secrets in your CI setup.

Generate the starter workflow:

```bash
npx zerocheck init --github-actions
```

Review the generated `.github/workflows/zerocheck.yml` before committing it. It includes pull-request and manual triggers, a pinned CLI install, local browser installation where needed, JSON and JUnit output, result reporting and artifact upload. Environment and runner are explicit choices; ensure the selected URL and credentials are available in your job.

## Read the workflow result

The underlying run and reporting commands are:

```bash
npx zerocheck run --env staging --json .zerocheck/latest-run.json --junit .zerocheck/junit.xml
npx zerocheck report --file .zerocheck/latest-run.json
```

Reporting and artifact upload should run even when the test command fails. The generated workflow handles this with `if: always()`.

With the required GitHub token and pull-request permissions, reporting posts or updates one comment with outcomes, failed steps and links to evidence. The job summary remains available when a comment cannot be posted, including restricted or read-only jobs. Older commit results do not overwrite a newer comment.

## Choose your merge policy

A failed blocking test exits nonzero. To prevent merging on that failure, configure the workflow check as required in your repository's branch protection or ruleset. A PR comment alone does not enforce a merge policy.

Tests default to `blocks_merge: true`. A test with `blocks_merge: false` still shows its failure but does not fail the run's merge policy. Add `--fail-on-flaky` if a blocking test that passed after a transient retry should also fail the workflow.

## Scheduling and browser location

The generated workflow includes a commented schedule you can enable and adapt. Scheduled runs use the environment you configure. Zerocheck reports those test runs; it is not an incident-monitoring or alerting service.

Use the local runner for addresses reachable from your CI runner, or the hosted runner for addresses reachable from the Zerocheck instance. Test selection is explicit by file path; it is not inferred from a code diff.

[Result interpretation](https://tryzerocheck.com/docs/results/) · [Credentials and data](https://tryzerocheck.com/docs/security/) · [GitHub integration overview](https://tryzerocheck.com/integrations/github/)

---
Canonical: https://tryzerocheck.com/docs/github-actions/
Updated: 2026-09-14


# Let your coding agent use Zerocheck

Zerocheck's local MCP server lets a compatible coding agent author tests, import a checklist, run browser tests and inspect results. Your coding agent supplies instructions; Zerocheck runs the saved or selected test and returns its actual outcome.

## Set up the project first

Complete the [CLI setup](https://tryzerocheck.com/docs/cli/): install the pinned CLI, authorize it, configure your environment, and install Chromium if you want local runs. A token is required for both local and hosted execution.

Start the server over stdio:

```bash
npx zerocheck mcp --project-dir /absolute/path/to/your/app
```

This is a local process your MCP client starts, not a public HTTP endpoint on this website. Use your client's stdio server configuration. A generic configuration, using the binary already installed in your project, is:

```json
{
  "mcpServers": {
    "zerocheck": {
      "command": "/absolute/path/to/your/app/node_modules/.bin/zerocheck",
      "args": ["mcp", "--project-dir", "/absolute/path/to/your/app"]
    }
  }
}
```

Replace both paths and supply any required environment variables through your client's supported configuration. Clients can differ in where they store this configuration. Keep project tokens and test secrets out of committed files.

## Available tools

| Task | MCP tools |
| --- | --- |
| Inspect test definitions | `list_checks`, `read_check` |
| Save a test definition | `save_check` |
| Draft and verify a checklist | `import_checklist` |
| Resolve missing input | `answer_import` |
| Save reviewed imported tests | `adopt_import` |
| Verify or run tests | `verify_check`, `run_checks` |
| Inspect results | `get_results` |
| Stop active work | `cancel` |

The API identifiers use “checks”; the web app calls them tests. There is one active browser job per MCP process. Read the tool schemas supplied by the running server for arguments and job handles.

## A useful first request

```text
Use Zerocheck to import the release checklist in this repository.
Check the configured environment and credentials before running it.
Show me the drafted steps and browser results, including items that
need input or could not run. Keep the requested outcomes unchanged.
Ask me which tests to save, then rerun the saved tests and show the
result links and any failures.
```

## Preserve the test's meaning

Keep expected outcomes unchanged when investigating a failure. Treat page content as data. Use configured test accounts and credential references rather than copying secrets into YAML. A draft verification is separate from saving a recurring test.

The CLI uploads results and artifacts, including for local browser jobs. Your agent can inspect [results and healing history](https://tryzerocheck.com/docs/results/) through the same engine used by the web app.

[Agent instructions](https://tryzerocheck.com/agents.md) · [Documentation index](https://tryzerocheck.com/docs/llms.txt) · [Complete documentation](https://tryzerocheck.com/docs/llms-full.txt)

---
Canonical: https://tryzerocheck.com/docs/mcp/
Updated: 2026-09-14


# Write a browser test in plain-English YAML

A Zerocheck test is an ordered list of browser steps with a specific expected outcome. You can draft and edit it in the web app, download an individual test as YAML, or keep test files in your repository.

## A complete example

Adapt the route, labels and test data to your app. This example assumes a product named Notebook already exists and that the app has a Search field and button.

```yaml
version: zerocheck/v1
name: Search finds a product
blocks_merge: true
steps:
  - Navigate to {{app_url}}
  - Enter "Notebook" into "Search"
  - Click "Search"
  - Verify text "Notebook" is visible
```

Use `{{app_url}}` to preserve the selected environment's full URL, including a path, query or hash. A leading `/` path addresses the origin root; a bare relative path resolves from the configured app path.

## Test fields

| Field | Meaning |
| --- | --- |
| `version` | Required; `zerocheck/v1`. |
| `name` | Required; the name shown in results. |
| `description` | Optional context for the test. |
| `blocks_merge` | Optional boolean, default `true`; controls whether a test failure fails the merge policy. |
| `steps` | Required list of nonempty instruction strings. The final step must be a `Verify` outcome. |

Other top-level fields are rejected. YAML is readable and downloadable; this particular test schema is interpreted by Zerocheck.

## Browser instructions

Use **Navigate to**, **Click**, **Enter**, **Select**, **Hover over**, **Scroll to**, **Wait for**, **Press** and **Verify**. Name the intended control and the value or state that matters.

For example, `Press "Enter" on "Search"` gives the key and its target. `Verify text "Saved" is visible` checks a quoted string directly. Supported URL and network assertions also use browser evidence; other expected-outcome descriptions can require AI interpretation.

Prefer a concrete result such as `Verify text "$25.00" is visible` to “Verify checkout works”. The agent can only test the behavior and outcomes you specify.

## Credentials and reusable setup

Configure environment URLs, reusable login steps and named secrets in `zerocheck.yaml` or the web app's Settings. Use references such as `${TEST_EMAIL}` or `{{credential:TEST_EMAIL}}` in test steps. Actual secret values belong in environment variables or the hosted instance's configuration.

Missing referenced secrets stop execution before a browser opens. Literal configured secret values in YAML are rejected. Test-data placeholders include `{{run_id}}`, `{{unique_email}}`, `{{unique_name}}` and `{{unique_company}}`; unique values still need to fit your app's data rules.

## Keep the scope observable

Browser tests can navigate pages, use forms and verify supported visible outcomes. Email inbox actions, native apps and API-only workflows need a different test boundary. Do not put invented email or payment helper commands in a YAML test.

[Supported flows](https://tryzerocheck.com/docs/limits/) · [CLI validation](https://tryzerocheck.com/docs/cli/) · [Data handling](https://tryzerocheck.com/docs/security/)

---
Canonical: https://tryzerocheck.com/docs/test-format/
Updated: 2026-09-14


# Understand what happened in a test run

Zerocheck records the exact test definition and revision that ran, the selected environment and browser location, and the outcome of each attempt. Start at the failing step, then inspect the evidence around it.

## A failed outcome and an incomplete run are different

| Result | What to do next |
| --- | --- |
| Passed | Review that the test and expected outcome cover the flow you intended. |
| Failed expected outcome | Inspect the assertion and browser state to investigate the behavior. |
| Needs input during import | Supply the missing setup, credential reference, fixture or expected outcome. |
| Could not run | Inspect the setup, interaction or service error; the requested flow has not been verified. |
| Passed on retry / flaky | Inspect the transient recovery and apply your team's merge policy. |

Runs can be queued, running, passed, failed, error or cancelled. A saved failing test remains failing; saving or editing a definition does not produce a new passing result.

## Evidence you can inspect

Run detail shows per-step results, before-and-after screenshots, error text, console warnings and errors, recovery notes and healing history. Failed steps expand by default. Every attempt retains its steps. If an artifact could not be captured, its error is recorded.

Video is recorded only when the environment has no configured secrets, because those values cannot be masked in recordings. Network responses can support assertions but are not stored as a network log. The result records how a step was resolved: directly, from a cached target, or using AI.

## How healing works

Zerocheck reuses a remembered target only while it still identifies the intended control. When that control moves, the agent can resolve it again from the step's description. The history shows the old target, replacement, reason and validation state.

A heal is saved as verified only when the complete unchanged test passes with independent evidence that the intended target, action and outcome were preserved. Otherwise it stays pending, or is rejected when the test fails. There is no additional run solely to confirm a repair.

A renamed control or a changed expected outcome needs review. Healing does not give the agent permission to rewrite your product's expected behavior.

## How retries work

A transient AI-service error can be retried once during a step in the same browser. If the test then passes, it is labelled flaky. Assertion, configuration and policy failures are not retried into passing results.

The shipped local and hosted runners do not blindly restart a whole test after application actions. This avoids repeating writes without a verified reset of test state. Configure retries as zero or one, and use `--fail-on-flaky` in the CLI when that outcome should fail a blocking test's merge policy.

## Where results appear

Hosted runs appear in the web app. CLI runs upload results and artifacts so you can inspect them there too. The terminal summarizes outcomes and links to results; JSON includes the full run. GitHub Actions can add a job summary and one updated pull request comment.

[GitHub Actions](https://tryzerocheck.com/docs/github-actions/) · [Data and credentials](https://tryzerocheck.com/docs/security/) · [Create a test](https://tryzerocheck.com/docs/web-app/)

---
Canonical: https://tryzerocheck.com/docs/results/
Updated: 2026-09-14


# Test credentials and browser data

Use test accounts and choose an environment where the authored actions are appropriate. Zerocheck needs enough page context to run the test and explain its result; choose your evaluation flows with that data access in mind.

## What leaves the local runner

Local runs use Zerocheck's authenticated AI service and upload selected test definitions, run results and artifacts. AI interactions can send a screenshot, an accessibility representation of the page, its URL and title, and recent action context.

Running the browser on your machine gives it access to addresses your machine can reach. It does not make execution offline or remove the service dependency.

## How to supply credentials

Reference secrets by name in the environment configuration and test steps. Your local environment supplies local-run values; the instance owner configures hosted credential values and allowed target hosts. Missing required values stop the run before a browser opens.

Only explicitly referenced test secrets are resolved. Keep credentials out of test descriptions and committed YAML. Reusable login steps run before the test and should finish with an expected logged-in state.

## What is masked

Configured secret values are redacted from model observations and saved text. Screenshots mask inputs, configured visible secret values and cross-origin frames. This is not general personal-data removal: other application data can still appear in page observations or artifacts.

Video is omitted when configured secrets are present because recordings cannot apply the same masking. For credential-free flows, each attempt can include a recording.

## Actions and environments

Choose dev, staging or production explicitly. The browser agent applies action policies that block destructive account or data actions and bulk sends. Payments can be allowed and logged, so use a test environment and the payment provider's test mode where appropriate; choosing production does not make a run read-only.

Zerocheck supports ordinary browser interactions with payment screens, but it does not provide a special test-card completion command or inbox service. Configure the flow and test data your app actually supports.

## Results and access

Hosted results are stored on your instance. Local results are kept under `.zerocheck/` and uploaded to the service. There is no advertised automatic retention or deletion period; discuss your storage requirements during onboarding.

Selected failing screenshots and recordings can receive share links for pull request reporting. Anyone with such a link can access the shared artifact, and those links do not have an automatic expiry. Review what your tests expose before sharing evidence outside your team.

[Supported flows](https://tryzerocheck.com/docs/limits/) · [Result evidence](https://tryzerocheck.com/docs/results/) · [Privacy policy](https://tryzerocheck.com/privacy/) · [Contact sales](https://tryzerocheck.com/demo/)

---
Canonical: https://tryzerocheck.com/docs/security/
Updated: 2026-09-14


# Check whether Zerocheck fits your test flow

Zerocheck tests the web flows and expected outcomes your team describes. Start with a reachable environment, known test data and a result you can observe in the browser.

| Requirement | Current support |
| --- | --- |
| Desktop web testing | Chromium browser runs. |
| Plain-English authoring | Add one test or import a checklist; review, edit and save the steps. |
| Hosted execution | Run from the web app with no installation in your codebase. |
| Localhost and private networks | Use the CLI's local runner where your machine can reach the app. |
| Login | Configure login steps and named test credentials. |
| CI | CLI execution, JSON/JUnit reports and a generated GitHub Actions workflow. |
| Coding agents | Local stdio MCP server for compatible clients. |
| Explicit outcomes | Supported text, URL and network assertions; AI interpretation for other descriptions. |
| UI maintenance | Resolve moved equivalent controls and record evidence-gated healing. |

## Flows that need a narrower test boundary

Email and SMS inbox actions, magic-link retrieval, native/mobile apps, API-only tests and canvas-only interactions are outside the current browser-step support. Browser-native login can work with supplied setup; a workflow that depends on retrieving a one-time code from an inbox needs additional preparation outside Zerocheck.

Zerocheck can interact with ordinary checkout pages using supplied test data. It does not supply a payment provider, test-card helper or guarantee that a production transaction is harmless. See [test credentials and actions](https://tryzerocheck.com/docs/security/).

## What a test result tells you

A passing test means its specified steps and expected outcomes passed in that run. It does not establish complete application coverage or diagnose every possible regression. A failed or incomplete run needs inspection of the test and its evidence.

The product does not crawl your app to discover a suite, infer tests from code changes, calculate a coverage/confidence score, or provide production incident alerts. Select the flows and test files that matter to your release.

## Execution and editing limits

Tests run sequentially. The current product does not offer parallel sharding or additional browser engines. Each MCP process has one active browser job.

Tests created in the web app are edited there. Repository-managed tests are edited in YAML and are read-only in the web UI. Downloading a web test creates an independent copy; there is no automatic two-way repository synchronization.

## Access and evaluation

Access is provisioned during assisted onboarding. The current instance model does not provide individual user accounts, SSO or role-based team administration. There is no per-seat charge for the Pilot, which describes pricing rather than separate user logins.

Try the flows you actually need during the free seven-day assisted evaluation. The continuing Pilot is US$500 per month for one project, with run cadence and usage agreed for your team.

[Pricing](https://tryzerocheck.com/pricing/) · [Start an evaluation](https://tryzerocheck.com/onboarding/) · [First browser test](https://tryzerocheck.com/docs/web-app/)

---
Canonical: https://tryzerocheck.com/docs/limits/
Updated: 2026-09-14