Step API

Complete reference for all step actions available in scenario definitions.

goto

Navigate to a URL.

{
  "action": "goto",
  "url": "/dashboard"
}

Property	Type	Required	Description
`url`	string	✓	URL to navigate to

Interactions

click

Click an element.

{
  "action": "click",
  "selector": "[data-testid='submit']",
  "description": "Click submit button"
}

Property	Type	Required	Description
`selector`	string	✓	Element selector
`description`	string	✗	Human-readable description

type

Type text into an input.

{
  "action": "type",
  "selector": "#email",
  "text": "user@example.com"
}

Property	Type	Required	Description
`selector`	string	✓	Input selector
`text`	string	✓	Text to type

hover

Hover over an element.

{
  "action": "hover",
  "selector": "[data-testid='dropdown']"
}

Property	Type	Required	Description
`selector`	string	✓	Element selector

Waiting

wait

Pause for a fixed duration.

{
  "action": "wait",
  "ms": 1000
}

Property	Type	Required	Description
`ms`	number	✓	Milliseconds to wait

waitFor

Wait for an element to appear.

{
  "action": "waitFor",
  "selector": ".loading-complete",
  "timeout": 5000
}

Property	Type	Required	Description
`selector`	string	✓	Element selector
`timeout`	number	✗	Max wait time (ms)

Capture

capture

Take a screenshot or video.

{
  "action": "capture",
  "key": "dashboard-hero",
  "selector": "[data-testid='hero']",
  "type": "screenshot",
  "crop": { "x": 0, "y": 0, "width": 800, "height": 600 }
}

Property	Type	Required	Description
`key`	string	✓	Unique asset identifier
`selector`	string	✗	Element to capture
`type`	string	✗	`screenshot` or `video`
`clip`	object	✗	Viewport clip region
`crop`	object	✗	Persisted crop region
`duration`	number	✗	Video duration (ms)

Selectors

Poliage supports multiple selector formats:

Type	Example
CSS	`.btn-primary`, `#submit`, `button.large`
Playwright	`role=button[name="Save"]`
Text	`text="Welcome back"`
Data Attribute	`[data-testid="nav-menu"]`

Prefer data-testid attributes for stable, maintainable selectors.