DSL
Steps
The actions a step can take and the keys every step accepts.
A step is an object with exactly one action key, plus any of the common keys below. when and loop_until are control steps that hold steps of their own.
#Actions
| Action | Type | Description |
|---|---|---|
fill | target | Types a value into a field. The target must be visible and editable; values typed into type=password fields are redacted. |
click | target | Clicks an element once it is visible, enabled and not covered; an obstacle in the way is handled by the obstacle layer first. |
press | string | Presses a key, named as Playwright names keys (Enter, Tab, Control+A). |
hover | target | Moves the mouse over an element, for menus and tooltips that open on hover. |
select | target | Chooses an option of a native <select> element, by exactly one of value, label or index (lint E001 otherwise). |
check | target | Checks a checkbox or selects a radio button. |
uncheck | target | Unchecks a checkbox. |
upload | target | Sets the files of a file input from your organisation's uploaded assets. |
scroll | target or object | Scrolls an element into view when given a target, or scrolls the page with the object form, for infinite-scroll lists. The object form needs to or until. |
wait_for | condition | Waits until a condition holds, up to the step's timeout_ms, without doing anything else. |
set_session | string | Loads the named session's storage state at this point in the program. Rarely needed; prefer options.session. |
extract | extract | Reads data from the page with an extract schema. The last extract into data produces the job's result; several merge shallowly, later keys winning. |
capture_response | object | Waits for a network response matching url (and method), observed since the step started, and stores its parsed JSON body in a variable. Bodies are limited to 2 MB. |
evaluate | object | Runs your own JavaScript in the page. The healer cannot see inside it, so lint warns W006, and it requires a paid organisation. |
paginate | object | Runs extract on each page, then follows next. Top-level many: true fields are concatenated across pages and other fields come from the first page; it stops at max_pages, when stop_when holds, when next is not found, or when the step's expect does not hold after next. A page whose extraction fails fails the step on that page; a next that breaks after some pages keeps them, with a pagination_incomplete warning. |
download | object | Clicks a trigger, captures the file it downloads and stores it as a job artifact with the response's content type. A PDF passes the PDF security gate first: a blocked one is never stored, and the step fails with its code. |
read_pdf | object | Reads the tables of a PDF the job has stored: the page the job is on when it is a PDF, or a named artifact such as a download's. Cells are returned exactly as printed, as strings; a table that continues over pages is one table. The file already passed the PDF security gate; nothing is fetched again. Lint warns W010 when no earlier goto or download could have produced the PDF. |
set_vars | map of string | Sets variables from templates, as a map of variable name to template; each is readable later as {{vars.<name>}}. |
sleep | integer | Pauses for a fixed number of milliseconds, at most 10000. Lint warns W003; a wait_for condition is usually better. |
reload | true | Reloads the current page. The value is always true. |
goto | string or object | Navigates the top frame to a URL, given as a template string or an object. It then waits for the page to settle (500 ms of network quiet, at most 10 s); lint warns W001 without an expect. |
await_input | string or object | Pauses the job as awaiting_input until a value such as a one-time code is supplied, then stores it in vars.<name>. The string form names the input. |
checkpoint | string or object | Saves the page URL, variables and browser state so a parked or resumed job can return here. The string form is the checkpoint's name. |
screenshot | string or object | Takes a screenshot, stored as the artifact artifacts.<name>. The string form is the name. |
when | condition | Runs do when a condition holds and else, if given, when it does not. |
loop_until | condition | Repeats do until a condition holds. The condition is checked before each iteration; after max iterations the job fails with loop_exhausted unless the step is optional. |
#Common keys
| Key | Type | Description |
|---|---|---|
expect | condition | A postcondition that must hold after the action, re-evaluated every 250 ms until timeout_ms. When it never holds, Kaabist diagnoses the failure; lint W001 warns about a goto or click without one. |
id | string | The step's id, matching ^[a-z0-9][a-z0-9-]{0,31}$ and unique within the program (lint E006). Assigned as s<N> when absent. |
if | condition | A guard condition evaluated before the step; when it is false the step is skipped without failing. |
name | string | A human-readable label for the step. |
on_error | "fail" | "skip" | "park" | What happens when the step fails and nothing else recovered it: fail (the default), skip, or park, which stops the job as needs_attention with the step's evidence. |
optional | boolean | When true, a failure of this step is recorded as the warning step_skipped and the job continues. Defaults to false; not allowed on a side_effect step (lint E011). |
retry | object | How many times a transient failure of this step is retried. Not allowed on a side_effect step (lint E011). |
retry.backoff_ms | integer | The wait between retries in milliseconds, from 0 to 60000. Defaults to 1000. |
retry.max | integer | The number of retries, from 0 to 5. |
side_effect | boolean | Marks a step that changes something outside the page, such as placing an order. It runs behind a fence: a side effect that was interrupted, or that failed after its action reached the page, parks the job as side_effect_ambiguous instead of repeating it; it is never retried, healed or escalated. Defaults to false. |
timeout_ms | integer | How long the step may take, in milliseconds, up to 900000. Defaults to 30000, 60000 for goto, and the ttl for await_input. |
x_kaab | object | A free-form object written by tools such as the recorder, takeover and picker, for example { "source": "takeover" }. Lint ignores it and the engine never reads it, but it is kept through normalization, diffs and versions. |