Selectors Guide

Advanced

Master element selection for reliable automations

Overview

Selectors are how your automation finds elements on a web page. A good selector is specific enough to find the right element but flexible enough to work even when the page changes slightly.

Using the Selector Picker

Smart Selector Picker

The easiest way to create selectors is using the Selector Picker:

Click the target icon next to any selector field
A browser window opens with your page
Click on any element to select it
The picker generates multiple selector options, ranked by reliability
Choose the best selector or let auto-fallback try them in order

Selector Types

CSS Selectors

Standard CSS selectors work in Prompteryx:

#login-button

ID selector - very reliable if ID is unique

.submit-btn

Class selector - good for styled elements

button[type="submit"]

Attribute selector - matches by attribute

.form input:first-child

Combination - for complex targeting

Playwright Locators (Recommended)

Playwright locators are more reliable because they find elements by their purpose, not just structure:

getByRole("button", { name: "Submit" })

Finds by ARIA role and accessible name - most reliable

getByLabel("Email address")

Finds input by its label text

getByText("Sign up")

Finds element containing exact text

getByPlaceholder("Enter your email")

Finds input by placeholder text

getByTestId("submit-button")

Finds by data-testid attribute - dev-friendly

XPath Selectors

XPath is powerful but more fragile. Use when CSS and Playwright locators don't work:

//button[@class="submit"]//div[contains(text(), "Welcome")]//input[@name="email"]/../following-sibling::button

Auto-Fallback

When you use the Selector Picker, it generates multiple selectors ranked by reliability. When it finds more than one, an Auto-fallback checkbox appears under the selector field (on by default): if the selected selector fails, Prompteryx automatically tries the other options in order.

How the picker ranks selectors (most reliable first):

Test ID (getByTestId) - when the page provides one
Role and accessible name (getByRole)
Placeholder (getByPlaceholder) and label (getByLabel) - for form inputs
Alt text and visible text (getByText) - for images, buttons and links
Title attribute
CSS ID, then other CSS selectors - last resort

Which steps use backup selectors and the AI fallback

The same on every run: in the cloud, on a schedule, and on your own computer with Prompteryx Desktop.

StepBackup selectorsAI Agent FallbackClick Element, Double Click, Right Click, HoverYesYesFill InputYesYes (types the text)Check, Uncheck, Select Option, FocusYesYesScroll Into ViewYesYes (scrolls, never clicks)Extract TextYesYes (the AI reads the text)BlurYesNoEvery other step with a selectorNoNo

Order: the selected selector first, then your other selectors in list order, then the AI (only if you ticked AI Agent Fallback). Steps that don't use them don't show the controls.
Timing: the selected selector gets up to 15 seconds to appear (slow pages), each backup 2 seconds. A broken selector no longer holds a step for its whole 30-second timeout.
Extract Text: an element that is there but empty counts as a miss, so the next selector (or the AI) gets a try. With the AI fallback, the AI reads the text off the page and does not click or type; if it can't find it, the step fails instead of saving a guess.
Run history: each step's output says what did the work ( selectorUsed: "Primary selector", "Backup selector #2 of 3" or "AI fallback (3 steps, 6 credits)"), lists every selector tried in selectorAttempts, and the Execution Logs show each fall-through as it happens.

What the Selector Picker Generates

The Selector Picker generates Playwright-style locators that find elements based on what's visible on the page — text content, accessible roles, labels, and links. This follows Playwright's official best practices for creating reliable selectors.

Example: Clicking a Link on Hacker News

If you click the top story title on Hacker News, the picker might generate:

getByRole("link", { name: "Show HN: My Cool Project" })

Matches the link by its current visible text

Content-Based vs Structure-Based

This selector works perfectly right now, but if the top story changes tomorrow, the selector will fail because the text no longer matches. This is called a content-based selector — it targets what an element says, not where it sits on the page.

