{"id":12132,"library":"testcafe-browser-tools","title":"TestCafe Browser Tools","description":"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.","status":"active","version":"2.0.26","language":"javascript","source_language":"en","source_url":"https://github.com/DevExpress/testcafe-browser-tools","tags":["javascript"],"install":[{"cmd":"npm install testcafe-browser-tools","lang":"bash","label":"npm"},{"cmd":"yarn add testcafe-browser-tools","lang":"bash","label":"yarn"},{"cmd":"pnpm add testcafe-browser-tools","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally, likely for the playground or internal web server functionality, noted in CVE fixes.","package":"express","optional":false},{"reason":"Used internally for ID generation, noted in CVE fixes.","package":"nanoid","optional":false}],"imports":[{"note":"Primary usage is via ES modules. CommonJS is supported but ESM is idiomatic.","wrong":"const { findWindow } = require('testcafe-browser-tools');","symbol":"findWindow","correct":"import { findWindow } from 'testcafe-browser-tools';"},{"note":"Most API functions are named exports, not default.","wrong":"import getWindowInfo from 'testcafe-browser-tools';","symbol":"get       WindowInfo","correct":"import { getWindowInfo } from 'testcafe-browser-tools';"},{"note":"Useful for accessing multiple utilities without individual named imports.","wrong":null,"symbol":"* as browserTools","correct":"import * as browserTools from 'testcafe-browser-tools';"}],"quickstart":{"code":"import { findWindow, getWindowInfo, maximizeWindow } from 'testcafe-browser-tools';\n\nasync function automateBrowserActions() {\n  // In a real scenario, a browser would already be open, e.g., by TestCafe\n  console.log('Searching for a browser window by title (e.g., ' + process.env.BROWSER_WINDOW_TITLE + ')...');\n\n  // Note: For Microsoft Edge, ensure document.title is not just a URL.\n  // e.g., document.title = 'My Test Page: ' + document.location.toString();\n  const windowTitle = process.env.BROWSER_WINDOW_TITLE ?? 'Google'; // Replace with an actual window title\n\n  try {\n    const windowId = await findWindow(windowTitle);\n    if (windowId) {\n      console.log(`Found window with title '${windowTitle}', ID: ${windowId}`);\n\n      const info = await getWindowInfo(windowId);\n      console.log('Window Info:', info);\n\n      console.log(`Maximizing window ID: ${windowId}`);\n      await maximizeWindow(windowId);\n      console.log('Window maximized.');\n\n      // Example: Restore window (or other actions)\n      // await restoreWindow(windowId);\n      // console.log('Window restored.');\n    } else {\n      console.log(`Window with title '${windowTitle}' not found.`);\n    }\n  } catch (error) {\n    console.error('An error occurred:', error.message);\n  }\n}\n\nautomateBrowserActions();","lang":"javascript","description":"Demonstrates how to find a browser window by title, retrieve its information, and maximize it."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"2.0.25"},{"fix":"Upgrade to the latest package version (`npm update testcafe-browser-tools`) to mitigate known security vulnerabilities introduced via transitive dependencies.","message":"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).","severity":"breaking","affected_versions":"<2.0.27"},{"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).","message":"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`).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error: The window with the provided ID was not found or is no longer accessible."},{"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.","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.","error":"Error: Could not load native binary. Check your system dependencies."},{"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.","cause":"Attempting to call an API function like `maximizeWindow` without correctly importing it or if the `testcafe-browser-tools` module failed to load.","error":"TypeError: Cannot read properties of undefined (reading 'maximizeWindow')"}],"ecosystem":"npm"}