CSS Selectors

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.

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

Playwright Extensions

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

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

Shadow DOM

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

Open the task in the Editor.
In Settings > Advanced, enable Shadow DOM support.
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;

XPath

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

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

Right-click an element > Inspect.
In the Elements panel, press Ctrl+F (or Cmd+F on Mac).
Type a CSS selector or XPath to see highlighted matches in real-time.
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.

Intro

Installation

Basics

Features

Agent Logic

Integrations

API

Ops

Changelog

Basic Selectors

Combining Selectors

Playwright Extensions

Pseudo-Classes

Shadow DOM

XPath

Testing Selectors

Built-in Highlight Tool

AI Selector Generator

Browser Developer Tools

Testing in the Browser Console

Best Practices

​Basic Selectors

​Combining Selectors

​Playwright Extensions

​Pseudo-Classes

​Shadow DOM

​XPath

​Testing Selectors

​Built-in Highlight Tool

​AI Selector Generator

​Browser Developer Tools

​Testing in the Browser Console

​Best Practices

Basic Selectors

Combining Selectors

Playwright Extensions

Pseudo-Classes

Shadow DOM

XPath

Testing Selectors

Built-in Highlight Tool

AI Selector Generator

Browser Developer Tools

Testing in the Browser Console

Best Practices