Run a workflow

paxter run path\to\workflow.yaml
paxter run path\to\workflow.yaml --data cases.csv --rows 1-5

run requires a verified local Paxter registration. Registered access allows up to 10 workflow actions; larger workflows require a current subscription. Without a path, run loads the bundled empty sample workflow.

Option	Purpose
--data <file>	Run the workflow once per row of a CSV, TSV, or .xlsx file, overriding DataSource.Path. See data-driven testing.
--rows <selection>	Limit a data-driven run to rows such as 2, 1-3, or 1-3,7 (1-based, header excluded).

What happens on a run

1. The workflow (and its data source) is loaded and validated. Unknown actions, missing fields, malformed targets, unresolved placeholders, and data problems are printed with suggestions, and the browser is not launched if any error is found. paxter validate performs the same checks on its own.
2. The registered step limit is checked.
3. Each action runs in order. The console shows one line per step with its outcome and duration. A failed step prints the error and the hints Paxter gathered from the page.
4. An HTML report, output.json, screenshots, and optional video are written to a timestamped folder under OutputPath.

The process exit code is 0 when the run met its expected outcome and 1 when it failed or validation stopped it, so CI pipelines can gate on it.

Workflow structure

Name: Sign-in smoke test
Description: Signs in with a known test account and checks the greeting.
Headless: true
NeedVideo: false
ActionTimeoutMilliseconds: 30000
ExpectTimeoutMilliseconds: 5000
TargetResolveMilliseconds: 5000
Actions:
  - Do: Page_GotoAsync
    Data1: https://your-test-environment.example/sign-in
  - Do: Fill
    Name: Enter the test account
    Target: label=Email address
    Value: test.user@example.invalid
  - Do: Fill
    Target: label=Password
    Value: "{{env:PAXTER_TEST_PASSWORD}}"
    Secret: true
  - Do: Click
    Target: button=Sign in
  - Do: Expect_Text
    Target: role=status
    Value: Welcome back

Field	Meaning
Name, Description	Shown in the console and the report header.
Headless	true hides the browser window. Default false.
NeedVideo	Records a video of the run. Default true.
ActionTimeoutMilliseconds	Maximum time for one browser action such as a click (1,000 to 120,000; default 30,000).
ExpectTimeoutMilliseconds	How long an Expect_* assertion waits for the page to satisfy it (100 to 120,000; default 5,000).
TargetResolveMilliseconds	Budget for automatic target resolution and fallback chains (0 to 30,000; default 5,000).
DataSource	Optional data file that turns the workflow into a suite. See data-driven testing.
ApiDiagnostics, NetworkTraffic	Optional API and network evidence for single-page applications. See API diagnostics.
Actions	The ordered steps.

Each step accepts:

Field	Meaning
Do	The action name, for example Click or Expect_Text. Plain-English aliases such as Should see are accepted; paxter actions lists them.
Name	Optional readable label shown in the console and report.
Target / Data1	The element target (see Targets) or, for navigation and page assertions, the URL or expected value.
Value, Key / Data2	The value to enter or expect, or the key to press.
Mode / Data3	The comparison mode for assertions: contains, exact, or regex.
Pipe	A text transformation such as `trim
Secret	true masks the value in the console, report, and output.json.
Optional	true records a failure of this step as a warning and continues with the next step.
Group	Do: Group with Data1: name labels the following steps in the report.

Placeholders ({{Column}}, {{env:NAME}}, {{__variable}}, {{today}}) work in every data field; quote values that start with {{.

Reading the report

The report opens on the Steps tab. Each step shows the action, its data (secrets masked), the strategy that located the element (Resolved via), the duration, the status, and a screenshot. A failed step additionally shows the error, the screenshot taken at the moment of failure, and What Paxter found: hidden or disabled matches, ambiguous matches, frames, and the nearest elements with ready-to-paste targets.

Data-driven case reports add a Case data panel with the row values. The Gallery, Video, API diagnostics, and Network traffic tabs appear when there is content for them. Paths inside the report are relative, so the run folder can be archived or shared as a whole.

Parallel runs

Parallel execution is a paid capability. Set MaxParallelTests and TestIterations in paxter.yaml, then use runparallel:

paxter runparallel path\to\workflow.yaml

For a plain workflow at least one of MaxParallelTests and TestIterations must be greater than 1; the standard run command rejects parallel settings. For a data-driven workflow, runparallel runs the rows concurrently up to MaxParallelTests, and TestIterations repeats every row. Paxter limits parallel execution to 20 workers and iterations to 100. Iteration reports are written below the configured temporary path; data-driven suite reports are written below OutputPath.

Exit behaviour

A failed action is recorded with its error and evidence and stops the remaining actions in that workflow unless the step is Optional. A data-driven suite continues with the next case. The exit code is 1 whenever any executed workflow did not meet its expected outcome.