Smart Locators Node

The Smart Locators node allows you to automate interactions with web pages using Playwright's semantic locators — based on ARIA roles, labels, placeholders, and other accessibility attributes. This approach is more resilient than CSS selectors, as it reflects how users actually find elements on the page.

Tip: For new web flows recorded by the extension, prefer Smart Web Flow. If you prefer traditional CSS selectors and XPath in legacy flows, use the Web Flow node.

Overview

General Configuration

Identical to the Web Flow node:

The Browser & Device options are identical to the Web Flow node — see the Web Flow documentation for details on viewport presets and available mobile devices.

Performance Audit

When Performance Audit is enabled, Smart Locators monitors the active Playwright session and generates visual performance evidence per screen.

The feature collects:

• Page Load
• FCP (First Contentful Paint)
• LCP (Largest Contentful Paint)
• total request count
• API request count
• request/API errors
• slow APIs per screen

In addition to the global summary, QANode generates per-screen checkpoints with:

• screen name
• URL
• step that originated the navigation
• chart of slowest APIs
• separate API error chart when errors exist on that screen

Performance Outputs

When the audit is enabled, the node exposes:

• performancePassed
• performanceRequestCount
• performanceApiRequestCount
• performanceErrorCount
• performanceSlowRequestCount
• performance

The performance object contains a structured summary of the execution, including per-screen checkpoints.

Self Healing

When Self Healing is enabled, Smart Locators can automatically recover semantic locator actions when the original locator no longer finds the expected element.

In addition to the semantic locator itself, the engine considers:

• element text and accessible name
• role
• label, placeholder, title, and other relevant attributes
• structural page context such as container, form, heading, and relative position

This helps in scenarios such as:

• text changes with the same meaning
• uppercase/lowercase changes
• text with or without accents
• short variations such as Login → Sign In or Next → Continue

The feature is conservative: it only applies recovery when it finds a candidate clearly stronger than the others, avoiding guesses on ambiguous screens.

When a step is recovered, the execution shows:

• the affected step
• the recovery confidence
• the locator used
• an Apply to Flow option to update the flow with the recovered locator

Locator System

Location Methods

Instead of CSS selectors, Smart Locators uses Playwright's semantic methods:

Locator Configuration

Available ARIA Roles

For the getByRole method, the following roles are available:

Usage example:

Method: getByRole
Value: button
Name: Sign In

Equivalent in Playwright: page.getByRole('button', { name: 'Sign In' })

Available Actions

Action Details

navigate

Navigates to a URL.

switchPage

Switches the active page when a click, link, or action opens a new tab/window and the next steps must continue there.

Modes:

When the extension identifies links that open a new tab, it can insert this step automatically. In manual flows, add switchPage after the click that opens the tab.

click

Clicks on a semantically located element.

The click waits for the element to be visible, scrolls to it if necessary, and then clicks. If it fails, it retries.

Example:

Method: getByRole
Value: button
Name: Submit
Retries: 3

dblclick

Double-clicks on an element.

fill

Fills an input field instantly (replaces the value).

Uses Playwright's locator.fill() — ideal for simple fields.

type

Types text character by character, simulating real typing.

Uses Playwright's locator.pressSequentially() — ideal for fields with:

• Autocomplete (suggestions appear as you type)
• Input masks (phone numbers, zip codes)
• On-keypress validation (validates each key)

Example:

Locator: getByPlaceholder → "Phone"
Text: 123.456.789-00
Delay: 100ms

check / uncheck

Checks or unchecks a checkbox/radio button.

Example:

Method: getByLabel
Value: I accept the terms of use

selectOption

Selects an option from a dropdown (<select>).

hover

Hovers the mouse over an element.

focus

Sets focus on an element.

press

Presses a keyboard key in the context of an element.

drag

Drags a semantically located element and drops it on another locator or at recorded coordinates.

Smart Locators tries to use Playwright semantic locators such as getByRole, getByText, getByLabel, and getByTestId. When a page has repeated elements and the step comes from the extension, the JSON may include internal position metadata to help the executor choose the element closest to the original gesture. These metadata fields are not shown as primary fields in the panel.

For drag/drop components, QANode also tries to promote the semantic locator to the real interactive container. This is useful when the clicked text is inside another draggable element, for example:

• A <p> inside a draggable card
• An image inside a draggable container
• A drop area marked by class or drop attributes

If the semantic target is too generic or fails, but Drop X / Y is available, Smart Locators can use the recorded coordinates as fallback. This allows automation of canvas, Kanban, and drop areas that do not have their own text, role, or label.

