Skip to main content

PaxAction Commands

PaxAction commands are Playwright automation actions that enable web application testing and automation. These commands are used within YAML test scripts to interact with web elements and perform browser automation tasks.

Overview​

PaxAction commands provide comprehensive web automation capabilities including:

  • Navigation: Page navigation and URL handling
  • Element Interaction: Clicking, filling, and interacting with form elements
  • Text Operations: Finding and clicking text elements
  • Form Controls: Working with buttons, textboxes, comboboxes, and other form elements
  • File Operations: Uploading files and handling file inputs
  • Advanced Locators: Complex element selection and interaction

All PaxAction commands are designed to work with Playwright's robust element selection and interaction capabilities.

Page_GotoAsync​

Navigate to a specified URL.

Pattern: await page.GotoAsync("URL");

Usage:

- Do: Page_GotoAsync
  Data1: https://example.com

Description: Navigates the browser to the specified URL. This is typically the first command in a test sequence to load the target web application.

Goto​

Navigate to a URL (legacy JavaScript pattern).

Pattern: await page.goto('URL')

Usage:

- Do: Goto
  Data1: https://example.com

Description: Legacy navigation command using JavaScript Playwright syntax. Functionally equivalent to Page_GotoAsync.

WaitForUrl​

Wait for the page to navigate to a specific URL.

Pattern: await page.waitForURL('URL');

Usage:

- Do: WaitForUrl
  Data1: https://example.com/dashboard

Description: Waits for the page to navigate to the specified URL. Useful for waiting for redirects or navigation after form submissions.

Button Commands​

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 Commands​

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.

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.

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.

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.

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 Selection Commands​

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 Commands​

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.

Advanced Locator Commands​

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 Commands​

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 Commands​

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.

Utility Commands​

WaitFor5Seconds​

Wait for 5 seconds before proceeding.

Usage:

- Do: WaitFor5Seconds

Description: Pauses test execution for 5 seconds. Use sparingly and prefer specific wait conditions when possible.

DefineVariable​

Define a variable for use in subsequent commands.

Usage:

- Do: DefineVariable
  Data1: __optCode

Description: Defines a variable that can be referenced in later commands using the __variableName syntax.

ReadInnerText​

Read text content from an element and store it in a variable.

Usage:

- Do: ReadInnerText
  Data1: .confirmation-code
  Data2: __optCode
  Pipe: trim|reverse

Description: Reads the inner text of an element identified by a CSS selector and stores it in a variable. The Pipe parameter can apply text transformations.

Best Practices​

Element Selection Priority​

  1. Role-based selection: Use GetByRole* commands when possible as they rely on accessibility attributes
  2. Text-based selection: Use GetByText* for elements identified by visible text
  3. Label-based selection: Use GetByLabel* for form fields with clear labels
  4. Locator-based selection: Use GetLocator* or Locator* as a last resort for complex selections

Data Parameters​

  • Data1: Usually the element identifier (name, text, selector)
  • Data2: Usually the value to input or additional configuration
  • Data3: Additional parameters for complex operations
  • Pipe: Data transformation operations (e.g., trim, reverse, randomName)

Variable Usage​

  • Variables are defined with DefineVariable and referenced using __variableName syntax
  • Variables can store dynamic values like confirmation codes or generated data
  • Use variables to share data between test steps

Error Handling​

  • Commands will fail if elements are not found or not actionable
  • Use appropriate wait commands before interacting with dynamic elements
  • Prefer specific element selection over broad selectors

Performance Considerations​

  • Minimize use of WaitFor5Seconds - use specific wait conditions instead
  • Use exact text matching when dealing with similar text options
  • Combine actions when possible (e.g., GetLocator_Click_Fill instead of separate click and fill)