TestCafe Browser Tools

Common errors

• Error: The window with the provided ID was not found or is no longer accessible.

  cause 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.

  cause 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')

  cause 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.

Warnings

• gotcha Microsoft 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.
• breaking Specific 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.
• breaking The 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.
• gotcha When 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).

Install

• npm install testcafe-browser-tools npm
• yarn add testcafe-browser-tools yarn
• pnpm add testcafe-browser-tools pnpm

Imports

• findWindow
  wrong:

  const { findWindow } = require('testcafe-browser-tools');

  correct:

  import { findWindow } from 'testcafe-browser-tools';

  Primary usage is via ES modules. CommonJS is supported but ESM is idiomatic.
• get WindowInfo
  wrong:

  import getWindowInfo from 'testcafe-browser-tools';

  correct:

  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.

Quickstart

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();