Implementation:Getgauge Taiko DomHandler

Knowledge Sources	Getgauge_Taiko
Domains	Browser_Automation, DOM_Geometry
Last Updated	2026-02-12 03:00 GMT

Overview

The DomHandler module provides geometric bounding-box calculations for DOM elements using the Chrome DevTools Protocol DOM domain, enabling precise coordinate-based interactions such as clicking at specific positions on elements.

Description

DomHandler is a low-level handler within the Taiko framework that translates DOM element references into pixel coordinates. It wraps the CDP DOM.getContentQuads command to retrieve the four-corner quad coordinates of an element's border box, then derives various positional representations from those quads: center, top-left, top-right, bottom-right, bottom-left, left edge, and right edge.

The module originated from Puppeteer and was adapted for Taiko's architecture. It listens for the createdSession event on the internal event bus to obtain a reference to the CDP DOM domain client. All exported functions are asynchronous and operate on either raw CDP object IDs (strings) or Taiko element objects that carry an objectId property.

Beyond basic bounding-box retrieval, the module provides utilities for computing the positional difference between two elements (used for proximity-based element resolution), calculating a new center point after applying directional offsets (used for drag-and-drop operations), and setting file paths on <input type="file"> elements via DOM.setFileInputFiles.

Usage

Use DomHandler whenever you need to translate a DOM element into screen coordinates for input simulation (clicks, drags, hovers). It is called internally by Taiko's action layer (click, hover, dragAndDrop) and by the scroll and proximity-matching subsystems. It is not intended to be called directly by end users.

Code Reference

Source Location

• Repository: Getgauge_Taiko
• File: lib/handlers/domHandler.js
• Lines: 1-223

Signature

async function boundBox(e) -> {x, y, width, height} | null
async function boundingBoxCenter(e) -> {x, y}
async function boundingBoxRight(e) -> {x, y}
async function boundingBox(position, e) -> {x, y}
async function boundingBoxTopLeft(e) -> {x, y}
async function boundingBoxTopRight(e) -> {x, y}
async function boundingBoxBottomRight(e) -> {x, y}
async function boundingBoxBottomLeft(e) -> {x, y}
async function boundingBoxLeft(e) -> {x, y}
async function getBoundingClientRect(e) -> {top, bottom, left, right} | null
async function getPositionalDifference(nodeA, nodeB) -> number
async function getBoxModel(e) -> {model: {border: Array<number>}}
async function calculateNewCenter(sourceElemobjectId, destElem) -> {x, y, newBoundary}
async function setFileInputFiles(objectId, resolvedPath) -> void

Import

const {
  boundBox,
  boundingBoxCenter,
  boundingBoxRight,
  boundingBox,
  boundingBoxLeft,
  getBoundingClientRect,
  boundingBoxTopRight,
  boundingBoxBottomRight,
  boundingBoxBottomLeft,
  boundingBoxTopLeft,
  getPositionalDifference,
  getBoxModel,
  calculateNewCenter,
  setFileInputFiles,
} = require("./handlers/domHandler");

I/O Contract

Primary Function: boundingBox(position, e)

Parameter	Type	Description
position	null	One of: "center", "topLeft", "topRight", "bottomRight", "bottomLeft", "left", "right". Defaults to "center" if null/undefined.
e	Element	A CDP objectId string or a Taiko element object with objectId property.

Return	Type	Description
{x, y}	Object	Pixel coordinates of the requested position on the element.

getPositionalDifference(nodeA, nodeB)

Parameter	Type	Description
nodeA	Element	First element reference.
nodeB	Element	Second element reference.

Return	Type	Description
number	number	Sum of absolute differences across all four rect edges (top, left, bottom, right). Lower values indicate closer proximity.

calculateNewCenter(sourceElemobjectId, destElem)

Parameter	Type	Description
sourceElemobjectId	string	CDP objectId of the source element.
destElem	Object	Directional offset object with optional keys: up, down, left, right (pixel values).

Return	Type	Description
{x, y, newBoundary}	Object	New center coordinates and the adjusted boundary rect after applying the directional offsets.

setFileInputFiles(objectId, resolvedPath)

Parameter	Type	Description
objectId	string	CDP objectId of the file input element.
resolvedPath	Array<string>	Array of absolute file paths to attach.

Algorithm

The core algorithm uses DOM.getContentQuads to obtain the quad coordinates of an element's border box. A quad is an array of 8 numbers representing 4 (x,y) pairs for the four corners of the element. The getBoxModel function retrieves this quad and wraps it in a {model: {border: quad}} structure for compatibility.

The boundBox function then derives the axis-aligned bounding box by finding the min/max x and y values across all four corners:

const x = Math.min(quad[0], quad[2], quad[4], quad[6]);
const y = Math.min(quad[1], quad[3], quad[5], quad[7]);
const width = Math.max(quad[0], quad[2], quad[4], quad[6]) - x;
const height = Math.max(quad[1], quad[3], quad[5], quad[7]) - y;

Each named position function (center, topLeft, etc.) computes its coordinate from this bounding box. For example, center is (x + width/2, y + height/2) and topRight is (x + width - 1, y).

The calculateNewCenter function applies directional pixel offsets (up, down, left, right) to an element's bounding client rect and returns the center of the resulting adjusted rectangle. This enables drag-and-drop to a relative position.

CDP Domain

This handler uses the DOM domain with two commands:

• DOM.getContentQuads -- Retrieves the quads (4-point border coordinates) for an element identified by objectId.
• DOM.setFileInputFiles -- Sets file paths on a file input element, bypassing the native file chooser dialog.

Usage Examples

// Internal usage: click at center of an element
const { boundingBox } = require("./handlers/domHandler");
const point = await boundingBox("center", elementObjectId);
// point => { x: 150, y: 200 }

// Internal usage: get proximity score between two elements
const { getPositionalDifference } = require("./handlers/domHandler");
const diff = await getPositionalDifference(labelObjectId, inputObjectId);
// diff => 12 (lower = closer)

// Internal usage: calculate drag destination
const { calculateNewCenter } = require("./handlers/domHandler");
const dest = await calculateNewCenter(dragElemId, { right: 100, down: 50 });
// dest => { x: 250, y: 275, newBoundary: {...} }

Related Pages

• Getgauge_Taiko_DOM_Geometry -- Principle page for DOM coordinate geometry concepts
• Getgauge_Taiko_RuntimeHandler -- Runtime handler that resolves element selectors to objectIds consumed by DomHandler
• Getgauge_Taiko_Click -- Click action that delegates to boundingBox for coordinate resolution
• Getgauge_Taiko_DragAndDrop -- Drag-and-drop action that uses calculateNewCenter
• Getgauge_Taiko_Attach -- File attach action that uses setFileInputFiles