Implementation:MarketSquare Robotframework browser Playwright Invoke

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

Overview

Core utility module providing locator resolution and keyboard/mouse invocation functions used throughout the Playwright wrapper layer.

Description

This module exports four key functions that form the foundation of element interaction in the Node.js Playwright wrapper.

findLocator is the central locator resolution function. It takes a PlaywrightState reference, a selector string, strict mode flag, optional nth index, and a firstOnly flag. It handles frame-piercing selectors by replacing the >>> separator with Playwright's internal frame-entering control syntax. In strict mode, selectors are used as-is; in non-strict mode, nth=0 is inserted at frame boundaries to select the first match. If nthLocator is provided, it returns the nth matching element. When strict mode is disabled and firstOnly is true, it returns locator.first(); otherwise it returns the full locator that may match multiple elements.

invokeOnMouse executes mouse actions (move, down, up, click, dblclick) on the active page's mouse object. It binds the specified method and spreads the provided argument values as positional parameters.

invokeOnKeyboard executes keyboard actions (down, up, press, insertText, type) on the active page's keyboard object using the same bind-and-spread pattern.

exists is a TypeScript assertion function that throws an Error with a descriptive message if the provided value is falsy, enabling non-nullable type narrowing in subsequent code.

Usage

These functions are called by virtually all other handler modules in the Playwright wrapper. findLocator is the standard way to resolve a Robot Framework selector string into a Playwright Locator object. invokeOnMouse and invokeOnKeyboard are used by the interaction handlers. exists is used as a guard throughout the codebase to validate that pages, contexts, and locators are available before performing operations.

Code Reference

Source Location

• Repository: MarketSquare_Robotframework_browser
• File: node/playwright-wrapper/playwright-invoke.ts
• Lines: 1-103

Signature

export async function findLocator(
    state: PlaywrightState,
    selector: string,
    strictMode: boolean,
    nthLocator: number | undefined,
    firstOnly: boolean,
): Promise<Locator>

export async function invokeOnMouse(
    page: Page | undefined,
    methodName: 'move' | 'down' | 'up' | 'click' | 'dblclick',
    args: Record<any, any>,
): Promise<any>

export async function invokeOnKeyboard(
    page: Page,
    methodName: 'down' | 'up' | 'press' | 'insertText' | 'type',
    ...args: any[]
): Promise<any>

export function exists<T1>(obj: T1, message: string): asserts obj is NonNullable<T1>

Import

import { findLocator, invokeOnMouse, invokeOnKeyboard, exists } from './playwright-invoke';

I/O Contract

Function	Input	Output	Description
findLocator	state: PlaywrightState, selector: string, strictMode: boolean, nthLocator: number or undefined, firstOnly: boolean	Promise<Locator>	Resolves a selector string to a Playwright Locator; handles frame-piercing, nth selection, and strict/non-strict modes
invokeOnMouse	page: Page or undefined, methodName: string, args: Record	Promise<any>	Executes a mouse action on the page's mouse object; throws if page is undefined
invokeOnKeyboard	page: Page, methodName: string, ...args: any[]	Promise<any>	Executes a keyboard action on the page's keyboard object; throws if binding fails
exists	obj: T1, message: string	asserts obj is NonNullable<T1>	Throws Error with message if obj is falsy; narrows type to non-nullable

findLocator Selector Handling
Mode	Behavior
Strict mode + frame piercing	>>> replaced with >> internal:control=enter-frame >>
Non-strict mode + frame piercing	>>> replaced with >> nth=0 >> internal:control=enter-frame >>
nthLocator provided	Returns activePage.locator(selector).nth(nthLocator)
Strict mode (no nth)	Returns activePage.locator(selector) directly
Non-strict + firstOnly	Returns activePage.locator(selector).first()
Non-strict + not firstOnly	Returns activePage.locator(selector) (may match multiple elements)

Usage Examples

import { findLocator, invokeOnMouse, invokeOnKeyboard, exists } from './playwright-invoke';

// Resolve a locator in strict mode
const locator = await findLocator(state, 'css=button.submit', true, undefined, true);

// Resolve a frame-piercing locator
const frameLocator = await findLocator(state, '#iframe >>> //button', false, undefined, true);

// Execute a mouse click at coordinates
await invokeOnMouse(page, 'click', { x: 100, y: 200 });

// Press a keyboard key
await invokeOnKeyboard(page, 'press', 'Enter');

// Guard that page exists before use
exists(page, 'No active page found');
// page is now narrowed to non-nullable type

Related Pages

• Environment:MarketSquare_Robotframework_browser_Node_Runtime