CSS, XPath, and Playwright Selectors in Figranium

Selectors are the “coordinates” Figranium uses to find and interact with elements on a webpage. Figranium relies primarily on CSS Selectors, with additional Playwright-specific extensions for text-based and visibility-based matching.

CSS Selectors
Playwright Extensions
XPath
Shadow DOM

Basic Selectors

Selector	Example	Matches
ID	`#login-button`	Element with `id="login-button"`
Class	`.btn-primary`	Elements with `class="btn-primary"`
Tag	`button`	All `<button>` elements
Attribute	`[type="submit"]`	Elements with `type="submit"`
Attribute contains	`[class*="error"]`	Elements where class contains “error”
Attribute starts with	`[href^="https"]`	Elements where href starts with “https”

Combining Selectors

Pattern	Example	Matches
Descendant	`.form-group input`	`input` anywhere inside `.form-group`
Direct child	`.menu > li`	`li` elements that are direct children of `.menu`
Adjacent sibling	`h2 + p`	`p` immediately after an `h2`
Group	`button, a.btn`	Both `button` and `a.btn` elements

Pseudo-Classes

Selector	Description
`li:nth-child(3)`	The 3rd child element
`li:first-child`	The first child
`li:last-child`	The last child
`input:checked`	Checked checkboxes and radio buttons
`input:disabled`	Disabled form inputs
`input:focus`	Currently focused element
`a:empty`	Elements with no children

Prefer IDs and data-* attributes for the most stable selectors. Avoid long descendant chains that break when the DOM structure changes.

Figranium uses Playwright under the hood, which adds useful CSS pseudo-classes beyond standard CSS:

Selector	Example	Description
`:has-text()`	`button:has-text("Submit")`	Elements whose text content includes the string
`:text()`	`:text("Accept")`	Shorthand for exact/partial text match
`:visible`	`button:visible`	Only visible elements (not hidden via CSS)
`:nth-match()`	`:nth-match(.item, 2)`	The Nth element matching a selector
`:has()`	`li:has(img)`	Elements that contain a child matching the inner selector
`:is()`	`:is(h1, h2, h3)`	Matches any of the given selectors
`:not()`	`input:not([disabled])`	Elements that do NOT match

Use :has-text() when a button’s text is the most stable thing about it, rather than a brittle class like .btn-blue-v2.

While CSS selectors are preferred, XPath is available for cases where CSS is insufficient — for example, selecting an element by its exact text content or navigating upward to a parent.Use the xpath= prefix to indicate an XPath selector:

xpath=//button[text()='Submit']
xpath=//td[contains(text(),'Total')]/following-sibling::td
xpath=//label[text()='Username']/following-sibling::input

Common XPath patterns:

Pattern	Description
`//div[@class='box']`	Div with exact class “box”
`//button[contains(text(),'OK')]`	Button whose text contains “OK”
`//input[@name='email']`	Input with name attribute “email”
`(//li)[3]`	The 3rd `li` element on the page
`//p/parent::div`	The parent `div` of a `p` element

XPath is especially useful for navigating up the DOM tree (e.g., parent::) or matching exact text content, which CSS cannot do natively.

Modern web applications often use Shadow DOM (Web Components). Standard CSS selectors cannot pierce shadow boundaries.To enable Shadow DOM traversal:

Open the Editor

Open the task in the Editor.

Enable Shadow DOM support

In Settings > Advanced, enable Shadow DOM support.

Use the shadow-piercing combinator

Use the >> combinator (Playwright’s shadow-piercing separator):

/* Click a button inside a shadow root */
my-component >> button.submit

Alternatively, use a JavaScript block to query shadow DOM manually:

return document.querySelector("my-component")
  .shadowRoot
  .querySelector(".submit-btn")
  .innerText;

Enable Shadow DOM support only for pages that use Web Components. Standard pages work fine without it.

Testing Selectors

