Writing Good Tests

How Monito reads a test

A test scenario is plain-language instructions. The Monito agent opens a real browser at the scenario's location, finds elements by their visible labels, follows the steps and checks the expected results. It reports pass when every expected result was verified, fail when the product does something else, and error when a result could not be checked (missing login, an unreachable page, an expectation it cannot observe).

The shape that works best:

1. Open the cart.
2. Click 'Checkout'.
3. Fill in the name, email and address, then click 'Place order'.

Expected: the page shows 'Thank you for your order' and an order number.

Numbered steps, one per line, then Expected: with results the agent can see on the page: visible text, a URL, a value, an item appearing or disappearing, or a state that survives a reload.

The rules

Monito's checker applies the rules below as you type, in the test form, when reviewing discovered drafts and in reusable setup. The same rules guide the discovery agent and AI Improve. Findings are hints and never block saving.

• Error: the run will likely end in error or expose private data.
• Warning: the run may be flaky or unverifiable.
• Tip: worth a look.

State the expected result

expected-outcome · error

The agent verifies what the scenario says should happen. Without an expected result it cannot pass the test and reports an error.

• Instead of: Go to settings and change the display name.
• Write: Change the display name to 'Ada' and save. Expected: the header shows 'Ada' after reloading the page.

Make expectations observable

vague-expectation · warning

"Works correctly", "looks good" and "is fast" cannot be checked in a browser. Name the text, URL, value or state the page should show.

• Instead of: Verify checkout works correctly.
• Write: Expected: the page shows 'Thank you for your order' and an order number.

Use a login role, not a password

inline-secret · error

Scenario text is sent to the agent and stored in run history. Keep credentials in an Environment login role; the executor enters them without exposing them to the agent or the transcript.

• Instead of: Sign in with password Hunter2!
• Write: Sign in with the admin login role. (and choose the role under Options → Login)

Prefer a login role for accounts

login-email · warning

An email address in the prompt does not give the agent a password. Choose the login role in the test's options so the executor signs in.

• Instead of: Log in as ada@example.com.
• Write: Log in with the member role.

Describe elements as a user sees them

selector · warning

The agent finds elements by their visible labels. Selectors and test IDs break when markup changes and don't describe the behavior under test.

• Instead of: Click [data-testid=submit-btn].
• Write: Click the 'Create project' button.

One flow per scenario

multiple-flows · warning

Each scenario gets one time budget and one verdict. Several flows in one scenario hide which one failed and often run out of time.

• Instead of: Test sign up. Also test password reset.
• Write two scenarios: Sign up and Password reset.

Make created data unique

namespace-data · warning

Runs share your application's data. When a scenario creates records after reusable setup, include {{namespace}} in their names so parallel and repeated runs don't collide.

• Instead of: Create a project named 'Test project'.
• Write: Create a project named 'Test project {{namespace}}'.

Only {{namespace}} is replaced

unknown-placeholder · error

{{namespace}} is the only placeholder Monito fills in. Anything else in double braces reaches the agent as literal text.

• Instead of: Search for {{product}}.
• Write: Search for 'Blue mug'.

Anchor dates

relative-date · tip

Runs happen at different times. Say which date matters, or accept any valid date, so results don't depend on when the run starts.

• Instead of: Book a table for tomorrow.
• Write: Book a table on any available date in the next 30 days.

Keep scenarios Environment-portable

environment-portable · tip

A scenario runs against any Environment of its project (production, staging, previews). A hard-coded origin pins it to one deployment; use paths such as /settings.

• Instead of: Open https://staging.example.com/settings.
• Write: Open /settings.

Keep scenarios short

too-long · tip

Long scenarios run out of time before verifying the result. Split long journeys, or move shared preparation into reusable setup.

Improve with AI

When AI assist is enabled for your account, the test form has an Improve button (⌘ J / Ctrl J in the instructions field). It rewrites the scenario to follow these rules while keeping your steps, facts and intent, and shows the rewrite as a diff: keep or untick each change, then apply. Each change names the rule it addresses. Nothing is saved until you save the test.

Improve and the other assists (drafting a test from a one-line idea, suggesting suites, explaining a failed run) run on the same model as your test runs, through the Vercel AI Gateway with zero data retention and prompt training disabled. They see your project's names, paths, login role names and the scenario text, never credentials or evidence files, and their suggestions are checked against these rules before you see them.