Docs
Writing flow tests
A flow is a list of steps, one per line, in plain English. Each line is matched against the patterns below, so the same steps always do the same thing. Put button text and typed values in double quotes.
How elements are found
Clickwalker looks for things the way a person does. For Click "Checkout" it tries, in order: a button, link, tab or menu item named exactly “Checkout”; then one whose name starts with it, like “Checkout (2)”; then one containing the word; then any visible text. For fields it uses the label, then the placeholder, then the field's name. It waits up to 10 seconds for the element to appear, and searches inside iframes too, so embedded payment fields work.
If you'd rather be exact, any target that starts with #, . or [ is used as a CSS selector: Click "#checkout-button".
Steps
| Step | What it does |
|---|---|
Go to /pricing | Opens a page on the same site. Full addresses work too. Open and Visit mean the same. |
Go back · Reload the page | Browser back button, or reload. |
Click "Add to cart" | Clicks a button, link, tab or text. Tap, Press and Select also work. |
Type "jane@example.com" into "Email" | Fills a field. Also Fill "Email" with "…" and Enter "…" in "…". |
Select "Large" from "Size" | Picks an option, in a normal menu or a custom dropdown. |
Check "I agree to the terms" | Ticks a checkbox, radio button or switch. Uncheck unticks it. |
Press Enter | Presses a key: Enter, Tab, Escape, Space, Backspace, arrow keys, Page Up/Down, Home, End. |
Submit the form | Clicks the form's submit button. |
Hover over "Products" | Moves the mouse over an element, for menus that open on hover. |
Scroll down · Scroll to "Reviews" · Scroll to the bottom | Scrolls the page. |
Wait 2 seconds | Pauses, up to 30 seconds. Rarely needed: every step already waits for the page. |
Checks
A flow passes when every step works. Add checks to make sure the right thing happened, not just that buttons were clickable.
| Step | Passes when |
|---|---|
Expect to see "Order confirmed" | The text is visible within 10 seconds. Also See "…", Wait for "…", The page should contain "…". |
Expect not to see "Error" | The text isn't visible. Also "Out of stock" should not appear. |
Expect the URL to contain "/thank-you" | The address contains the text within 10 seconds. |
Expect the title to contain "Checkout" | The page title contains the text. |
Fresh values each run
Sign-up flows need a new email address each time. Write {{random_email}} to get one like test+3f9a1c2e@example.com, or build your own with {{random}}: Type "you+{{random}}@yourdomain.com" into "Email". {{timestamp}} gives the current Unix time.
A complete example
Go to /signup
Type "Test User" into "Name"
Type "{{random_email}}" into "Email"
Type "Test-password-2026" into "Password"
Check "I agree to the terms"
Click "Create account"
Expect to see "Welcome"
Expect the URL to contain "/onboarding"Reading the results
The report lists every step with how long it took and a screenshot taken right after it. When a step fails, the run stops there and the report shows why, for example Couldn't find a button, link or text “Checkout” on the page. If the page logged a JavaScript error or a request failed during that step or the one before, it's shown as the likely cause.
Lines starting with # are comments. Numbered or bulleted lists (1., -) are fine; the markers are ignored.
Tips
- Use test accounts and test payment cards, like Stripe's
4242 4242 4242 4242, never real ones. - If a cookie banner covers the page, add
Click "Accept"(or your banner's button) as the first step. - End every flow with an
Expect to seestep, so you know the journey actually finished.
Stuck? Email hello@clickwalker.com with the flow you're writing and we'll help.