Modifiers

Modifiers provide additional configuration for actions and Within blocks. They are key-value pairs that customize behavior, specify selectors, or set timeouts.

Syntax Forms

Vanya supports two equivalent syntaxes for modifiers.

Parentheses Syntax

Place modifiers in parentheses directly after the action or block name:

Within the Browser (plugin: playwright-python, type: browser)
    click button (timeout: 5000)
    go to "/login" (timeout: 30000)

Multiple modifiers are separated by commas:

Within the Login Form (type: element, id: 'login_form', class: 'auth')
    type "hello" into email-input (timeout: 5000)

With Syntax

For inline modifier lists, use with:

click button with timeout: 5000
go to "/login" with timeout: 30000

Multiple modifiers with with are also comma-separated:

wait for div with timeout: 5000, state: visible

Both syntaxes are equivalent. Patterns with indented blocks (via returns) must use parentheses syntax.

Modifier Values

Modifier values can be quoted strings or unquoted identifiers:

# Quoted values
click button (id: 'submit_btn')
click button (id: "submit_btn")

# Unquoted values
Within the Browser (plugin: playwright-python, type: browser)

The plugin defines whether each modifier expects a quoted or unquoted value type.

Reserved Modifiers

Two modifiers are handled by vanya core and are not passed to plugins:

Modifier	Description	Required
plugin	Selects the plugin (e.g., playwright-python)	Required at root Within block; inherited by nested blocks
type	Selects the type within the plugin (e.g., browser, element, api)	Always required on Within blocks

Within the Browser (plugin: playwright-python, type: browser)
    # Nested block inherits plugin, must specify type
    Within the Form (type: element, id: 'login')
        click submit-button

Plugin-Defined Modifiers

All other modifiers are defined by plugins. Each type and pattern declares its valid modifier keys in the plugin TOML file.

Type Modifiers

Types can declare modifiers that apply to Within blocks of that type:

# browser type supports: url, headless
Within the Browser (plugin: playwright-python, type: browser, url: 'http://localhost:3000')

# element type supports: id, class, testid, label
Within the Form (type: element, id: 'login_form')

# api type supports: base, timeout, headers
Within the API (plugin: python-requests, type: api, base: 'http://api.local')

Pattern Modifiers

Patterns declare modifiers that apply to specific actions:

# click pattern supports: timeout
click button (timeout: 5000)

# wait-for pattern supports: timeout, state
wait for div (timeout: 10000, state: visible)

# see pattern supports: text
see a span (text: 'Welcome')

# expect-failure pattern supports: error, capture
expect failure (error: 'TimeoutError', capture: 'exc_info')
    click button (testid: 'missing')

Modifier Precedence

When both the type and pattern define the same modifier key, the pattern takes precedence. The valid modifiers for an action are the union of type modifiers and pattern modifiers.

Available Modifiers by Plugin

playwright-python

browser type

Modifier	Type	Description
url	quoted	Initial URL to navigate to
headless	quoted	Run browser in headless mode

element type

Modifier	Type	Description
id	quoted	HTML id attribute selector
class	quoted	CSS class selector
testid	quoted	data-testid attribute selector
label	quoted	Accessible label selector

Pattern modifiers

Pattern	Modifier	Type	Description
go to	timeout	quoted	Navigation timeout in ms
click	timeout	quoted	Click timeout in ms
type ... into	timeout	quoted	Input timeout in ms
see	text	quoted	Text content to match
wait for	timeout	quoted	Wait timeout in ms
wait for	state	quoted	Wait condition (e.g., visible)
expect failure	error	quoted	Exception type to expect
expect failure	capture	quoted	Variable name to capture exception

python-requests

api type

Modifier	Type	Description
base	quoted	Base URL for API requests
timeout	quoted	Request timeout in ms
headers	quoted	HTTP headers

Pattern modifiers

Pattern	Modifier	Type	Description
GET	headers	quoted	Request headers
GET	timeout	quoted	Request timeout
POST	headers	quoted	Request headers
POST	timeout	quoted	Request timeout
PUT	headers	quoted	Request headers
PUT	timeout	quoted	Request timeout
DELETE	headers	quoted	Request headers
DELETE	timeout	quoted	Request timeout
expect failure	error	quoted	Exception type to expect
expect failure	capture	quoted	Variable name to capture exception

Validation

Using an unknown modifier key is a validation error. The vanya check command validates that:

1. All modifier keys are declared by the plugin type or pattern
2. Modifier values match the expected type (quoted or unquoted)
3. Required modifiers (plugin, type) are present where needed

vanya check tests/*.vanya

Examples

Browser Testing with Modifiers

Vanya test scenario (vanya-lang.org/v0.1)

Script title: "login_with_modifiers"

Within the Browser (plugin: playwright-python, type: browser, url: 'http://localhost:3000')
    go to "/login" (timeout: 30000)

    Within the Login Form (type: element, id: 'login_form')
        type "user@example.com" into email-input (timeout: 5000)
        click submit-button (timeout: 5000)

    see a div (text: 'Hello')
    wait for div (timeout: 10000, state: visible)

API Testing with Modifiers

Vanya test scenario (vanya-lang.org/v0.1)

Script title: "api_with_modifiers"

Within the API (plugin: python-requests, type: api, base: 'http://api.local', timeout: 30000)
    GET "/users" (headers: 'Authorization: Bearer token')
        expect status 200

    POST "/users" body '{"name": "alice"}' (timeout: 5000)
        expect status 201

Expected Failure with Captured Exception

Within the Browser (plugin: playwright-python, type: browser)
    expect failure (error: 'TimeoutError', capture: 'exc_info')
        click button (testid: 'does-not-exist', timeout: 1000)