# 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