Quick Reference

A single-page reference of all Vanya verbs, modifiers, and selectors for the playwright-python plugin.

File Structure

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

Script title: "test_suite_name"

Setup for each Scenario:
    Within the Browser (plugin: playwright-python, type: browser)
        # shared setup here

Scenario: "test case one"
    # actions and assertions

Scenario: "test case two"
    # actions and assertions

Actions (Verbs)

Verb	Syntax	Description
go to	go to <url>	Navigate to a URL
click	click <target>	Click an element
type	type <text> into <target>	Type text into an input
press	press <key>	Press a keyboard key
see	see <q> <target>	Assert element visibility
wait for	wait for <target>	Wait for element to appear
expect failure	expect failure	Expect an error in nested actions

Navigation

go to "https://example.com"
go to "/login"
go to "/users/{user_id}"  # Variable interpolation

Click

click button
click submit-button
click button (id: 'submit')
click button (testid: 'login-btn')
click button (class: 'primary')
click button (role: 'button', name: 'Submit')

Type

type "hello" into input
type "user@example.com" into email-input
type "password123" into input (id: 'password')
type "{stored_value}" into search-input  # Variable interpolation

Press

press Enter
press Tab
press Escape
press Space
press ArrowDown

See (Assertions)

see a button                           # Exactly one visible
see an input                           # Exactly one visible
see any div (class: 'item')            # At least one visible
see no span (class: 'error')           # Zero elements
see a li (text: 'Hello')               # With text content
see a li (class: 'completed', text: 'Buy milk')  # Combined selectors
see a div (state: 'attached')          # Check attached (not necessarily visible)
see a div (state: 'hidden')            # Check hidden

Wait For

wait for button
wait for div (id: 'loading')
wait for span (state: 'visible')
wait for modal (state: 'hidden')
wait for element (timeout: 10000)

Expect Failure

expect failure
    click missing-button

expect failure (error: 'TimeoutError')
    click button (timeout: 100)

expect failure (error: 'TimeoutError', capture: 'exc_info')
    go to "https://unreachable.example"

Selectors & Modifiers

Element Selectors

Modifier	Example	Generated Locator
id	(id: 'submit')	#submit
class	(class: 'btn')	.btn
class	(class: 'btn primary')	.btn.primary
testid	(testid: 'login')	[data-testid='login']
role	(role: 'button')	get_by_role("button")
role + name	(role: 'button', name: 'Submit')	get_by_role("button", name="Submit")
text	(text: 'Hello')	has_text="Hello"

Modifier Composition

When combining modifiers, they compose into a single selector:

# class + text
see a li (class: 'completed', text: 'Buy milk')
# Generates: ctx.locator("li.completed", has_text="Buy milk")

# Multiple classes (space-separated)
see a li (class: 'todo-item completed', text: 'Buy milk')
# Generates: ctx.locator("li.todo-item.completed", has_text="Buy milk")

Common Modifiers

Modifier	Type	Description
timeout	quoted	Action timeout in milliseconds
state	quoted	Element state (visible, hidden, attached, detached)
exact	quoted	Exact text match (for text modifier)

Form Interactions

Checkboxes and Radio Buttons

Use click to toggle checkboxes and radio buttons. Vanya relies on Playwright’s native 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')

Playwright behavior

Clicking a checkbox toggles its state (checked to unchecked or vice versa). Clicking a radio button selects it. There is no separate check or toggle verb in Vanya.

Text Inputs

type "hello@example.com" into input (id: 'email')
type "secure123" into input (testid: 'password')

Select Dropdowns

Use click with role selectors:

click select (id: 'country')
click option (text: 'United States')

Within Blocks

Browser Context

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

Element Scoping

Within the Browser (plugin: playwright-python, type: browser)
    Within the Login Form (type: element, id: 'login')
        type "user" into input (id: 'username')
        type "pass" into input (id: 'password')
        click button

API Context

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

    POST "/users" body '{"name": "alice"}'
        expect status 201
        capture "$.id" as user_id

State Management

Define (Aliases)

Define login-btn (id: 'submit', class: 'primary')
Define email-input (testid: 'email-field')

click login-btn        # Uses the defined selector
type "a@b.c" into email-input

Capture (Store Values)

POST "/users" body '{"name": "alice"}'
    capture "$.id" as user_id

GET "/users/{user_id}"
    expect status 200

Export (For Test Fixtures)

Export user_id
Export auth_token

Complete Example

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

Script title: "todo_app"

Setup for each Scenario:
    Within the Browser (plugin: playwright-python, type: browser, url: 'http://localhost:3000')
        Define new-todo (testid: 'new-todo-input')
        Define todo-item (class: 'todo-item')

Scenario: "user can add a todo"
    type "Buy milk" into new-todo
    press Enter
    see a todo-item (text: 'Buy milk')

Scenario: "user can complete a todo"
    type "Buy milk" into new-todo
    press Enter
    Within the Todo Item (type: element, class: 'todo-item', text: 'Buy milk')
        click input (role: 'checkbox')
    see a li (class: 'completed', text: 'Buy milk')

CLI Commands

# Validate syntax and semantics
vanya check tests/*.vanya

# Format code
vanya fmt tests/*.vanya

# Build (transpile to Python)
vanya build tests/*.vanya -o out/

# Run tests (after building)
pytest out/