Best practices:

• Prefer components with accessible names (aria-label, visible text, labels)
• Use data-testid or data-qa for critical cards, columns, and drop areas
• Avoid icon-only buttons without aria-label
• Review recordings that depend on nth, especially when there are repeated texts
• Use before and after screenshots to visually prove the movement

assert

Verifies conditions on the page. Offers multiple verification modes:

Assert Modes:

Examples:

// Verify that the "Submit" button is visible
Mode: visible, Locator: getByRole("button", "Submit")

// Verify that message contains "Success"
Mode: textContains, Locator: getByText("Success"), Expected: "Success"

// Verify URL after login
Mode: hasURL, Expected: "/dashboard"

// Verify that field is disabled
Mode: disabled, Locator: getByLabel("Email")

extract

Extracts data from an element.

Available attributes:

extractList

Iterates over a list of repeated elements (table rows, cards, list items) and extracts named fields from each, producing an array of objects as output.

Fields configuration:

Output example:

{
  "extracts": {
    "products": [
      { "name": "Item A", "price": "$10.00" },
      { "name": "Item B", "price": "$25.00" }
    ]
  }
}

Recording with the extension: Use Ctrl+Shift+E in the Chrome Recorder to record a list extraction in two steps: first click the repeating item, then click the fields to extract within it.

wait

Waits for a condition.

scroll

Scrolls the page.

refresh

Reloads the page. Same configuration as Web Flow.

clock

Controls the browser clock using Playwright's page.clock. This is the same action available in Web Flow and can be used to validate date/time behavior without depending on the machine's real clock.

New clock steps start with reload disabled. Enable reload only when the application depends on page load to recalculate dates or times.

frame

Switches to an iframe. Supports name and main modes (return to main context).

Evidence (Screenshots per Step)

Identical to Web Flow — each step can have individual screenshot capture configuration.

Accessibility Testing

Smart Locators supports automatic accessibility scanning with built-in axe-core. When enabled, the node audits the page after each step that captures a screenshot, identifying WCAG/ARIA violations and visually marking the affected elements.

Smart Locators already uses semantic locators based on ARIA roles — combining it with accessibility scanning is especially useful for verifying that the elements you interact with pass accessibility criteria.

Configuration

How It Works

After each step that takes a screenshot, axe-core is injected into the page and scans the document for violations. Violations are drawn over the screenshot as colored boxes around the affected elements, plus a summary panel in the corner:

At the end of execution, the following are generated automatically:

• Per-step screenshots — overlay with colored boxes + panel Critical N / Serious N / Moderate N / Minor N + top 2 rules
• Severity chart — {id}-accessibility-severity-chart.png — distribution by level
• Rules chart — {id}-accessibility-rule-chart.png — top 8 most violated rules
• JSON report — {id}-accessibility-report.json — full data for all violations

Pass/Fail Criteria

The node fails if there is any violation with severity equal to or above the configured threshold. Use none to never fail (collect metrics without blocking the flow).

Example: Verify login form accessibility

Node configuration:
  Accessibility Scan: true
  Fail When Severity >= : serious

Steps:
1. navigate → https://mysite.com/login            (no screenshot = no scan)
2. fill → getByLabel("Email") → "..."              → screenshot after → scan executed
3. fill → getByLabel("Password") → "..."           → screenshot after → scan executed
4. click → getByRole("button", { name: "Sign In" }) → screenshot after → scan executed
5. wait → networkIdle
6. assert → "loginOk" → textContains → getByText("Welcome") → screenshot → scan executed

If any step has a serious or critical violation, the node fails with:

"Accessibility findings at or above "serious" were detected."

Outputs

Complete Example: Login with Smart Locators

Step 1: navigate → https://mysite.com/login
Step 2: fill → getByLabel("Email") → "{{ variables.EMAIL }}"
Step 3: fill → getByLabel("Password") → "{{ variables.PASSWORD }}"
Step 4: click → getByRole("button", { name: "Sign In" })
Step 5: wait → networkIdle
Step 6: assert → "loginOk" → textContains → getByText("Welcome")
Step 7: extract → "userName" → getByRole("heading") → text

When to Use Smart Locators vs Web Flow

Tips

• Prefer getByRole — it is the most resilient and reflects how assistive technologies find elements
• Use getByLabel for form fields — it is more stable than CSS
• getByTestId is great for elements without a clear role/label
• Use the type action (instead of fill) for fields with masks or autocomplete
• The Nth field allows you to select a specific element when multiple ones match the locator