Concepts

Core Concepts

Core Concepts

Persistent Selectors: Handling Nags and Popups

Selectors That Can Appear at Any Time

WithPersistentSelector adds a selector to a special unit of work that GPAL checks alongside every regular unit of work for the lifetime of the session. Pair it with PersistentCallIfFound and PersistentCallIfNotFound to react when the selector matches or doesn't. This is the right tool for nags not part of your workflow's logic -- cookie banners, rate-our-site popups, session-expired modals -- things that might appear after step 2, or step 20, or never.

// Dismiss a cookie banner whenever it appears, for the rest of the session

var cookieBanner = GPAL.Selector

.WithCSS("#cookie-consent .accept-all")

.WithSelectorName("Cookie Consent Accept")

.CallIfFound((browser, foundElements, matchedElements, selector, matchedAll) => {

matchedElements[0].Click();

return CallIfStatus.Handled;

})

.ToGPALObject();


GPAL.Browser

.WithBrowserType(BrowserType.Chrome)

.WithPersistentSelector(cookieBanner)

.GoTo("https://example.com");

NOTE

Persistent selectors run before the UOW selectors at each step -- they are checked first because a persistent element could get in the way of the UOW selector finding or interacting with the target. This is most pronounced with Selenium, where an element sitting in front of the target can block a click or fail a visibility check. It applies to image matching too: a persistent overlay on top of the target changes what the image matcher sees. They do not run on a timer or in a background thread; they run as part of GPAL's step-to-step bookkeeping.

One-Time Nags vs Recurring Nags

Not every nag needs to stay registered. A cookie banner usually only appears once per session -- once you've dismissed it, there's no reason to keep checking for it. Call selector.Remove() from inside the CallIfFound handler to remove that selector from the persistent unit of work after it's done its job. For handlers that were attached at multiple scopes (selector, UOW, and global), or that you registered as a named method and want gone everywhere at once, call browser.RemoveCallIfHandlerEverywhere(handler) -- it strips that delegate from every CallIfFound and CallIfNotFound list it was added to.

CallIfStatus FoundCookieBanner(IBrowser browser, List<IGPALElement> foundElements,

List<IGPALElement> matchedElements, Selector selector, bool matchedAll)

{

matchedElements[0].Click();


// one-time nag - stop checking for it

selector.Remove();


// and remove this handler from anywhere else it might be registered

browser.RemoveCallIfHandlerEverywhere(FoundCookieBanner);


return CallIfStatus.Handled;

}


var cookieBanner = GPAL.Selector

.WithCSS("#cookie-consent .accept-all")

.CallIfFound(FoundCookieBanner)

.ToGPALObject();


GPAL.Browser

.WithBrowserType(BrowserType.Chrome)

.WithPersistentSelector(cookieBanner)

.GoTo("https://example.com");

On this page

Core Concepts
Persistent Selectors: Handling Nags and Popups
  • Selectors That Can Appear at Any Time
  • One-Time Nags vs Recurring Nags
    • 💬 Ask GPAL