@playwright-helper-utils/generic-utils

A collection of utility functions for Playwright to simplify common tasks and enhance the efficiency of your end-to-end test scripts.

Installation

npm install @playwright-helper-utils/generic-utils

Peer Dependency: Requires @playwright/test >= 1.0.0

Usage

import {
  clickSelector,
  fillTextInput,
  waitForSelectorToEnable,
  delay,
} from '@playwright-helper-utils/generic-utils';

API Reference

Core Element Interactions

| Function | Description | |---|---| | clickSelector(locatable, selector) | Waits for the element to become visible, then clicks it. | | forceClick(locatable, selector, doubleClick?) | Force-clicks an element, bypassing actionability checks. Optionally double-clicks. | | fillTextInput(locatable, selector, text, options) | Fills a text input field. Set { clear: true } to clear existing content first. | | fillLargeText(locatable, selector, text) | Fills large text by setting the element value directly via JS evaluation. | | waitForSelectorToEnable(locatable, selector) | Waits for the element to become visible (up to 180s). | | waitForSelectorToDisable(locatable, selector) | Waits for the element to become hidden (up to 180s). |

Element Data Retrieval

| Function | Description | |---|---| | getElementInnerText(locatable, selector) | Returns the inner text of the first matching element. | | getElementInnerTextByPosition(locatable, selector, position) | Returns the inner text of the element at a specific zero-based index. | | getAttributeValue(locatable, selector, attributeName) | Returns the value of an HTML attribute from the first matching element. | | getElementPropertyValue(locatable, selector, property) | Returns the computed CSS property value of the first matching element. | | getElementPropertyValueUsingXPath(page, xpath, property) | Returns the computed CSS property value of an element located via XPath. |

Navigation & Frame Handling

| Function | Description | |---|---| | navigateToNewTab(page, selector) | Clicks an element that opens a new tab, waits for it to load, and returns the new Page. | | getFrameByName(page, frameName) | Retrieves a child frame by its name attribute. | | getElementTextValueFromFrame(page, selector, frameName) | Gets the .value of an input/textarea within a named frame. | | uploadFile(page, scope, selector, filePath) | Uploads a file via the file chooser dialog triggered by clicking the specified element. |

Element Layout & Visual Validation

| Function | Description | |---|---| | getElementBoundingBoxValue(locatable, selector, position?) | Returns [x, y, height, width] of an element's bounding box. | | getElementOrientation(locatable, selector) | Returns 'Portrait' or 'Landscape' based on the element's dimensions. | | checkOverlap(locatable, selector1, selector2) | Returns true if two elements' bounding boxes intersect. | | verifyScrollBarPresence(locatable, selector, verticalScroll?) | Returns true if a vertical (default) or horizontal scroll bar is present. |

Canvas Operations

| Function | Description | |---|---| | drawLineInCanvas(element) | Draws a horizontal line on a canvas from (50, 50) to (200, 50). | | getCanvasImageData(element) | Returns the RGBA pixel data array for the drawn line region. |

Network & Browser Control

| Function | Description | |---|---| | blockNetwork(page) | Blocks all network requests by emulating offline conditions via CDP. |

Utility & Helper Functions

| Function | Description | |---|---| | generateUniqueName(prefix) | Generates a unique name: {prefix}_Playwright_{timestamp}. | | delay(milliseconds) | Promise-based delay (replacement for deprecated waitForTimeout). | | parseJsonFromString(input) | Extracts and parses a JSON object from a raw string, sanitizing smart quotes. | | convertPxToPt(px) | Converts a pixel value string to points (px × 0.75). | | getFirstMatchingXPathNode(page, xpath) | Returns the first DOM node matching an XPath expression, or undefined. | | readTextFromFile(filePath) | Reads a text file and returns its UTF-8 content. | | executeBatchFile(batchFilePath) | Executes a batch file synchronously. |

Type: Locatable

Most functions accept a locatable parameter, which can be any of:

type Locatable = Page | Locator | FrameLocator | Frame;

This allows you to scope element lookups to the full page, a specific frame, or a nested locator.

License

ISC