Implementation:MarketSquare Robotframework browser Locator Handler Grpc Handlers

Knowledge Sources	MarketSquare_Robotframework_browser
Domains	Browser Automation, Overlay Handling
Last Updated	2026-02-12 05:40 GMT

Overview

gRPC service handlers for registering and removing custom locator-based overlay handlers that automatically interact with UI overlays (such as cookie banners or modal dialogs) when they appear during test execution.

Description

This module exports two async functions that manage Playwright's locator handler API via gRPC.

addLocatorHandlerCustom registers a handler for a specified overlay selector on the active page. When the overlay element appears, the handler iterates through a list of handler specs and performs the specified actions (click, fill, check, or uncheck) on the corresponding action selectors with parsed JSON options. The handler supports an optional times parameter to limit how many times it triggers and a noWaitAfter flag. The overlay locator is cached in the locatorCache (keyed by page ID and selector) so it can be referenced later for removal.

removeLocatorHandler removes a previously registered handler by looking up the cached overlay locator for the given selector and page, deleting it from the cache, and calling Playwright's removeLocatorHandler on the active page. If no matching locator is found in the cache, it returns a log message indicating no handler was registered for that selector.

Usage

Use these handlers to automatically dismiss or interact with overlay elements that may appear unpredictably during test execution. This is particularly useful for cookie consent banners, authentication popups, survey modals, or any UI element that can block interaction with the page under test. Register the handler before navigating to pages where overlays may appear, and remove it when it is no longer needed.

Code Reference

Source Location

• Repository: MarketSquare_Robotframework_browser
• File: node/playwright-wrapper/locator-handler.ts
• Lines: 1-100

Signature

export async function addLocatorHandlerCustom(
    request: Request.LocatorHandlerAddCustom,
    state: PlaywrightState,
): Promise<Response.Empty>

export async function removeLocatorHandler(
    request: Request.LocatorHandlerRemove,
    state: PlaywrightState,
): Promise<Response.Empty>

Import

import { addLocatorHandlerCustom, removeLocatorHandler } from './locator-handler';

I/O Contract

Function	Request Type	Response Type	Description
addLocatorHandlerCustom	Request.LocatorHandlerAddCustom	Response.Empty	Registers a custom overlay handler for the given selector; caches the locator for later removal
removeLocatorHandler	Request.LocatorHandlerRemove	Response.Empty	Removes a previously registered overlay handler by selector; deletes from locator cache

addLocatorHandlerCustom Parameters
Parameter	Description
selector	CSS/XPath selector identifying the overlay element to watch for
times	Optional limit on how many times the handler fires; 'None' for unlimited
noWaitAfter	Boolean flag to skip waiting after handler actions complete
handlerSpecsList	List of action specs, each containing action type, selector, value, and JSON options

Supported Handler Actions
Action	Description
click	Clicks the specified action selector with provided options
fill	Fills an input at the action selector with the specified value and options
check	Checks a checkbox at the action selector with provided options
uncheck	Unchecks a checkbox at the action selector with provided options

Usage Examples

*** Settings ***
Library    Browser

*** Test Cases ***
Handle Cookie Banner Example
    New Browser    chromium    headless=true
    New Page       https://example.com
    # Register a handler to click "Accept" when a cookie banner appears
    Add Locator Handler    selector=css=.cookie-banner
    ...    action=click    actionSelector=css=.cookie-banner .accept-btn
    # Navigate and interact normally - overlay is handled automatically
    Go To    https://example.com/dashboard
    Click    css=.main-content button
    # Remove the handler when no longer needed
    Remove Locator Handler    selector=css=.cookie-banner

Related Pages

• Environment:MarketSquare_Robotframework_browser_Node_Runtime