Step actions reference

Each English line you write becomes one action in this list. The parser maps natural language to one of these action keys; the executor (Playwright, under the hood) runs them. This page is the complete inventory.

Note

For the natural-language side (“what English do I write?”), see the YAML schema reference. For why locators work the way they do, see Locator resolution.

Action shape

Every step is a single key-value pair. The key is the action; the value is either a string (target text) or an object with a target and other fields:

- click: "Sign in button"

- type:
    target: "email field"
    text: "user@example.com"

- verifyVisible: "Welcome back"

Some actions accept aliases so multiple natural phrasings map to the same behavior — click and tapOn, type and inputText, verifyVisible and assertVisible. Use whichever reads more naturally.

Optional steps

Any action can take optional: true. If the target element isn’t found, the step is marked skipped instead of failed and the run continues:

- click:
    target: "Cookie banner accept"
    optional: true

This is most useful for cookie banners, A/B-tested elements, and anything that may or may not be there.

Navigation

navigate / openLink

Go to a URL. Waits for the page to finish loading.

- navigate: "https://example.com"

back

Navigate browser back one entry.

- back: true

goForward

Navigate browser forward one entry.

- goForward: true

refresh

Reload the current page.

- refresh: true

launchApp

Open an app by URL. If the value isn’t an http(s):// URL, the step is a no-op (reserved for native-app contexts).

- launchApp: "https://app.example.com"

Input

click / tapOn

Click (or tap) an element. If the element is outside the viewport, the executor scrolls to find an in-viewport equivalent before clicking.

- click: "Sign in button"

type / inputText

Type into a field. With a target, fills that specific field. Without one, fills the currently focused input — or the first visible input on the page as a fallback.

- type:
    target: "email field"
    text: "user@example.com"

- type: "user@example.com"   # fills focused/first visible input

clear / clearText

Clear a field. Same target rules as type.

- clear:
    target: "search input"

- clear: true   # clears focused/first visible input

pressKey

Press a single key. Use Playwright key names (Enter, Escape, Tab, ArrowDown, etc.).

- pressKey: "Enter"

longPress

Click and hold for one second. Useful for context menus on mobile-style sites.

- longPress: "thumbnail image"

doubleClick

Double-click an element.

- doubleClick: "row item"

rightClick

Right-click (context-menu click) an element.

- rightClick: "file in tree"

hover

Move the pointer over an element without clicking.

- hover: "user avatar"

scroll / swipe

Scroll the page. Direction defaults to down.

- scroll: "down"
- scroll:
    direction: "up"

Accepted values: down, up, left, right.

selectOption

Pick an option from a <select> dropdown. With a target, picks from that specific dropdown; without, uses the first visible select on the page.

- selectOption:
    target: "country dropdown"
    value: "US"

- selectOption: "US"

check

Check a checkbox. No-op if it’s already checked.

- check: "I agree to the terms"

uncheck

Uncheck a checkbox. No-op if it’s already unchecked.

- uncheck: "Subscribe to newsletter"

Assertions

All assertions wait up to 10 seconds for the condition to become true before failing. There’s no per-step override flag.

verifyVisible / assertVisible

Assert an element (or text) is visible. With a string target, falls back to fuzzy text search if the exact text isn’t found — see Locator resolution.

- verifyVisible: "Welcome back"

- verifyVisible:
    target: "Sign out button"

verifyNotVisible / assertNotVisible

Assert an element is not visible.

- verifyNotVisible: "Loading spinner"

verifyText

Assert exact text content of an element. With elementType: "text" (or just a string), falls back to the same fuzzy text search as verifyVisible.

- verifyText:
    target: "page heading"
    elementType: "heading"
    expected: "Dashboard"

- verifyText: "Welcome back"

verifyContainsText

Assert an element contains the given text (substring match).

- verifyContainsText:
    target: "status message"
    expected: "successfully"

verifyValue

Assert the value of an input matches.

- verifyValue:
    target: "email input"
    expected: "user@example.com"

verifyAttribute

Assert an HTML attribute equals an expected string.

- verifyAttribute:
    target: "submit button"
    attribute: "disabled"
    expected: "true"

verifyCount

Assert the number of matching elements. With elementType: "checkbox" or "button", counts by ARIA role; otherwise by text match.

- verifyCount:
    elementType: "checkbox"
    count: 3

- verifyCount:
    target: "row item"
    count: 5

verifyChecked / verifyNotChecked

Assert a checkbox or radio is (or isn’t) checked.

- verifyChecked: "Remember me"
- verifyNotChecked: "Subscribe to newsletter"

verifyEnabled / verifyDisabled

Assert an interactive element is (or isn’t) enabled.

- verifyEnabled: "Submit button"
- verifyDisabled: "Submit button"

verifyFocused

Assert an element currently has keyboard focus.

- verifyFocused: "search input"

verifyEmpty

Assert an element has no children or text.

- verifyEmpty: "empty cart message"

verifyUrl

Assert the current page URL matches.

- verifyUrl: "https://example.com/dashboard"

verifyTitle

Assert the document title matches.

- verifyTitle: "Dashboard — Example"

Waits

wait

Pause execution. Defaults to 2 seconds if no value given.

- wait: 5

- wait:
    seconds: 5

Use sparingly — every assertion already auto-waits up to 10 seconds. Hard sleeps are usually a sign of a missing assertion.

waitForLoad

Wait for the network to go idle (no requests for 500ms). Times out at 15 seconds and continues without failing — the run keeps going either way.

- waitForLoad: true

waitForElement

Wait for an element matching the given text to become visible. Default timeout 10 seconds, override per-step.

- waitForElement: "Dashboard"

- waitForElement:
    target: "Dashboard"
    timeout: 30000

timeout is in milliseconds.

Screenshots and visual regression

screenshot / takeScreenshot

Capture a screenshot. With a target, captures just that element; without, captures the full page.

- screenshot: true                  # full page

- screenshot:
    target: "search input"
    elementType: "input"            # element-only

When the test runs in visual regression mode with a saved baseline, the screenshot is compared against the baseline using a vision model. See Visual regression for the comparison mechanics.

Screenshot steps respect optional: true — if the target element isn’t there, the step is skipped, not failed.

Action aliases

A few actions accept multiple keys for readability. They’re identical:

Canonical	Alias
click	tapOn
type	inputText
clear	clearText
verifyVisible	assertVisible
verifyNotVisible	assertNotVisible
screenshot	takeScreenshot
navigate	openLink
scroll	swipe

See also

• YAML schema reference — the file structure these actions live inside
• Locator resolution — how target: "Sign in button" finds the right element
• Visual regression — what the screenshot action does on a baseline run