Reference

Selector

Selector

Selector Definition

Methods for defining how GPAL locates an element - by CSS, XPath, AutomationID, name, text, value, href, or a custom attribute.

Methods for defining how GPAL locates an element - by CSS, XPath, AutomationID, name, text, value, href, or a custom attribute.

GPAL.Selector returns a new Selector builder. WithCSS accepts a CSS selector string (browser only). WithXPath accepts an XPath expression (browser and desktop). WithAutomationID targets desktop elements by their UI Automation AutomationId property. WithName targets elements by the Name automation property (desktop) or the HTML name attribute (browser). WithText targets by visible text content (browser only). WithValue targets by the value attribute (browser only). WithHRef targets anchor elements by their href attribute. UseAttribute specifies a custom attribute name for matching.

TIP

CSS selectors are browser-only and generally faster. XPath works in both browser and desktop contexts and supports more complex traversal logic (parent/ancestor axis, position-based selection). Use CSS when targeting browsers, XPath or AutomationID for desktop.

WARNING

Wherever a Selector parameter is expected (WithSelector, WithPersistentSelector, etc.) a plain string can be passed directly instead of building one with GPAL.Selector - GPAL.Selector.WithCSS(...) and friends are mainly needed when you want to chain additional configuration such as Match filters, WithSelectorName, or WithHardware/WithJavaScript. When a string is used directly, GPAL does not guess between CSS and XPath - it sets the selector up with both, and CSS is tried first at match time, with XPath as the fallback if CSS finds nothing.

Examples

GPAL Fluent: High-level fluent C# API

//A Selector can specify only one primary locator (CSS, XPath, AutomationID, etc.). Match methods are filters applied after the primary locator finds candidates.

// CSS selector (browser) var loginBtn = GPAL.Selector .WithCSS("#login-button"); // XPath selector (browser or desktop) var nameField = GPAL.Selector .WithXPath("//input[@id='username']"); // AutomationID (desktop - most reliable) var saveBtn = GPAL.Selector .WithAutomationID("btnSave"); // By visible text var link = GPAL.Selector .WithText("Click Here"); // By custom attribute var item = GPAL.Selector .UseAttribute("data-testid") .MatchAttribute("submit-button");

On this page

Selector
Selector Definition
  • Examples