Skip to main content
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

SelectorExampleMatches
ID#login-buttonElement with id="login-button"
Class.btn-primaryElements with class="btn-primary"
TagbuttonAll <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

PatternExampleMatches
Descendant.form-group inputinput anywhere inside .form-group
Direct child.menu > lili elements that are direct children of .menu
Adjacent siblingh2 + pp immediately after an h2
Groupbutton, a.btnBoth button and a.btn elements

​
Playwright Extensions

Figranium uses Playwright under the hood, which adds useful CSS pseudo-classes beyond standard CSS:
SelectorExampleDescription
:has-text()button:has-text("Submit")Elements whose text content includes the string
:text():text("Accept")Shorthand for exact/partial text match
:visiblebutton:visibleOnly 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

SelectorDescription
li:nth-child(3)The 3rd child element
li:first-childThe first child
li:last-childThe last child
input:checkedChecked checkboxes and radio buttons
input:disabledDisabled form inputs
input:focusCurrently focused element
a:emptyElements 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:
  1. Open the task in the Editor.
  2. In Settings > Advanced, enable Shadow DOM support.
  3. 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:
PatternDescription
//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::divThe 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:
  1. Name and placeholder attributes — [name="email"], [placeholder="Search..."]
  2. Text content — :has-text("Submit") for buttons, links, and labels
  3. Semantic attributes — [aria-label="Close"], [title="Settings"], [alt="Logo"]
  4. Data attributes — [data-testid="login-btn"], [data-cy="submit"]
  5. IDs — #checkout-form (skips random or obfuscated IDs)
  6. Other attributes — [type="submit"], [href="/account"]
  7. Classes — .product-card (skips auto-generated hashes like .sc-abc123)
  8. 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. See AI Selector Generation for setup and usage details. Set your preferred default tool in Settings > System > Selector Finder.

​
Browser Developer Tools

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

  1. 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.
  2. 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.
  3. 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.
  4. Scope your selectors: Instead of .item, use .product-list .item to avoid accidentally matching elements in other parts of the page.
  5. Avoid nth-child on large lists: li:nth-child(7) breaks when items are added/removed. Use a data attribute or text match instead.
  6. Test after site updates: Websites change. Pin important selectors to stable attributes and review them periodically.