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
• see url <url:quoted> - assert current URL matches exactly
• see url contains <url:quoted> - assert current URL contains string
• click <target:unquoted> - click an element
• type <text:quoted> into <target:unquoted> - type into an input
• press <key:unquoted> - press a keyboard key (e.g., Enter, Tab, Escape)
• 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 (see warning below)
• state - assertion state for see (attached, hidden) or wait state for wait for (visible, hidden, attached, detached)

Strict Mode and text: Modifier

When using see a (singular) with text:, Playwright’s strict mode may match multiple elements if parent containers also contain the same text. For example:

see a div (text: 'Error')

This can fail with a strict mode violation like:

strict mode violation: locator("div").filter(has_text="Error") resolved to 3 elements

This happens because has_text matches ALL elements containing the text, including ancestor divs that wrap the actual target element.

Recommendations:

• Use see any when text matching might be ambiguous
• Pair text: with a unique selector like testid: or class: to identify the leaf node
• Use a more specific tag (e.g., span, p) instead of generic div

# Preferred: use testid to uniquely identify the element
see a div (testid: 'error-message', text: 'Error')

# Or use see any when multiple matches are acceptable
see any div (text: 'Error')

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.

Form element interactions

Checkboxes and radio buttons

Use click to toggle checkboxes and select radio buttons. Vanya relies on Playwright’s native click behavior:

# Toggle a checkbox
click input (testid: 'agree-checkbox')
click input (role: 'checkbox')

# Select a radio button
click input (testid: 'option-a')
click input (role: 'radio', name: 'Option A')

Clicking a checkbox toggles its checked state. Clicking a radio button selects it and deselects other radios in the same group. There is no separate check or toggle verb in Vanya - click is the canonical way to interact with these elements.

Verifying checkbox state

To verify a checkbox is checked or unchecked:

# Verify checkbox is visible and can be clicked
see a input (role: 'checkbox', name: 'Agree')

# After clicking, verify the todo is marked complete
click input (role: 'checkbox')
see a li (class: 'todo-item completed')