Writing Tests

A good test is specific, sequential, and verifiable. The AI agent is capable, but clear instructions produce more consistent results than vague ones. You can use markdown headings, lists, and checkboxes to make longer tests easier to scan.

Three principles

1. One test per test

Each test should test one user journey end to end. Don't combine login, onboarding, and checkout into a single test. Split them. This makes failures easier to diagnose and tests easier to maintain.

2. Describe actions in sequence

The agent reads your description top to bottom. Structure it as a sequence of actions:

"User navigates to the pricing page → clicks Start free trial on the Pro plan → fills in their email → clicks Continue."

This is clearer than:

"User signs up for a Pro trial."

Markdown lists work well for multi-step tests:

## Signup

- Open the signup page
- Enter a test email
- Submit the form
- Verify the onboarding checklist appears

3. State the expected outcome explicitly

The agent needs to know what success looks like. End your description with a concrete, observable condition:

"...and arrives at the onboarding page with the heading Let's get you set up."

Without an explicit outcome, the agent has to guess — and results become less reliable.

Reuse Shared Steps

Use Shared Steps for repeated steps such as login, onboarding setup, or opening a shared dashboard state. Create a named Shared Step in the Shared Steps view, then type / at the start of an empty line in the Test editor and choose it from the menu.

Inserted Shared Steps appear as block chips in the editor. At Run time, Smoketest expands each chip into the latest saved Shared Step description. Runs are blocked if a chip points to a missing Shared Step or a Shared Step from another project.

Stored markdown represents Shared Step chips as stable tokens:

[Log in](smoketest-shared-step:018effff-abcd-7000-8000-abc123456789)

Shared Steps cannot contain other Shared Step chips yet.