---

Selector Configuration Guide

This document details how to configure and use element selectors within task scripts.

1. Supported Selector Types

The plugin supports two main types of selectors: CSS Selectors and XPath.

1.1 CSS Selectors (Default)

This is the most commonly used selector type and the default parsing method. It covers common matching patterns such as IDs, class names, attributes, and hierarchy.

• Syntax: Standard CSS selector syntax.
• Examples:
  • Basic Positioning:
    • #submit-btn (ID selector - Recommended, unique and stable)
    • .user-profile (Class selector)
    • button.primary (Tag + Class combination)
  • Attribute Positioning (Powerful & Flexible):
    • input[name="username"] (Exact attribute match)
    • [data-testid="submit"] (Custom test attribute - Highly Recommended)
    • a[href*="login"] (Attribute value contains text)
    • img[src^="https"] (Attribute value starts with...)
    • div[class$="-container"] (Attribute value ends with...)
  • Hierarchy & Relationships:
    • .header > .logo (Direct child element)
    • .form-container input (All descendant elements)
    • .label + input (Immediately following sibling)
  • Pseudo-classes & States:
    • .content > p:first-child (First child element)
    • tr:nth-child(2n) (Even rows)
    • input:checked (Selected checkbox/radio)
    • .btn:not(.disabled) (Exclude specific class)

1.2 XPath Selectors

When CSS selectors cannot accurately locate an element (e.g., finding an element based on its text content or selecting a parent element), you can use XPath.

• Recognition Rules:
  1. Starts with the xpath: prefix (Recommended for explicit declaration).
  2. Starts with // (Automatically recognized as XPath).
• Examples:
  • xpath://div[contains(text(), "Login")]
  • //button[@type="submit"]
  • xpath://div[@class="item"]/.. (Find parent element)

---

2. Scenarios & Compatibility

Support for selectors varies slightly between different Action types. Please note the distinctions.

2.1 Interactions

Supported: CSS Selectors, XPath

Applicable to the following Actions:

• click
• type
• hover
• waitForElement
• mouse* (e.g., doubleClick, rightClick)

Examples:

{
  "action": "click",
  "selector": "//button[text()='Submit']",
  "description": "Click button using XPath"
}

{
  "action": "type",
  "selector": "#search-input",
  "text": "Agent",
  "description": "Input text using CSS ID"
}

2.2 Scrape

Supported: CSS Selectors Only

The scrape action uses querySelectorAll internally for batch retrieval, so XPath is not supported. Please ensure that both itemSelector and the field selectors in the schema are valid CSS selectors.

Example:

{
  "action": "scrape",
  "itemSelector": ".product-card", 
  "schema": {
    "name": ".product-title",
    "price": ".price-tag" 
  }
}

⚠️ Note: If you use XPath like //div in a scrape action, it will cause the scrape to fail or throw an error.

---

3. Best Practices

1. Prioritize CSS Selectors: The syntax is cleaner, performance is generally better than XPath, and it works for all Actions (including scrape).
2. Use IDs: If an element has a unique ID (e.g., #login-btn), this is the fastest and most stable way to locate it.
3. Use Data Attributes: Modern frontend apps often include attributes like data-test-id or data-role. These are usually more stable than class names.
   • [data-test-id="submit-order"]
4. XPath as a Backup: Use XPath only when CSS selectors cannot achieve the goal (e.g., "a button containing specific text") or when the path is extremely complex.
5. Relative Positioning: In the scrape schema, all selectors are relative to the current element found by the itemSelector.

---

4. FAQ

Q: How do I select the N-th element in a list?

CSS Method (Recommended): Use :nth-child(n) or :nth-of-type(n) pseudo-classes. Note that CSS indexes start from 1.

• ul > li:nth-child(3) (Selects the 3rd li)
• .item:nth-of-type(2) (Selects the 2nd element of type .item among siblings)
• .item:first-child (The 1st)
• .item:last-child (The last)

XPath Method: Use [] index syntax. Note that XPath indexes also start from 1.

• //ul/li[3] (The 3rd li)
• (//div[@class="item"])[1] (Can use parentheses to ensure it selects the global 1st)
• //div[@class="item"][last()] (The last one)

Q: How do I select based on the text on a button?

You must use XPath. Native CSS selectors do not support text matching.

• //button[text()="Submit"] (Exact match)
• //div[contains(text(), "Order Details")] (Contains match - Recommended, more robust)
• //a[normalize-space()="About Us"] (Ignores leading/trailing whitespace)

Q: What if an ID or Class name contains special characters (like . or :)?

In CSS selectors, symbols like . and : have special meanings, so they must be escaped using double backslashes \\.

• ID: user.name -> Selector: #user\\.name
• ID: frame:0 -> Selector: #frame\\:0

---

5. Debugging & Verification

Before writing scripts, it is recommended to verify selectors in the Console of Chrome DevTools (F12).

1. Verify CSS Selectors:

   // Returns the first matching element, or null if not found
   document.querySelector('.your-class')
   
   // Returns a list of all matching elements (useful for testing scrape)
   document.querySelectorAll('.item') 
   

2. Verify XPath (Chrome Console exclusive):

   // Returns an array of all matching elements
   $x('//button[text()="Submit"]')