Concepts

Basic Concepts

Basic Concepts

Hardware-Level Interaction

What WithHardware Changes

By default, GPAL interacts with elements through the automation engine's normal API. Selenium's element.Click(), Puppeteer's CDP input events, or UI Automation's invoke patterns for desktop controls. WithHardware switches that element to real OS-level input instead: GPAL moves the actual mouse cursor and generates real click and keypress events at the OS level, exactly as if a person were at the keyboard. For text inputs under hardware emulation, focusing the control means physically clicking it first; otherwise GPAL just hovers over it.

// Normal interaction

browser

.LeftClick("#normal-btn");


// Hardware interaction - real OS mouse movement and click

browser

.WithSelector("#stubborn-btn").WithHardware

.LeftClick();

When Programmatic Interaction Isn't Enough

Some elements don't respond correctly to programmatic events, or sites that specifically check for synthetic input as a sign of automation. WithHardware bypasses all of that by generating the same low-level input a real user produces, at the cost of needing the target element to actually be visible and positioned on screen for the mouse to reach it. After a hardware click, GPAL normally leaves the cursor right where it landed. The one exception is when the current unit of work also uses image selectors: GPAL then parks the mouse at a randomized edge or corner of the browser window first, so a lingering hover state (tooltips, dropdowns, sticky menus) can't obscure the next image match. For workflows where every interaction needs to be hardware-driven, this is set by choosing a HW variant of AutomationEngine.

NOTE

WithHardware can be set globally on GPAL, inline on the workflow right after WithSelector, or baked into a reusable Selector definition. See 'Configuration Hierarchy' in Core Concepts for how these layers combine.

On this page

Basic Concepts
Hardware-Level Interaction
  • What WithHardware Changes
  • When Programmatic Interaction Isn't Enough
    • 💬 Ask GPAL