Define & Export

Define

Create named aliases for selectors within a Within block:

Within the Browser (plugin: playwright-python, type: browser)
    Define submit-button (id: 'submit')
    Define email-input (testid: 'email-field')
    Define error-message (class: 'error')

    click submit-button
    type "user@example.com" into email-input
    see no error-message

Aliases are resolved at compile time. They can only be used in unquoted pattern slots and shadow literal tokens.

Supported Modifiers for Define

Define supports a subset of selectors that map directly to CSS or Playwright locators:

Modifier	Generated Selector	Example
id	#value	Define btn (id: 'submit')
testid	[data-testid='value']	Define form (testid: 'login')
class	.value	Define card (class: 'product')
label	get_by_label()	Define input (label: 'Email')
text	get_by_text()	Define heading (text: 'Welcome')
role + name	get_by_role(role, name)	Define btn (role: 'button', name: 'Submit')
role	get_by_role(role)	Define nav (role: 'navigation')

Priority order: When multiple modifiers are specified, Define uses this priority: id > testid > class > label > text > role+name > role.

Note: For complex selectors combining multiple attributes (e.g., tag + class + text), use inline modifiers on actions or Within blocks with type: element instead.

Scoping Rules

• Define is only valid inside a Within block
• Aliases share a single flat scope across the entire script (not block-scoped)
• Alias names must be unique across the script; reusing a name is a compile error
• Aliases cannot be exported (they are resolved at compile time)
• Reserved words (Script, Within, Define, Export) cannot be used as alias names

Capture

Capture values from responses into variables:

Within the API (plugin: python-requests, type: api, base: 'http://localhost:8080')
    POST "/users" body '{"name": "alice"}'
        Capture "$.id" as userId

Variables created via Capture can be interpolated in later statements using {varname} syntax:

    GET "/users/{userId}"

Export

Export captured variables for use in sibling and subsequent Within blocks:

Within the API (plugin: python-requests, type: api, base: 'http://localhost:8080')
    POST "/users" body '{"name": "alice", "email": "alice@test.com"}'
        Capture "$.id" as userId
    Export userId

Within the Browser (plugin: playwright-python, type: browser, url: 'http://localhost:8080')
    go to "/users/{userId}"
    see any user-profile

Export Rules

• Export only works on variables (not aliases)
• Export is only valid directly inside a Within block (not inside pattern blocks)
• Export must appear after the variable is captured, within the same Within block
• Exporting an undefined variable is a compile error
• Exporting the same name from multiple blocks is a compile error
• If a variable and alias have the same name in overlapping scope, it is a compile error