Figranium provides multiple tools for finding and verifying selectors:

Built-in Highlight Tool

Click the selector/crosshair icon in any action block’s selector field. This activates a visual picker in the headful browser that lets you hover over and click elements on the live page. When you click an element, Figranium generates up to five selector candidates ranked by stability and readability. The top candidate is automatically inserted into the selector field, and the remaining alternatives appear as clickable pill buttons below the input. Click any alternative to switch. The selector generation algorithm prioritizes selectors in this order:

Name and placeholder attributes — [name="email"], [placeholder="Search..."]
Text content — :has-text("Submit") for buttons, links, and labels
Semantic attributes — [aria-label="Close"], [title="Settings"], [alt="Logo"]
Data attributes — [data-testid="login-btn"], [data-cy="submit"]
IDs — #checkout-form (skips random or obfuscated IDs)
Other attributes — [type="submit"], [href="/account"]
Classes — .product-card (skips auto-generated hashes like .sc-abc123)
Structural fallback — tag:nth-of-type(n) or parent path

This priority order means you get human-readable, resilient selectors by default, with structural fallbacks only when no better option exists.

AI Selector Generator

Uses AI (Gemini or Claude) to generate robust, semantically meaningful selectors. It analyzes the page structure and suggests selectors that are more resilient to minor HTML changes. Configure your AI provider keys in Settings > System > API Keys and choose the preferred model in Settings > System > AI Models. Set your preferred default selector tool in Settings > System > Selector Finder.

Browser Developer Tools

Inspect the element

Right-click an element > Inspect.

Search for matches

In the Elements panel, press Ctrl+F (or Cmd+F on Mac).

Type and verify

Type a CSS selector or XPath to see highlighted matches in real-time.

Copy the selector

Right-click the element in the Elements tree > Copy > Copy selector for an auto-generated selector.

Testing in the Browser Console

Verify a selector in DevTools console:

// CSS
document.querySelectorAll(".product-card")  // → NodeList

// XPath
document.evaluate(
  "//button[text()='Buy Now']",
  document, null,
  XPathResult.FIRST_ORDERED_NODE_TYPE, null
).singleNodeValue

Best Practices

Prefer IDs and data-* attributes: IDs (#submit) and test attributes ([data-testid="submit"]) are the most stable because they are explicitly set by developers and less likely to change with styling updates.
Avoid long chains: body > div > div > section > ul > li > span breaks as soon as the HTML structure changes. Use a more specific class or attribute closer to the element.
Use :has-text() for dynamic buttons: When a button’s text is the most stable thing about it, use button:has-text("Add to Cart") rather than a brittle class like .btn-blue-v2.
Scope your selectors: Instead of .item, use .product-list .item to avoid accidentally matching elements in other parts of the page.
Avoid nth-child on large lists: li:nth-child(7) breaks when items are added/removed. Use a data attribute or text match instead.
Test after site updates: Websites change. Pin important selectors to stable attributes and review them periodically.

When a selector feels brittle, switch to the Highlight Tool or AI Selector Generator to find a more stable alternative before it breaks in production.

Intro

Installation

Basics

Features

Agent Logic

API

JavaScript SDK

Integrations

Ops

Changelog

CSS, XPath, and Playwright Selectors in Figranium

Basic Selectors

Combining Selectors

Pseudo-Classes

Testing Selectors

Built-in Highlight Tool

AI Selector Generator

Browser Developer Tools

Testing in the Browser Console

Best Practices

​Basic Selectors

​Combining Selectors

​Pseudo-Classes

​Testing Selectors

​Built-in Highlight Tool

​AI Selector Generator

​Browser Developer Tools

​Testing in the Browser Console

​Best Practices

Basic Selectors

Combining Selectors

Pseudo-Classes

Testing Selectors

Built-in Highlight Tool

AI Selector Generator

Browser Developer Tools

Testing in the Browser Console

Best Practices