# Writing Specs

WebTest AI specs are Markdown files with optional frontmatter and one or more top-level test headings.

```md
---
suite: checkout
baseUrl: https://shop.example
tags: [checkout]
---

# Guest Checkout

## Goal

Verify a guest can start checkout.

## Steps
1. Open "/cart"
2. Click role "button" named "Checkout"

## Expected
1. Assert text "Contact information"
```

## Useful Step Shapes

- `Open "/path"`
- `Click text "Save"`
- `Click role "button" named "Continue"`
- `Click action "primary checkout"`
- `Click element "Search"`
- `Fill field "Email" with "person@example.com"`
- `Fill field "Email" with env "USER_EMAIL"`
- `Assert text "Dashboard"`
- `Assert url "**/dashboard"`
- `Wait for url "**/complete"`
- `Wait for network "/api/orders"`
- `Wait for network "/api/orders" status 201`
- `Capture screenshot`
- `Capture screenshot as "after-login.png"`
- `Capture visual checkpoint "homepage-hero"`

Prefer visible names and roles over brittle CSS selectors. That keeps specs readable and gives the runner stronger accessibility-tree signals.

The step language is exact. Unsupported wording fails fast with `Unsupported step`; the full supported grammar is listed in [Config and API Reference](../config-and-api-reference.md#step-language-api).