Managing Playwright, Node.js, and Browser Version Compatibility

Maintaining a stable Playwright execution setup across local developer environments and CI pipelines is crucial for avoiding issues like pipeline flakiness and runtime errors. A key aspect of this stability hinges on clear version management strategies for Node.js, test packages, and browser drivers. This guide provides a straightforward reference matrix and best practices for managing compatibility between Playwright, test packages, Node.js runtimes, and target browsers.

The recommended compatibility matrix outlines the supported versions and browsers for Playwright test suites. It specifies that Playwright versions 1.55.x to 1.58.x should be used with Node.js runtime 24.x, targeting browsers such as Chromium, Chrome, Edge (via channels), and Firefox (optionally). The configuration reference indicates that the playwright package should be pinned to ^1.55.1, and the @playwright/test package to ^1.58.2, while the package.json engine definition should specify node: =24.x.x.

To ensure smooth upgrades and minimize compatibility issues, follow these best practices. Firstly, pin Node.js environments explicitly to Node.js 24.x across both local development setups and CI runner Docker images. This can be achieved by enforcing the engines key in the package.json file. Secondly, keep all packages in lockstep by upgrading core playwright drivers and @playwright/test packages simultaneously.

This approach avoids mismatches in APIs and runner functionalities that could lead to unexpected behavior. Finally, before promoting any upgrades to Playwright dependencies, review the official Playwright release notes for any shifts in browser engines. Additionally, run target smoke test suites across all supported browsers to validate the upgrades thoroughly.