Scenarios
Reference for scenario fields and every step type, with all options and defaults.
The guide to writing scenarios is Interaction scenarios. This page lists every field.
Scenario
| Field | Type | Default | Description |
|---|---|---|---|
id | string | required | Stable id used to match captures: letters, digits, ., _, -, max 80 |
name | string | id | Shown in reports |
path | string | "/" | Opened relative to baseURL before the steps run |
url | string | — | Absolute http(s) URL, instead of baseURL + path |
viewports | string[] | all | Names of viewports to run in |
steps | Step[] | [] | See below. Checkpoint labels must be unique within the scenario |
timeout | number (ms) | capture.scenarioTimeout | Overall scenario timeout |
skip | boolean | string | — | Skip the scenario; a string documents why |
tags | string[] | — | Free-form |
Checkpoints
| Step | Fields |
|---|---|
capture | label (required), frames? (default capture.frames.enabled), maxWindow? (ms, overrides capture.maxWindow), screenshot? (default true) |
screenshot | label (required), fullPage?, selector? (one element instead of the viewport) |
Labels: 1–80 characters, letters, digits, spaces, ., _, -, starting with a letter or digit.
{ type: "capture", label: "menu-open" }
{ type: "capture", label: "intro", frames: false } // timing and samples only, no filmstrip
{ type: "capture", label: "hero", maxWindow: 8000 } // allow a longer motion window
{ type: "screenshot", label: "footer", selector: "footer" }Interactions
Each interaction is a trigger: the first motion after it becomes t = 0 of the next
checkpoint.
| Step | Fields | Notes |
|---|---|---|
click | selector, button? (left, right, middle), clickCount? (1–3), position? {x, y}, force?, timeout? | position is relative to the element's top-left corner |
hover | selector, position?, force?, timeout? | |
move | x, y (viewport CSS px), steps? (1–100 intermediate mousemove events) | Moves the mouse |
fill | selector, value, timeout? | The value is never written to captures, reports or error messages |
press | key (Playwright key name: Enter, Escape, ArrowDown, …), selector? (focus first), timeout? | |
scroll | x?, y? (absolute CSS px), selector? (a container) | Instant positioning, not scroll motion |
scrollIntoView | selector, block? (start, center, end, nearest), timeout? | Instant positioning, not scroll motion |
force: true skips Playwright's actionability checks. timeout defaults to
capture.actionTimeout.
Scroll motion
| Step | Fields and defaults |
|---|---|
scrollTo | target (px on the scroll axis, or a selector), behavior (smooth | instant, default smooth), via (auto | lenis | native, default auto), axis?, offset?, selector? (a native container) |
wheel | deltaX (0), deltaY (0), steps (1, max 100), interval (16 ms), position? (default: viewport centre) |
waitForScrollSettled | timeout (5000 ms), threshold (0.5 px), stableFrames (6), minStableMs (100 ms) |
via: "auto"scrolls through the first attached Lenis instance when there is one, otherwise natively (with aSCROLL_NATIVEnote);via: "lenis"requires Lenis.wheelsends real wheel events, so smooth-scroll engines react exactly as they do for users.waitForScrollSettledresolves when every scroller moved less thanthresholdper sample forstableFramesconsecutive samples and at leastminStableMs. On timeout it addsSCROLL_NOT_SETTLEDinstead of failing.
See Lenis for what is recorded.
Navigation and waiting
| Step | Fields | Notes |
|---|---|---|
goto | path? (relative to baseURL) or url?, waitUntil? (load, domcontentloaded, networkidle, commit) | url takes precedence |
waitFor | selector, state? (attached, detached, visible, hidden; default visible), timeout? | |
waitForAnimations | timeout? (default capture.waitForAnimationsTimeout) | Waits until motion settles. A timeout is a warning, not a failure |
wait | duration (ms, max 60000) | Fixed delay. Prefer waitFor / waitForAnimations; use only for timers |
After every navigation MotionPR waits for the page to be ready: network idle (bounded by
capture.networkIdleTimeout), web fonts (document.fonts.ready), non-lazy images and settled
page-load animations. Each of these produces a diagnostic instead of silently continuing:
NETWORK_NOT_IDLE, FONTS_NOT_READY, IMAGES_NOT_LOADED.
Selectors
Selectors are Playwright selectors (CSS, text=…, role=…) and must match exactly one
element. An empty selector is a config error.
Helpers
defineScenario(scenario) and defineSteps(steps) return their argument unchanged and only add
types, for scenarios kept in separate modules.