How to update Playwright or Selenium without breaking your test suite
Updating Playwright or Selenium need not mean days of blind test repairs. Keep the framework change separate from the browser, driver and continuous integration (CI) environment. You can then identify the cause of a failure, verify the result and restore the last working build if necessary.
You are updating more than one package
A test suite combines a library or test runner, its runtime and dependencies, the browser, a WebDriver where applicable, operating system libraries and a CI image. Changing one layer may expose an incompatibility in another.
Each Playwright version requires particular browser builds, so an update may require another installation through the Playwright CLI. The Playwright browser documentation describes this dependency. Changing package.json alone does not complete the update.
With Selenium, the language package, browser and driver that controls it can have separate lifecycles. Selenium Grid or an external provider adds the remote node and its configuration. Define this complete update set before work begins, not only the target framework version.
Record a reliable baseline first
A baseline is the last known configuration and result used for comparison. A green pipeline alone is insufficient. Record the application and test commits, exact command, dependency lockfile, runtime, operating system or CI image, browsers, drivers, concurrent worker count and retry configuration.
On the original configuration, run the critical scenarios and full suite over the scope that will assess the update. Retain the report, initial failures, duration and tests that passed only after a retry. Mark existing intermittent failures, or they may later be blamed on the update.
The baseline should also answer four practical questions:
- Which browsers and operating systems are required for a release?
- Which scenarios must pass before the branch can be merged?
- What known failure rate and duration remain acceptable?
- Who decides to roll back if the update does not meet the agreed conditions?
Set these conditions before the first run. The work already invested should not determine the response to a failure.
Prepare a separate branch and a route back
Use a short-lived branch based on a known commit. Keep application changes, new tests and extensive suite refactoring out of it, so a failure can be traced to the product, test or environment.
Commit the package manifest and lockfile. CI should install from that lockfile instead of freely resolving newer transitive dependencies. For containers, record an exact tag or immutable image identifier. Playwright recommends pinning its Docker image and matching its version to the project because a mismatch can prevent browser executables from being found. See the Playwright Docker documentation.
Keep the last working lockfile and CI image. Reverting only the package could leave the old library paired with a new browser or driver, which is not the original build.
Updating Playwright
Read the Playwright release notes between the installed and target versions for API changes, system requirements, default behaviour and browser revisions. Choose the target deliberately. Do not leave an unrestricted latest rule in CI.
Update the package the project uses and generate a new lockfile. Playwright Test usually depends on @playwright/test, while another setup may use playwright. Do not change both when the suite relies on one.
Install the browser builds required by the new package. On Linux CI, npx playwright install --with-deps can include the operating system dependencies. With the official container, align its version with the project rather than download an unrelated build afterwards.
Run one verification job on a clean runner without the old cache. A cache can conceal a missing installation step or retain an old binary. After the clean run passes, restore it with a key derived from the lockfile and platform.
Updating Selenium
Update the Selenium language package and its transitive dependencies first. Compilation or static checks often expose changed APIs before an end-to-end run. For a larger jump, the Selenium upgrade guide covers code preparation, dependencies and removed interfaces.
Check what selects the driver. Selenium Manager ships with Selenium, and the bindings use it when another method does not supply a driver. It detects the installed browser, resolves and downloads a suitable driver, then caches it. A driver in PATH, a directly supplied location or a third-party manager changes this path.
Use one strategy locally and in CI. Let Selenium Manager handle the driver with the same configuration, network access and cache policy, or pin browser and driver together in an image or Grid node. A manual driver hidden in an old image can make CI differ from a laptop.
For remote runs, record the requested session options, known as capabilities, and the Grid address. Add the actual browser, platform and driver if the provider reports them. A client update may work locally but fail when creating a remote session.
Verify in layers instead of relying on one full run
Check package installation and test compilation first. The second layer is a short smoke test that opens every supported browser, loads a controlled page and performs a simple interaction. This quickly distinguishes a browser start-up problem from a failure in a business scenario.
Next, run the critical journeys with the same worker, timeout and retry configuration as the baseline. Run the complete suite in the main CI environment after that, followed by the wider browser and platform matrix. If the suite uses visual comparisons, do not approve new images in bulk. Confirm first that a legitimate rendering change caused the difference, rather than a wrong font, resolution or operating system library.
A green result after a retry is a sign of instability, rather than a clean pass. Compare initial failures, duration and the distribution of errors with the baseline. For a suspicious difference, use the process for comparing local and CI runs.
Diagnose the difference by failure type
An installation or compilation error points towards packages, the runtime or a removed API. Failure to create a session points more towards the browser, driver, system libraries or Grid. A failed selector or assertion may be connected to changed tool behaviour, browser rendering or a real application defect.
Retain a log, screenshot, trace or WebDriver log from the first new failure, depending on what the suite can produce. Repeat only the affected test on both the old and new environments without changing the application or data. If one version change controls the result, you have a useful reproduction. Raising timeouts across the suite, enabling more retries or refreshing every snapshot removes that evidence.
Split a large jump into smaller decisions
Skipping many releases can introduce changes to APIs, browsers, the runtime and operating system at the same time. Plan an intermediate version, or separate the runtime and CI image update from the test tool update. Each intermediate step needs its own green commit and a short record of the repairs it required.
If the old suite relies on an API that has been removed or on an unsupported environment, this is no longer a routine maintenance update. Estimate the required work first and decide whether to repair the existing suite or migrate some scenarios. Increasing version numbers alone will not remove that debt.
A rollback must restore the complete configuration
Agree the rollback trigger in advance. It might be a broken critical journey, an inability to start a supported browser, a breach of the team’s instability threshold or an unacceptable increase in pipeline duration. The rollback must then restore the manifest, lockfile, CI image, browser installation configuration and, where relevant, the driver or Grid image as one set.
After reverting, run the same smoke test and critical scenarios used for the baseline. Keep artefacts from the unsuccessful branch so the next attempt does not start without evidence. A rollback does not replace a repair. It keeps the main branch usable while the team investigates a specific incompatibility.
How to recognise a successful update
The update is complete when the environment can be built on a clean runner, every agreed browser can create a session, and both critical and full tests pass within the defined scope. The result should not depend on newly skipped tests, weaker assertions or more retries. The report should show the versions that actually ran, and the team must be able to recreate the same configuration from the repository.
On the next update, the team will no longer have to rediscover what to pin, verify and retain for a rollback. The change can be smaller and follow the same process. If the suite lacks a reliable baseline or its environment cannot be recreated, contact us. We can first separate suite defects from differences in tools and infrastructure.