---
title: Writing Tests
description: Principles for writing tests the AI agent can understand and execute reliably.
---

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

```markdown
## 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:

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

Shared Steps cannot contain other Shared Step chips yet.

---

<Cards>
  <Card title="Good tests" href="/writing-tests/good-tests">
    Worked examples across login, forms, navigation, and content verification.
  </Card>
  <Card title="Common mistakes" href="/writing-tests/bad-tests">
    Anti-patterns that produce flaky or inconclusive results — and how to fix them.
  </Card>
  <Card title="Test examples" href="/writing-tests/examples">
    A library of copy-paste starters organized by use case.
  </Card>
</Cards>