Registry / testing / testcafe-browser-tools

testcafe-browser-tools

JSON →
library2.0.26jsnpmunverified

TestCafe Browser Tools is a JavaScript utility library designed to perform platform-dependent actions on web browser windows, crucial for automated testing frameworks like TestCafe. It abstracts away the complexities of interacting with browser APIs across different operating systems (Windows, macOS, Linux) by encapsulating pre-built native binaries and JavaScript wrappers. This approach eliminates the need for users to perform post-install build steps, ensuring a smoother setup. The current stable version is 2.0.27, with frequent patch and minor updates primarily addressing bug fixes, dependency vulnerabilities, and binary stability. Its key differentiator is the provision of robust, pre-compiled native tools that handle browser window manipulation, a task that often requires direct OS interaction and platform-specific code. It's an essential component for scenarios requiring reliable programmatic control over browser windows' positions, sizes, and focus during automated tests.

npm install testcafe-browser-tools
INSTALL
IMPORT
SIG · TESTCAFE-BROWSER-T
T
testcafe-browser-tools
testingjavascriptv2.0.26
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

findWindow
✓ import { findWindow } from 'testcafe-browser-tools';
✗ const { findWindow } = require('testcafe-browser-tools');
Primary usage is via ES modules. CommonJS is supported but ESM is idiomatic.
get WindowInfo
✓ import { getWindowInfo } from 'testcafe-browser-tools';
✗ import getWindowInfo from 'testcafe-browser-tools';
Most API functions are named exports, not default.
* as browserTools
✓ import * as browserTools from 'testcafe-browser-tools';
Useful for accessing multiple utilities without individual named imports.

Demonstrates how to find a browser window by title, retrieve its information, and maximize it.

import { findWindow, getWindowInfo, maximizeWindow } from 'testcafe-browser-tools'; async function automateBrowserActions() { // In a real scenario, a browser would already be open, e.g., by TestCafe console.log('Searching for a browser window by title (e.g., ' + process.env.BROWSER_WINDOW_TITLE + ')...'); // Note: For Microsoft Edge, ensure document.title is not just a URL. // e.g., document.title = 'My Test Page: ' + document.location.toString(); const windowTitle = process.env.BROWSER_WINDOW_TITLE ?? 'Google'; // Replace with an actual window title try { const windowId = await findWindow(windowTitle); if (windowId) { console.log(`Found window with title '${windowTitle}', ID: ${windowId}`); const info = await getWindowInfo(windowId); console.log('Window Info:', info); console.log(`Maximizing window ID: ${windowId}`); await maximizeWindow(windowId); console.log('Window maximized.'); // Example: Restore window (or other actions) // await restoreWindow(windowId); // console.log('Window restored.'); } else { console.log(`Window with title '${windowTitle}' not found.`); } } catch (error) { console.error('An error occurred:', error.message); } } automateBrowserActions();
Debug
Known issues
gotchaMicrosoft Edge truncates window titles to the hostname if the `document.title` only contains a URL. This can prevent `findWindow` and similar functions from correctly identifying the browser window.
fix
Prefix the `document.title` with additional characters (e.g., `document.title = 'title: ' + document.location.toString()`) to ensure the full title is reflected in the window's title bar.
affects: >=1.0.0
breakingSpecific versions of pre-built native binaries have caused issues, leading to reverts or fixes. For example, `v2.0.26` explicitly reverted to working binaries due to previous problems.
fix
Always use the latest stable version of the library (`npm install testcafe-browser-tools@latest`) to ensure you have the most reliable pre-built binaries. If issues persist, check the GitHub releases for specific advisories.
affects: 2.0.25
breakingThe package has experienced several supply chain vulnerability fixes in its dependencies, including `CVE-2021-23337` related to `vlN` (v2.0.27), and `CVE-2021-23566` in `nanoid` (v2.0.22).
fix
Upgrade to the latest package version (`npm update testcafe-browser-tools`) to mitigate known security vulnerabilities introduced via transitive dependencies.
affects: <2.0.27
gotchaWhen building native binaries from source (e.g., for contributions or specific environments), it's critical that the build is performed on a machine with the *same* operating system and a sufficiently old OS version if targeting older Node.js environments (e.g., NodeJS 16 docker container requiring `glibc-2.31`).
fix
Always build on the target platform. For older environments, ensure the build system matches the older OS version to guarantee binary compatibility and dependency linking (e.g., `glibc` versions).
affects: >=1.0.0
Errors
Common errors & fixes
Error: The window with the provided ID was not found or is no longer accessible.
The window targeted by an operation (e.g., maximizeWindow, getWindowInfo) either does not exist, has been closed, or the window ID is incorrect/stale.
fix
Ensure the browser window is open and visible. Re-acquire the window ID using `findWindow` before attempting operations if there's a chance the window state has changed or the ID is old.
Error: Could not load native binary. Check your system dependencies.
The pre-built native binary for your operating system failed to load, often due to missing runtime dependencies (e.g., specific `glibc` versions on Linux) or corrupted files.
fix
Ensure your system meets the basic requirements for the package (e.g., `Node.js >= 0.10`). Try clearing your `node_modules` and reinstalling (`rm -rf node_modules && npm install`). If building from source, ensure the build environment matches the deployment environment.
TypeError: Cannot read properties of undefined (reading 'maximizeWindow')
Attempting to call an API function like `maximizeWindow` without correctly importing it or if the `testcafe-browser-tools` module failed to load.
fix
Verify that you are using named imports (`import { maximizeWindow } from 'testcafe-browser-tools';`) and that `npm install testcafe-browser-tools` completed successfully without errors.
Upgrade
Version history
2.0.26latest on npm
Audit
Dependencies
expressrequiredUsed internally, likely for the playground or internal web server functionality, noted in CVE fixes.
nanoidrequiredUsed internally for ID generation, noted in CVE fixes.
Agent activity
9 hits · last 30 days
node
8
Resources