Validate and troubleshoot

Validate a workflow without a browser

paxter validate path\to\workflow.yaml
paxter validate path\to\workflow.yaml --data cases.xlsx --rows 1-5

validate is a free command. It loads the workflow and, when configured, its data source, then reports:

Check	Example message
Unknown action names, with the closest match	Step 4: Unknown action 'Clik'. Did you mean 'Click'?
Missing required fields	Step 2: Press requires Data2 (Key).
Malformed targets	Step 3: Invalid target 'lable=Email': Unknown target kind 'lable='. Did you mean 'label='?
Invalid comparison modes, counts, indexes, URLs, and wait durations	Step 6: Comparison mode 'sorta' is not supported. Use contains, exact, or regex.
Placeholders that match no data column	Step 5: Placeholder {{Emial}} does not match a column in cases.csv. Did you mean {{Email}}?
Variables used before they are defined	Step 7: Variable __code is used before it is defined.
Environment variables that are not set	Step 3: Environment variable 'PAXTER_TEST_PASSWORD' used by {{env:PAXTER_TEST_PASSWORD}} is not set on this machine.
Data source problems	Missing file, unsupported format, unmatched quotes, unknown worksheet, invalid ExpectedOutcome values, rows that are all skipped, or data that no step references.
Timeout settings outside their ranges	ActionTimeoutMilliseconds must be between 1000 and 120000.
Style advice	WaitFor5Seconds slows every run. Prefer Expect_Visible or Expect_Text on the element you are waiting for.

Errors exit with code 1, which makes validate a useful pull-request check for workflow repositories. run performs the same validation and refuses to launch the browser when errors exist.

Validate the project source

dotnet build Paxter.sln --configuration Release
dotnet test Paxter.sln --no-build --configuration Release

The test project includes browser-backed fixture tests that run against a local HTML page; they are skipped automatically when the Playwright Chromium build is not installed.

Validate a workflow safely

1. Use a dedicated test environment and non-sensitive test data.
2. Start with Headless: true and NeedVideo: false.
3. Run paxter validate after every edit.
4. Set Verbose: true in your local configuration when troubleshooting.
5. Review the generated HTML report and output.json after each run.

Reading a failed step

When an element cannot be used, the console and the report show the Playwright error together with What Paxter found: whether several elements matched, whether a matching element is hidden or disabled, whether the page uses frames, and the nearest elements on the page with ready-to-paste targets. The screenshot taken at the moment of failure sits next to the step. Start from those hints before changing the workflow; see Targets for the reasoning behind each suggestion.

Common errors

Message or symptom	Likely cause	What to check
Configuration file not found	paxter.yaml is not in the current working directory.	Run from the configuration directory or change into it first.
YAML test file not found	The path supplied to run or validate does not exist.	Use an absolute path or verify the relative path.
is not valid workflow YAML at line N	A YAML syntax problem, most often an unquoted placeholder.	Write Value: "{{Email}}" with quotes, and check the field names listed in the message.
The workflow was not run because validation found errors	One or more validation errors.	Fix the listed steps; paxter validate repeats the list.
Browser launch failure	Playwright browser binaries are unavailable or ChromiumPath is invalid.	Run paxter setup, or leave ChromiumPath empty to use Paxter's managed browser.
strict mode violation	An explicit target matched several elements.	Add ;first, ;nth=N, or ;exact, or use a more specific role and name.
Step passes locally but fails in CI	Timing differences.	Replace fixed waits with Expect_Visible or Expect_Text, or raise ExpectTimeoutMilliseconds.
Unsupported conversion line	The converter does not recognise that Playwright statement.	Review the conversion log and add a supported action manually.