Workflow actions

Every step in a workflow names an action in Do:. Paxter has three families:

Generic actions take a target expression and do one thing: Click, Fill, Select, Check, Press, Upload, and so on. Use these in new workflows.
Assertions (Expect_*) wait for the page to reach a state and fail the step if it does not. They are what turn a click-through into a regression test.
Playwright-style actions (GetByRoleButton_ByName_Click, Locator_Fill, and the rest) mirror recorded Playwright code. They are fully supported for existing and converted workflows and documented further down.

Run paxter actions for the same list in the terminal, including the plain-English aliases (Should see, Expect text, Double click).

Fields

Field	Alias of	Meaning
`Target`	`Data1`	Element target such as `button=Save`, `label=Email`, `css=#total`, or plain text.
`Value`	`Data2`	Text to enter, option to select, expected text or value, count, file paths, or a `__variable` name.
`Key`	`Data2`	Key or chord to press, for example `Enter`, `Tab`, `Control+a`.
`Mode`	`Data3`	Comparison mode for assertions: `contains`, `exact`, or `regex`.
`Name`	—	Readable step label for the console and report.
`Pipe`	—	Text transformation (`trim`, `upper`, `lower`, `capitalize`, `reverse`, `randomName`, `substr:start,length`, joined with `
`Secret`	—	`true` masks the value in all evidence.
`Optional`	—	`true` turns a failure into a warning and continues.

Placeholders such as {{Column}}, {{env:NAME}}, {{__variable}}, and {{today}} work in every field; quote values that start with {{. See data-driven testing.

Generic actions

Do	Fields	What it does
`Click`	`Target`	Clicks the element.
`DoubleClick`	`Target`	Double-clicks the element.
`Hover`	`Target`	Moves the pointer over the element, for example to open a menu.
`Focus`	`Target`	Gives keyboard focus to the element.
`Fill`	`Target`, `Value`	Replaces the content of an input, textarea, or contenteditable. `Pipe` is applied to the value.
`Clear`	`Target`	Empties an input.
`Press`	`Target`, `Key`	Presses a key or chord on the element.
`Check`	`Target`	Ticks a checkbox or selects a radio button (no-op when already checked).
`Uncheck`	`Target`	Unticks a checkbox.
`Select`	`Target`, `Value`	Chooses an option of a native `<select>` by visible label or by value.
`Upload`	`Target`, `Value`	Sets one or more files on a file input. Separate paths with commas; relative paths resolve from the workflow file.
`ReadInnerText`	`Target`, `Data2`: `__name`	Stores the element's text in a variable. `Pipe` is applied.
`ReadValue`	`Target`, `Data2`: `__name`	Stores an input's current value in a variable. `Pipe` is applied.
`DefineVariable`	`Data1`: `__name`	Declares or clears a variable.

- Do: Fill
  Name: Enter the delivery postcode
  Target: label=Postcode || placeholder=e.g. 2000
  Value: "{{Postcode}}"
- Do: Select
  Target: label=Delivery speed
  Value: Express
- Do: Upload
  Target: css=input[type=file]
  Value: fixtures/id-card.png
- Do: Click
  Target: button=Continue

Assertions

Assertions retry until the condition holds or ExpectTimeoutMilliseconds (default 5,000) elapses, so they double as targeted waits. Prefer them over fixed pauses.

Do	Fields	Passes when
`Expect_Visible`	`Target`	The element is visible.
`Expect_Hidden`	`Target`	The element is hidden or not present.
`Expect_Text`	`Target`, `Value`, `Mode`	The element's text matches. Default mode `contains`.
`Expect_Value`	`Target`, `Value`, `Mode`	The input's value matches. Default mode `exact`.
`Expect_Enabled`	`Target`	The element is enabled.
`Expect_Disabled`	`Target`	The element is disabled.
`Expect_Checked`	`Target`	The checkbox or radio is checked.
`Expect_Unchecked`	`Target`	The checkbox or radio is unchecked.
`Expect_Count`	`Target`, `Value`	Exactly that many elements match the target.
`Expect_Url`	`Data1`, `Data2`: mode	The page URL matches. Default mode `contains`.
`Expect_Title`	`Data1`, `Data2`: mode	The page title matches. Default mode `contains`.
`Expect_Equals`	`Data1`, `Data2`, `Data3`: mode	Two resolved values match, for example `{{__reference}}` and `{{ExpectedReference}}`. Default mode `exact`.

Modes: contains (substring), exact (whole text after whitespace normalisation), regex (a .NET regular expression).

- Do: Expect_Visible
  Target: heading=Order confirmed
- Do: Expect_Text
  Target: css=.order-total
  Value: "{{ExpectedTotal}}"
  Mode: exact
- Do: Expect_Url
  Data1: /orders/
- Do: Expect_Count
  Target: css=table tbody tr
  Value: 3
- Do: Expect_Text
  Target: role=alert
  Value: ^Order [A-Z]{2}-\d{6} placed$
  Mode: regex

Do	Fields	What it does
`Page_GotoAsync`	`Data1`: absolute URL	Navigates to the URL.
`Goto`	`Data1`: URL	Legacy alias for `Page_GotoAsync`.
`WaitForUrl`	`Data1`: URL or glob	Waits until the URL matches. `Expect_Url` is usually clearer.
`WaitForSeconds`	`Data1`: seconds (1 to 120)	Pauses. Use only when no assertion can express the wait.
`WaitFor5Seconds`	—	Pauses five seconds. Validation warns about it.

Playwright-style actions

The actions below mirror recorded Playwright statements and are what paxter convert produces. They behave exactly as before; each entry notes the generic action that replaces it in new workflows.

Button actions

GetByRoleButton_ByName_Click

Click a button by its accessible name.

Pattern: await page.GetByRole(AriaRole.Button, new() { Name = "ButtonName" }).ClickAsync();

Usage:

- Do: GetByRoleButton_ByName_Click
  Data1: Submit

Description: Clicks a button element identified by its accessible name. This is the most reliable way to interact with buttons as it uses accessibility attributes.

Examples:

Login buttons: Data1: Log in
Submit buttons: Data1: Submit
Action buttons: Data1: Save & continue

GetByRoleButton_Click

Click a button (legacy pattern).

Pattern: await page.getByRole('button', { name: 'ButtonName' }).click();

Usage:

- Do: GetByRoleButton_Click
  Data1: Cancel

Description: Legacy button click command using JavaScript syntax. Functionally equivalent to GetByRoleButton_ByName_Click.

GetByRoleButton_SetInputFiles

Upload files through a button element.

Pattern: await page.GetByRole(AriaRole.Button, new() { Name = "ButtonName" }).SetInputFilesAsync(new[] { FilePath });

Usage:

- Do: GetByRoleButton_SetInputFiles
  Data1: Upload File
  Data2: path/to/file.pdf

Description: Uploads files through a button that triggers a file picker. Data2 can contain multiple file paths separated by commas.

Text input actions

GetByRoleTextbox_Fill

Fill a textbox with specified text.

Pattern: await page.GetByRole(AriaRole.Textbox, new() { Name = "FieldName" }).FillAsync("Value");

Usage:

- Do: GetByRoleTextbox_Fill
  Data1: Email *
  Data2: user@example.com

Description: Fills a text input field identified by its accessible name. This clears the field first, then enters the new text.

Examples:

Email fields: Data1: Email, Data2: user@domain.com
Password fields: Data1: Password, Data2: secretpassword
Text areas: Data1: Comments, Data2: Sample comment text

GetByRoleTextbox_Click

Click on a textbox to focus it.

Pattern: await page.GetByRole(AriaRole.Textbox, new() { Name = "FieldName" }).ClickAsync();

Usage:

- Do: GetByRoleTextbox_Click
  Data1: Search

Description: Clicks on a textbox to give it focus. Useful for dropdown textboxes or fields that need to be activated before filling.

GetByRoleTextbox_Press

Press a key while focused on a textbox.

Pattern: await page.GetByRole(AriaRole.Textbox, new() { Name = "FieldName" }).PressAsync("Key");

Usage:

- Do: GetByRoleTextbox_Press
  Data1: Search
  Data2: Enter

Description: Presses a keyboard key while the textbox has focus. Common keys include Enter, Tab, Escape, or ArrowDown.

GetByLabel_Fill

Fill a form field identified by its label.

Pattern: await page.getByLabel('LabelText').fill('Value');

Usage:

- Do: GetByLabel_Fill
  Data1: Username
  Data2: myusername

Description: Fills a form field by finding it through its associated label element. Alternative to textbox role-based selection.

GetByLabel_Press

Press a key on a field identified by its label.

Pattern: await page.getByLabel('LabelText').press('Key');

Usage:

- Do: GetByLabel_Press
  Data1: Search
  Data2: Enter

Description: Presses a keyboard key on a form field identified by its label.

Link actions

GetByRoleLink_ByName_Click

Click a link by its accessible name.

Pattern: await page.GetByRole(AriaRole.Link, new() { Name = "LinkText" }).ClickAsync();

Usage:

- Do: GetByRoleLink_ByName_Click
  Data1: Log in

Description: Clicks a link identified by its accessible name or text content. This is the primary method for link interaction.

GetByRoleLink_Exact_Click

Click a link with exact text matching.

Pattern: await page.GetByRole(AriaRole.Link, new() { Name = "LinkText", Exact = true }).ClickAsync();

Usage:

- Do: GetByRoleLink_Exact_Click
  Data1: Home

Description: Clicks a link with exact text matching. Use this when you need precise text matching to avoid partial matches.

GetByRoleLink_Nth_Click

Click the nth occurrence of a link with specific text.

Pattern: await page.GetByRole(AriaRole.Link, new() { Name = "LinkText" }).Nth(Index).ClickAsync();

Usage:

- Do: GetByRoleLink_Nth_Click
  Data1: Submit application
  Data2: 1

Description: Clicks the nth occurrence (0-based index) of a link when multiple links have the same text. Data2 specifies the index.

GetByRoleLink_Click

Click a link (legacy pattern).

Pattern: await page.getByRole('link', { name: 'LinkText' }).click();

Usage:

- Do: GetByRoleLink_Click
  Data1: Dashboard

Description: Legacy link click command using JavaScript syntax.

Text actions

GetByText_Generic_Click

Click an element containing specific text.

Pattern: await page.GetByText("Text").ClickAsync();

Usage:

- Do: GetByText_Generic_Click
  Data1: I agree to the terms

Description: Clicks any element containing the specified text. Useful for checkboxes with text labels, custom buttons, or clickable text elements.

GetByText_Exact_Click

Click an element with exact text matching.

Pattern: await page.GetByText("Text", new() { Exact = true }).ClickAsync();

Usage:

- Do: GetByText_Exact_Click
  Data1: Submit

Description: Clicks an element with exact text matching. Use this to avoid partial text matches.

GetByText_ExactTrue_Click

Click an element with exact text matching (alternative pattern).

Pattern: await page.GetByText("Text", new() { Exact = true }).ClickAsync();

Usage:

- Do: GetByText_ExactTrue_Click
  Data1: Continue

Description: Alternative exact text matching command. Functionally equivalent to GetByText_Exact_Click.

GetByText_Click

Click text element (legacy pattern).

Pattern: await page.getByText('Text').click();

Usage:

- Do: GetByText_Click
  Data1: Select this option

Description: Legacy text click command using JavaScript syntax.

Form control actions

GetByRoleCombobox_Click

Click a combobox (dropdown) to open it.

Pattern: await page.GetByRole(AriaRole.Combobox, new() { Name = "FieldName" }).ClickAsync();

Usage:

- Do: GetByRoleCombobox_Click
  Data1: Country

Description: Clicks a combobox/dropdown to open the options list. Used before selecting an option.

GetByRoleCombobox_Press

Press a key on a combobox.

Pattern: await page.GetByRole(AriaRole.Combobox, new() { Name = "FieldName" }).PressAsync("Key");

Usage:

- Do: GetByRoleCombobox_Press
  Data1: Country
  Data2: ArrowDown

Description: Presses a keyboard key on a combobox. Useful for keyboard navigation through options.

GetByRoleCombobox_LocatorSpanNth_Click

Click a specific span element within a combobox.

Pattern: await page.GetByRole(AriaRole.Combobox, new() { Name = "FieldName" }).Locator("span").Nth(Index).ClickAsync();

Usage:

- Do: GetByRoleCombobox_LocatorSpanNth_Click
  Data1: Language
  Data2: 2

Description: Clicks the nth span element within a combobox. Used for complex dropdown controls with multiple clickable areas.

GetByRoleCombobox_LocatorId_Click

Click an element by ID within a combobox.

Pattern: await page.GetByRole(AriaRole.Combobox, new() { Name = "FieldName" }).Locator("#ElementId").ClickAsync();

Usage:

- Do: GetByRoleCombobox_LocatorId_Click
  Data1: Category
  Data2: option-1

Description: Clicks an element by its ID within a combobox container.

GetByRoleOption_Click

Click an option within a dropdown or combobox.

Pattern: await page.GetByRole(AriaRole.Option, new() { Name = "OptionText" }).ClickAsync();

Usage:

- Do: GetByRoleOption_Click
  Data1: United States

Description: Clicks an option in an opened dropdown or combobox. Use this after opening the dropdown with a click action.

GetByRoleSearchbox_Fill

Fill a search box with text.

Pattern: await page.GetByRole(AriaRole.Searchbox, new() { Name = "FieldName" }).FillAsync("SearchText");

Usage:

- Do: GetByRoleSearchbox_Fill
  Data1: Search address
  Data2: 123 Main Street

Description: Fills a search input field. Often used for autocomplete or filtered search functionality.

GetByRoleSpinbutton_Click

Click a spinbutton (numeric input) field.

Pattern: await page.GetByRole(AriaRole.Spinbutton, new() { Name = "FieldName" }).ClickAsync();

Usage:

- Do: GetByRoleSpinbutton_Click
  Data1: Quantity

Description: Clicks a numeric input field (spinbutton) to focus it.

GetByRoleSpinbutton_Fill

Fill a spinbutton field with a numeric value.

Pattern: await page.GetByRole(AriaRole.Spinbutton, new() { Name = "FieldName" }).FillAsync("Value");

Usage:

- Do: GetByRoleSpinbutton_Fill
  Data1: Age
  Data2: 25

Description: Fills a numeric input field with a value. Can also reference variables using the __variableName syntax.

Locator actions

GetLocator_Click

Click an element using a CSS selector or locator.

Pattern: await Page.Locator(Selector).ClickAsync();

Usage:

- Do: GetLocator_Click
  Data1: "#submit-button"

Description: Clicks an element identified by a CSS selector, XPath, or other locator strategy. Use for elements that can't be easily identified by role or text.

GetLocator_LinkByRole_Click

Click a link within a specific container using role-based selection.

Pattern: await Page.Locator(ContainerSelector).GetByRole(AriaRole.Link, new () { Name = LinkName }).ClickAsync();

Usage:

- Do: GetLocator_LinkByRole_Click
  Data1: .navigation-menu
  Data2: "About Us"

Description: Finds a link by its role and name within a specific container element.

Locator_Press

Press a key on an element identified by a locator.

Pattern: await page.Locator("Selector").PressAsync("Key");

Usage:

- Do: Locator_Press
  Data1: body
  Data2: Tab

Description: Presses a keyboard key on an element identified by a CSS selector. Commonly used for global key presses or element-specific key events.

GetByRoleGroup_LocatorI_First_Click

Click the first <i> element within a group.

Pattern: await page.GetByRole(AriaRole.Group, new() { Name = "GroupName" }).Locator("i").First.ClickAsync();

Usage:

- Do: GetByRoleGroup_LocatorI_First_Click
  Data1: Date picker

Description: Clicks the first <i> (icon) element within a named group. Often used for calendar icons, dropdown arrows, or other interface icons.

File upload actions

UploadFile

Upload a file through a file input element.

Usage:

- Do: UploadFile
  Data1: Photo
  Data2: sample-image.png

Description: Uploads a file through a file input element identified by its ID (Data1). The file path is specified in Data2.

Note: The file should be available in the test environment's file system.

Custom form actions

GetLocator_Click_Fill

Click on a form field and then fill it with text.

Usage:

- Do: GetLocator_Click_Fill
  Data1: FirstName
  Data2: John
  Pipe: randomName

Description: Clicks on a form field to focus it, then fills it with the specified text. The Pipe parameter can specify data transformations like randomName.

SelectLabelOption

Select an option from a dropdown by label.

Usage:

- Do: SelectLabelOption
  Data1: Country
  Data2: United States

Description: Selects an option from a dropdown or select element identified by its label.

SelectTextForOption

Select an option from a dropdown with additional parameters.

Usage:

- Do: SelectTextForOption
  Data1: Select residency status
  Data2: Australian or New Zealand
  Data3: 0

Description: Advanced option selection with additional configuration parameters.

Checkbox_Click

Click a checkbox element.

Usage:

- Do: Checkbox_Click
  Data1: HasDisability_False

Description: Clicks a checkbox element identified by its name or ID.

SelectByValue

Select an option by its value attribute.

Usage:

- Do: SelectByValue
  Data1: country-select
  Data2: US

Description: Selects an option from a select element by matching the option's value attribute.

SelectByOption

Select an option by its text content.

Usage:

- Do: SelectByOption
  Data1: language-select
  Data2: English

Description: Selects an option from a select element by matching the option's visible text.

ForceButtonClick

Force click a button element (bypasses normal click validation).

Usage:

- Do: ForceButtonClick
  Data1: uploadPhotoButton

Description: Forces a click on a button element, bypassing Playwright's normal actionability checks. Use when normal clicks fail due to element state.

Best practices

Choosing a target

Role and name (button=Save, link=Details): stable across restyling and matches what users perceive.
Label or placeholder (label=Email): best for form fields.
Test id (testid=submit): stable when the team maintains data-testid attributes.
Visible text (text=Order confirmed): good for assertions, weaker for actions on repeated text.
CSS or XPath: last resort; add a fallback chain so a redesign does not break the step.

Writing reliable workflows

Follow every action that changes the page with an Expect_* assertion.
Replace WaitFor5Seconds with Expect_Visible or Expect_Text on the element you are waiting for.
Use ;exact when similar names exist, and ;first or ;nth=N only after confirming the page repeats the element.
Keep secrets in {{env:NAME}} placeholders with Secret: true.
Put repeated scenarios in a data file and reference columns with {{Column}}.
Run paxter validate after editing; it catches typos in action names, targets, and placeholders before a browser opens.

When a step fails

The console and report show the error together with What Paxter found: ambiguous matches, hidden or disabled elements, frames, and the nearest elements on the page with ready-to-paste targets. Start from those hints. See Targets for details.

Fields​

Generic actions​

Assertions​

Navigation and waits​

Playwright-style actions​

Button actions​

GetByRoleButton_ByName_Click​

GetByRoleButton_Click​

GetByRoleButton_SetInputFiles​

Text input actions​

GetByRoleTextbox_Fill​

GetByRoleTextbox_Click​

GetByRoleTextbox_Press​

GetByLabel_Fill​

GetByLabel_Press​

Link actions​

GetByRoleLink_ByName_Click​

GetByRoleLink_Exact_Click​

GetByRoleLink_Nth_Click​

GetByRoleLink_Click​

Text actions​

GetByText_Generic_Click​

GetByText_Exact_Click​

GetByText_ExactTrue_Click​

GetByText_Click​

Form control actions​

GetByRoleCombobox_Click​

GetByRoleCombobox_Press​

GetByRoleCombobox_LocatorSpanNth_Click​

GetByRoleCombobox_LocatorId_Click​

GetByRoleOption_Click​

GetByRoleSearchbox_Fill​

GetByRoleSpinbutton_Click​

GetByRoleSpinbutton_Fill​

Locator actions​

GetLocator_Click​

GetLocator_LinkByRole_Click​

Locator_Press​

GetByRoleGroup_LocatorI_First_Click​

File upload actions​

UploadFile​

Custom form actions​

GetLocator_Click_Fill​

SelectLabelOption​

SelectTextForOption​

Checkbox_Click​

SelectByValue​

SelectByOption​

ForceButtonClick​

Best practices​

Choosing a target​

Writing reliable workflows​

When a step fails​

Fields

Generic actions

Assertions

Navigation and waits

Playwright-style actions

Button actions

GetByRoleButton_ByName_Click

GetByRoleButton_Click

GetByRoleButton_SetInputFiles

Text input actions

GetByRoleTextbox_Fill

GetByRoleTextbox_Click

GetByRoleTextbox_Press

GetByLabel_Fill

GetByLabel_Press

Link actions

GetByRoleLink_ByName_Click

GetByRoleLink_Exact_Click

GetByRoleLink_Nth_Click

GetByRoleLink_Click

Text actions

GetByText_Generic_Click

GetByText_Exact_Click

GetByText_ExactTrue_Click

GetByText_Click

Form control actions

GetByRoleCombobox_Click

GetByRoleCombobox_Press

GetByRoleCombobox_LocatorSpanNth_Click

GetByRoleCombobox_LocatorId_Click

GetByRoleOption_Click

GetByRoleSearchbox_Fill

GetByRoleSpinbutton_Click

GetByRoleSpinbutton_Fill

Locator actions

GetLocator_Click

GetLocator_LinkByRole_Click

Locator_Press

GetByRoleGroup_LocatorI_First_Click

File upload actions

UploadFile

Custom form actions

GetLocator_Click_Fill

SelectLabelOption

SelectTextForOption

Checkbox_Click

SelectByValue

SelectByOption

ForceButtonClick

Best practices

Choosing a target

Writing reliable workflows

When a step fails