Implementation:Getgauge Taiko MouseAction
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, User_Interaction |
| Last Updated | 2026-02-12 03:00 GMT |
Overview
Concrete tool for dispatching individual low-level mouse events (press, move, release) at specific coordinates provided by the Taiko browser automation library.
Description
The `mouseAction` function provides fine-grained control over mouse input by dispatching individual CDP mouse events at precise pixel coordinates. Unlike higher-level actions such as `click` or `hover`, this function allows issuing discrete `press`, `move`, and `release` events independently, enabling automation of complex interactions like custom drag handles, canvas drawing, range sliders, and map interactions.
The function operates in two distinct modes based on the type of the `selector` parameter:
- Mode 1 -- Element-Relative Coordinates:** When `selector` is a valid Taiko selector or string (not one of the action keywords), the function resolves the element via `waitAndGetActionableElement`, scrolls it into view with `scrollToElement`, retrieves its bounding rectangle via `domHandler.getBoundingClientRect`, and adds the provided `coordinates.x` and `coordinates.y` offsets to the element's `left` and `top` positions. This produces absolute page coordinates relative to the element's top-left corner. The `action` parameter then specifies which mouse event to dispatch.
- Mode 2 -- Absolute Coordinates:** When `selector` is one of the action strings (`"press"`, `"move"`, `"release"`), the function reinterprets the parameters: the `selector` becomes the action, and the `action` parameter is treated as the `{x, y}` coordinate object representing absolute viewport positions. No element resolution or scrolling is performed.
In both modes, the resolved action string is mapped to a CDP `Input.dispatchMouseEvent` type: `"press"` maps to `mousePressed`, `"move"` maps to `mouseMoved`, and `"release"` maps to `mouseReleased`. In headful mode, a 1x1 pixel highlight rectangle is drawn at the target coordinates for visual feedback. The event is dispatched within `doActionAwaitingNavigation` to handle any navigation that may result from the mouse interaction.
Usage
Use `mouseAction` when you need granular control over individual mouse events that cannot be expressed with higher-level Taiko actions. Common scenarios include drawing on HTML5 canvas elements (press, move along a path, release), interacting with custom slider controls, manipulating map pan/zoom interfaces, testing game UIs, and any interaction requiring a sequence of separate press/move/release steps at precise coordinates.
Code Reference
Source Location
- Repository: Getgauge_Taiko
- File: lib/actions/mouseAction.js
- Lines: 1-63
Signature
const mouseAction = async (selector, action, coordinates, options) => { ... }
Import
const { mouseAction } = require('taiko');
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| selector | Selector / string | Yes | In Mode 1: a Taiko selector or CSS string identifying the target element. In Mode 2: one of the action strings `"press"`, `"move"`, or `"release"`. |
| action | string / {x, y} | Yes | In Mode 1: the mouse action to perform (`"press"`, `"move"`, or `"release"`). In Mode 2: an `{x, y}` coordinate object specifying absolute viewport pixel positions. |
| coordinates | {x, y} | Conditional | In Mode 1: an `{x, y}` offset relative to the element's top-left bounding box corner. Not used in Mode 2. |
| options | object | Yes | Configuration object. Supports `force` (boolean) to bypass actionability checks, plus navigation and click options inherited from `setNavigationOptions` and `setClickOptions`. |
Outputs
| Name | Type | Description |
|---|---|---|
| result | Promise<string> | A human-readable description of the action performed, e.g. `"Performed mouse press action at {100, 200}"`. |
Usage Examples
Basic Usage
const { openBrowser, goto, mouseAction, $, closeBrowser } = require('taiko');
(async () => {
await openBrowser();
await goto('https://example.com/canvas-app');
// Mode 1: Element-relative coordinates -- click at offset (50, 30) from the canvas top-left
await mouseAction($('#drawing-canvas'), 'press', { x: 50, y: 30 }, {});
await mouseAction($('#drawing-canvas'), 'move', { x: 150, y: 100 }, {});
await mouseAction($('#drawing-canvas'), 'release', { x: 150, y: 100 }, {});
// Mode 2: Absolute viewport coordinates -- press at (300, 400) without referencing an element
await mouseAction('press', { x: 300, y: 400 }, {}, {});
await mouseAction('move', { x: 500, y: 400 }, {}, {});
await mouseAction('release', { x: 500, y: 400 }, {}, {});
await closeBrowser();
})();