Targets: how Paxter finds elements

Every generic action (Click, Fill, Expect_Text, and the rest) takes a target: a short expression that says which element to use. Targets are designed so that a tester can write what they see on the screen, and so that Paxter can explain itself when the page does not match.

- Do: Fill
  Target: label=Email address
  Value: test.user@example.invalid
- Do: Click
  Target: button=Sign in
- Do: Expect_Text
  Target: css=#message
  Value: Welcome back

Target is an alias for Data1; both spellings are accepted everywhere.

Target kinds

Prefix	Finds	Example
button=, link=, textbox=, checkbox=, radio=, combobox=, option=, heading=, tab=, menuitem=, cell=, row=, listitem=, img=, dialog=, switch=, searchbox=, spinbutton=, slider=, region=, navigation=, alert=, group=, table=, columnheader=, listbox=	An element with that ARIA role and accessible name. This is the most stable choice.	button=Save changes
role=	Any ARIA role, optionally with ;name=.	role=heading;name=Welcome
label=	A form control by its label text.	label=Password
placeholder=	An input by placeholder text.	placeholder=Search products
text=	An element by visible text.	text=Your order is confirmed
alt=	An image by alt text.	alt=Company logo
title=	An element by title attribute.	title=Close
testid=	The data-testid attribute.	testid=submit-order
id=	An element id (with or without #).	id=email
css=	Any CSS selector.	css=form.sign-in > button[type=submit]
xpath=	An XPath expression.	xpath=//table//tr[2]/td[3]

Names and texts match case-insensitively and by substring unless you add ;exact.

Modifiers

Append modifiers with ;:

Modifier	Meaning
;exact	Match the whole accessible name or text, not a substring.
;first	Use the first match when several elements match.
;last	Use the last match.
;nth=N	Use the match at zero-based index N.
;name=X	With role=, the accessible name.

Target: link=Details;nth=2
Target: text=Delete;exact;first
Target: css=table tbody tr;last

Fallback chains

Separate alternatives with ||. Paxter tries them in order and uses the first one that matches, so a workflow keeps working while a page is being redesigned:

- Do: Fill
  Target: label=Email || placeholder=Email address || css=#email
  Value: "{{Email}}"

The report shows which alternative was used in the Resolved via column, for example label=Email.

Plain text: automatic resolution

When a target has no prefix, Paxter resolves it automatically based on what the action intends to do:

Action family	Order tried
Click, DoubleClick, Hover, Check, Uncheck	button, link (exact names first), tab, menuitem, checkbox, radio, option, switch, label, test id, exact text, title, alt text, partial text
Fill, Press, Select, Clear, Focus, ReadValue, Upload, Expect_Value	label, placeholder, textbox (exact first), combobox, searchbox, spinbutton, checkbox, radio, test id, title
Expect_Visible, Expect_Text, Expect_Count, ReadInnerText	exact text, heading, button, link, label, placeholder, test id, partial text

Text that looks like a CSS selector (#save, .btn.primary, form > button, input[name=email]) is tried as CSS first, and text that looks like an XPath (//button) as XPath. A single word that could be an id is tried as id= last.

Two rules make automatic resolution predictable:

1. A strategy that matches exactly one element wins over a strategy that matches several.
2. If no strategy matches once, the first strategy with any matches is used with its first element, and the report says so: button=Save (first of 3 matches).

Paxter keeps probing for up to TargetResolveMilliseconds (default 5,000 ms) so that elements rendered after a navigation are still found. After that it falls back to the first strategy and lets the normal action timeout apply.

Prefer explicit prefixes in workflows you keep; use plain text while exploring a page. Explicit single strategies are passed straight to Playwright, including its strict-mode rule that a click must match exactly one element.

When Paxter cannot find an element

A failed step never fails silently. Paxter:

1. Saves a screenshot of the page at the moment of failure (resources/screenshot-N-failed.png), shown in the report next to the step.
2. Records the full Playwright error, including the action log.
3. Inspects the page and adds a What Paxter found section with practical hints:
   • several elements matched and how to disambiguate (;first, ;nth=, ;exact);
   • an element with that name exists but is hidden, collapsed, or zero-size;
   • an element with that name is disabled;
   • the page contains frames, which these actions do not reach;
   • the nearest matching elements on the page, each with a ready-to-paste target such as button=Sign in or testid=email-input.
4. Stops the workflow (or continues, when the step is marked Optional: true).

The same hints are printed in the console, so a failed CI run tells you what to change without opening the report.

Tips

• Take names from the page's accessibility tree (browser developer tools show it) rather than from the visual label; icons often have an aria-label.
• Use ;exact when a page has both "Save" and "Save and close".
• Use testid= when the team maintains data-testid attributes; they survive copy and layout changes.
• Use css= and xpath= last. They break most often when markup changes.
• Run paxter validate workflow.yaml after editing targets. It reports malformed prefixes (lable= becomes "Did you mean 'label='?") without launching a browser.