Actions

Basic actions

Actions are statements that perform operations. They are matched against patterns defined in plugins. Each action consists of tokens (identifiers, strings, or numbers) that match a plugin-defined pattern.

go to "https://example.com"
click button
type "hello" into search-input

Actions can only appear inside Within blocks, where they are matched against the patterns defined for that block’s type.

Pattern matching

Actions are matched against patterns defined in plugins. The plugin determines which actions are valid in each context. Patterns define the syntax using literal words and typed slots.

For example, in a browser context (from the playwright-python plugin):

• go to <url:quoted> - navigate to URL
• click <target:unquoted> - click an element
• type <text:quoted> into <target:unquoted> - type into an input
• see <q:a|an|any|no> <target:unquoted> - assert element visibility
• wait for <target:unquoted> - wait for an element to appear

In an api context (from the python-requests plugin):

• GET <path:quoted> - make a GET request
• POST <path:quoted> body <body:quoted> - make a POST request with body
• expect status <code:unquoted> - assert response status code
• expect json <path:quoted> == <value:quoted> - assert JSON value

Slots

Patterns have slots (placeholders) that capture values:

type "hello" into search-input
     ^^^^^^^      ^^^^^^^^^^^^
     text slot    target slot
     (quoted)     (unquoted)

Slots can be:

• quoted - must be a string literal (single or double quotes)
• unquoted - must be an identifier or hyphenated identifier (like submit-button)
• union - one of several literal keywords

Quoted slots

Quoted slots capture string literals. They are written as <name:quoted> in patterns.

go to "/login"
type "user@example.com" into email-input
POST "/users" body '{"name": "alice"}'

Quoted strings support variable interpolation with {var}:

GET "/users/{user_id}"

Unquoted slots

Unquoted slots capture identifiers or hyphenated identifiers. They are written as <name:unquoted> in patterns.

click button
click submit-button
type "hello" into email-input

Unquoted slots can reference aliases defined with Define:

Define submit-button (id: 'submit', class: 'primary')
click submit-button

Union slots

Union slots accept one of several literal keywords. They are written as <name:keyword1|keyword2|...> in patterns.

see a div (class: 'welcome')
see an input (id: 'email')
see any button
see no span (class: 'error')

In the see pattern, the quantifier slot accepts a, an, any, or no:

• a or an - exactly one element must match
• any - at least one element must match
• no - zero elements must match

Action modifiers

Actions can have modifiers that provide additional parameters. Two syntaxes are supported:

Parentheses syntax

click button (id: 'submit', timeout: '5s')
see a div (class: 'welcome', text: 'Hello')

With syntax

click button with id: 'submit', timeout: '5s'
see a div with class: 'welcome', text: 'Hello'

Both syntaxes are equivalent. Modifier keys and their valid types are defined by the plugin pattern.

Common modifiers for browser actions:

• timeout - wait timeout for the action
• id, class, testid, label - element selectors
• text - expected text content

Action blocks

Some actions can have nested blocks with child statements. The action block is indented under the action.

POST "/orders" body '{"items": [...]}'
    expect status 201
    capture "$.id" as order_id

Action blocks can contain:

• Child action statements (like expect status 201)
• Capture statements (like capture "$.id" as order_id)

The pattern’s returns field in the plugin determines what type of block is opened. For example, the expect failure pattern returns a failure_block where errors are expected:

expect failure (error: 'TimeoutError')
    click missing-button

Numbers in actions

Action tokens can include numbers for patterns that need them:

expect status 200
wait 5 seconds

Numbers are written as bare digits without quotes.