Concepts

Core Concepts

Core Concepts

The Selector System

Selectors are how GPAL locates elements in a browser or desktop application. A single selector can define multiple location strategies. If the first finds nothing, GPAL automatically tries the next.

Location Strategies

A selector is built with GPAL.Selector and configured with one or more location strategies. Browser selectors can find elements by CSS, XPath, visible text, attribute values, or even a visual image match. Application selectors use the Windows UI Automation tree instead -- matching by accessible name, automation ID, class name, or image. XPath and image matching work with both targets.

Multiple Strategies and Fallback

When more than one strategy is defined, GPAL tries each in declaration order. The first strategy that finds at least one element wins. The rest are skipped. This makes selectors resilient across different page states or browser versions without any conditional logic in your code.

// Single strategy

var heading = GPAL.Selector.WithCSS("h1").ToGPALObject();

// Multiple strategies - tried in order, first match wins

var btn = GPAL.Selector

.WithCSS("#submit-btn") // tried first

.WithXPath("//button[@type='submit']") // fallback

.WithText("Submit") // last resort

.WithSelectorName("Submit Button")

.ToGPALObject();

TIP

WithSelectorName gives the selector a human-readable label used in log messages, event channel output, and as column headers when saving scraped data to a file. Essential for debugging.

Interaction Type Override

Each selector can override the interaction type for that one element with .WithHardware, .WithSelenium, or .WithJavaScript. .WithHardware works on any automation engine, adding real OS-level input for just that element. .WithSelenium and .WithJavaScript only apply on the Selenium stack, whose default is Selenium for everything. Set Hardware globally to flip that default, then use .WithSelenium, .WithJavaScript, or .WithHardware per selector to mix any combination.

WARNING

CSS, HRef, and Placeholder work only with Browser automation. Name and AutomationID work only with Application automation. XPath, Image, Text, Value, and ClassName work with both.

On this page

Core Concepts
The Selector System
  • Location Strategies
  • Multiple Strategies and Fallback
  • Interaction Type Override