Content-based selectors are ideal for elements with stable text — buttons that always say "Submit", navigation links that always say "Home", or form labels that don't change. For elements where the content changes (news feeds, search results, product listings), you may need a different approach.

Selectors for Dynamic Content

When you need to target elements whose content changes — like "the first item in a list" or "the footer of a page" — you need structural selectors that target an element's position or CSS class rather than its text. The Selector Picker doesn't generate these automatically, but there are several easy ways to create them.

Method 1: Pick, Then Edit

Easiest approach — start with the picker, then simplify

Use the Selector Picker to click the element you want. This confirms you're targeting the right thing.
Look at the generated selector in the Element Selector field. Note what type of element it found (a link, a heading, a div, etc.).
Replace the content-specific selector with a structural CSS selector. For example:

Before:getByRole("link", { name: "Show HN: My Cool Project" })

After:tr.athing:first-of-type .titleline

The edited selector targets "the title area of the first story row" — no matter what the story text says.

Method 2: Use Browser Inspect

Look at the page structure to find stable class names

Open the target website in your browser and right-click the element you want to target, then select "Inspect" (or press F12).
The Developer Tools will highlight the element in the HTML. Look for:
- Class names that describe the element's purpose (e.g. .titleline, .nav-footer, .product-card)
- ID attributes (e.g. #main-content) — these are unique on the page
- Data attributes (e.g. data-item="1") — often stable and meaningful
Build a selector using those stable attributes. Combine a parent's class with a child element to be specific:

.product-list .product-card:first-of-type

First product card in the product list

footer .footer-links

Links section inside the page footer

table tbody tr:nth-child(1) td.name

Name column of the first row in a table

Method 3: Ask an AI Assistant

Let AI generate the selector for you from the page's HTML

If you're not comfortable reading HTML, you can share the page's code with an AI assistant (like ChatGPT or Claude) and ask it to write a selector for you:

Open the target website, right-click the area you're interested in, and select "Inspect".
In the Developer Tools, right-click the highlighted HTML element and choose "Copy" → "Copy outer HTML" (or copy a larger section of the HTML around it).
Paste the HTML into an AI assistant and ask something like:

"Here is the HTML of a news page. I need a CSS selector that always picks the first story title, even when the stories change. The selector should not depend on any specific story text."

"Here is the HTML of a product listing page. Give me a CSS selector for the price of the first product in the grid. It should work no matter which products are shown."

The AI will analyze the HTML structure and return a structural CSS selector that targets position and class names rather than specific text content. Paste the result into the Element Selector field in Prompteryx.

Common Structural Selector Patterns

.list-item:first-of-typeFirst item in a list.list-item:last-of-typeLast item in a list.list-item:nth-of-type(3)Third item in a listtable tr:first-child tdCells in the first table rownav a[href="/about"]Link by its URL (stable)footerPage footer element[data-testid="search-input"]Element with a test ID attribute

When to Use Which Type

Selector Picker (Playwright locators) — Best for buttons, form fields, navigation links, and any element with stable, unchanging text.
Structural CSS selectors — Best for dynamic content like news feeds, search results, product listings, or "the first/last item" in any list.
AI Agent Fallback (Last Resort) — Tick this checkbox under a selector field as a safety net. If all selectors fail, the AI agent tries to find the element visually. It uses AI credits only when it runs.

When Selectors Fail

Common Causes

Page hasn't fully loaded - add Wait for Element
Element is in an iframe - use Frame handling
Element is behind a modal/overlay - close it first
Dynamic IDs/classes that change each load
Element doesn't exist on this page state

Use Prompteryx Browser Agent

When traditional selectors just won't work reliably - especially on complex, dynamic pages - the Prompteryx Browser Agent can use AI vision to find and interact with elements. It can handle situations where selectors fail because it "sees" the page like a human would.Learn about AI-powered automation →

Best Practices

Prefer Role and Label Selectors

getByRole and getByLabel are the most reliable because they match how users perceive elements, not how they're coded. They survive UI redesigns better than CSS selectors.

Keep Auto-Fallback On

Auto-fallback is on by default and makes your automation self-healing. If the primary selector breaks, it automatically tries alternatives without stopping the workflow.

Use Positional Selectors Carefully

Selectors like :first-of-type and :last-of-type are reliable for targeting "the first item" or "the last item" in a list. Specific indexes like :nth-child(7) are more fragile because the number of items may change. Prefer first/last over specific numbers when possible.

Test Across Page States

Test your selectors when the page is in different states (logged in/out, different data, etc.) to ensure they work consistently.

Selectors Guide

Advanced

Master element selection for reliable automations

Overview

Selectors are how your automation finds elements on a web page. A good selector is specific enough to find the right element but flexible enough to work even when the page changes slightly.

Using the Selector Picker

Smart Selector Picker

The easiest way to create selectors is using the Selector Picker:

Click the target icon next to any selector field
A browser window opens with your page
Click on any element to select it
The picker generates multiple selector options, ranked by reliability
Choose the best selector or let auto-fallback try them in order

Selector Types

CSS Selectors

Standard CSS selectors work in Prompteryx:

#login-button

ID selector - very reliable if ID is unique

.submit-btn

Class selector - good for styled elements

button[type="submit"]

Attribute selector - matches by attribute

.form input:first-child

Combination - for complex targeting

Playwright Locators (Recommended)

Playwright locators are more reliable because they find elements by their purpose, not just structure:

getByRole("button", { name: "Submit" })

Finds by ARIA role and accessible name - most reliable

getByLabel("Email address")

Finds input by its label text

getByText("Sign up")

Finds element containing exact text

getByPlaceholder("Enter your email")

Finds input by placeholder text

getByTestId("submit-button")

Finds by data-testid attribute - dev-friendly

XPath Selectors

XPath is powerful but more fragile. Use when CSS and Playwright locators don't work:

//button[@class="submit"]//div[contains(text(), "Welcome")]//input[@name="email"]/../following-sibling::button

Auto-Fallback

How the picker ranks selectors (most reliable first):

Test ID (getByTestId) - when the page provides one
Role and accessible name (getByRole)
Placeholder (getByPlaceholder) and label (getByLabel) - for form inputs
Alt text and visible text (getByText) - for images, buttons and links
Title attribute
CSS ID, then other CSS selectors - last resort

Which steps use backup selectors and the AI fallback

The same on every run: in the cloud, on a schedule, and on your own computer with Prompteryx Desktop.

Order: the selected selector first, then your other selectors in list order, then the AI (only if you ticked AI Agent Fallback). Steps that don't use them don't show the controls.
Timing: the selected selector gets up to 15 seconds to appear (slow pages), each backup 2 seconds. A broken selector no longer holds a step for its whole 30-second timeout.
Extract Text: an element that is there but empty counts as a miss, so the next selector (or the AI) gets a try. With the AI fallback, the AI reads the text off the page and does not click or type; if it can't find it, the step fails instead of saving a guess.
Run history: each step's output says what did the work ( selectorUsed: "Primary selector", "Backup selector #2 of 3" or "AI fallback (3 steps, 6 credits)"), lists every selector tried in selectorAttempts, and the Execution Logs show each fall-through as it happens.

What the Selector Picker Generates

Example: Clicking a Link on Hacker News

If you click the top story title on Hacker News, the picker might generate:

getByRole("link", { name: "Show HN: My Cool Project" })

Matches the link by its current visible text

Content-Based vs Structure-Based

Selectors for Dynamic Content

Method 1: Pick, Then Edit

Easiest approach — start with the picker, then simplify

Use the Selector Picker to click the element you want. This confirms you're targeting the right thing.
Look at the generated selector in the Element Selector field. Note what type of element it found (a link, a heading, a div, etc.).
Replace the content-specific selector with a structural CSS selector. For example:

Before:getByRole("link", { name: "Show HN: My Cool Project" })

After:tr.athing:first-of-type .titleline

The edited selector targets "the title area of the first story row" — no matter what the story text says.

Method 2: Use Browser Inspect

Look at the page structure to find stable class names

Open the target website in your browser and right-click the element you want to target, then select "Inspect" (or press F12).
The Developer Tools will highlight the element in the HTML. Look for:
- Class names that describe the element's purpose (e.g. .titleline, .nav-footer, .product-card)
- ID attributes (e.g. #main-content) — these are unique on the page
- Data attributes (e.g. data-item="1") — often stable and meaningful
Build a selector using those stable attributes. Combine a parent's class with a child element to be specific:

.product-list .product-card:first-of-type

First product card in the product list

footer .footer-links

Links section inside the page footer

table tbody tr:nth-child(1) td.name

Name column of the first row in a table

Method 3: Ask an AI Assistant

Let AI generate the selector for you from the page's HTML

If you're not comfortable reading HTML, you can share the page's code with an AI assistant (like ChatGPT or Claude) and ask it to write a selector for you:

Open the target website, right-click the area you're interested in, and select "Inspect".
In the Developer Tools, right-click the highlighted HTML element and choose "Copy" → "Copy outer HTML" (or copy a larger section of the HTML around it).
Paste the HTML into an AI assistant and ask something like:

"Here is the HTML of a news page. I need a CSS selector that always picks the first story title, even when the stories change. The selector should not depend on any specific story text."

"Here is the HTML of a product listing page. Give me a CSS selector for the price of the first product in the grid. It should work no matter which products are shown."

Common Structural Selector Patterns

When to Use Which Type

Selector Picker (Playwright locators) — Best for buttons, form fields, navigation links, and any element with stable, unchanging text.
Structural CSS selectors — Best for dynamic content like news feeds, search results, product listings, or "the first/last item" in any list.
AI Agent Fallback (Last Resort) — Tick this checkbox under a selector field as a safety net. If all selectors fail, the AI agent tries to find the element visually. It uses AI credits only when it runs.

When Selectors Fail

Common Causes

Page hasn't fully loaded - add Wait for Element
Element is in an iframe - use Frame handling
Element is behind a modal/overlay - close it first
Dynamic IDs/classes that change each load
Element doesn't exist on this page state

Use Prompteryx Browser Agent

Best Practices

Prefer Role and Label Selectors

getByRole and getByLabel are the most reliable because they match how users perceive elements, not how they're coded. They survive UI redesigns better than CSS selectors.

Keep Auto-Fallback On

Auto-fallback is on by default and makes your automation self-healing. If the primary selector breaks, it automatically tries alternatives without stopping the workflow.

Use Positional Selectors Carefully

Test Across Page States

Test your selectors when the page is in different states (logged in/out, different data, etc.) to ensure they work consistently.

Selectors Guide

Overview

Using the Selector Picker

Selector Types

Auto-Fallback

How the picker ranks selectors (most reliable first):

What the Selector Picker Generates

Content-Based vs Structure-Based

Selectors for Dynamic Content

When to Use Which Type

When Selectors Fail

Common Causes

Use Prompteryx Browser Agent

Best Practices

Prefer Role and Label Selectors

Keep Auto-Fallback On

Use Positional Selectors Carefully

Test Across Page States

Related Documentation

Click Node

Wait Nodes

Prompteryx Browser Agent

Testing Workflows

Selectors Guide

Overview

Using the Selector Picker

Selector Types

Auto-Fallback

How the picker ranks selectors (most reliable first):

What the Selector Picker Generates

Content-Based vs Structure-Based

Selectors for Dynamic Content

When to Use Which Type

When Selectors Fail

Common Causes

Use Prompteryx Browser Agent

Best Practices

Prefer Role and Label Selectors

Keep Auto-Fallback On

Use Positional Selectors Carefully

Test Across Page States

Related Documentation

Click Node

Wait Nodes

Prompteryx Browser Agent

Testing Workflows