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.

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. (and choose the login under Options → Login)

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. (and choose the member login under Options → Login)

login-in-steps · warning

The executor signs in with the login chosen in the test's Options → Login, or with the Environment's default login when none is chosen. Naming another login in the steps doesn't switch accounts, so the run signs in as someone else. The checker offers a button that chooses the named login for you.

Instead of: Sign in with the credentials from the qa-admin login role.
Write: Sign in. (and choose the qa-admin login under Options → Login)

sign-in-without-login · warning

When a test has no login chosen and its Environment has no default login, the run starts signed out and has no credentials to enter. Choose a login under Options → Login, or set a default login on the Environment.

Instead of: Log in and open the billing page. (with no login anywhere)
Write: the same steps, with a login chosen under Options → Login.

Don't check the login's email or password

masked-login-values · warning

Monito masks the login's email and password in every screenshot and in the page text the agent reads, so a check that the page shows them can never pass. Check something else about the account, like the user's name.

Instead of: Expected: the profile menu shows the user's name and their email.
Write: Expected: the profile menu shows the user's name.

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. A flow with 7 or more steps and a budget of 5 minutes or less also gets this hint: “Set Timeout to 10 minutes, or split the journey.”

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 names and the scenario text, never credentials or evidence files, and their suggestions are checked against these rules before you see them. They never write a login's name into the steps or check its email or password; when a rewrite drops a login from the steps, its change note says which login to choose in Options.

On this page