Upgrading Playwright: a practical guide for developers

Introduction

Playwright moves fast. New versions arrive monthly, each bringing performance improvements, bug fixes, and sometimes breaking changes that can trip up teams running production test suites. Upgrading Playwright: a practical guide for developers walks you through the process safely, ensuring your automation stays reliable and current without unexpected downtime.

We've learned this the hard way across multiple projects. Rushing an upgrade, skipping release notes, or updating the package without the browsers can leave your CI/CD pipeline broken for hours. This guide distills the steps we follow every time, from local development through production deployment.

Update the package and browsers together

The most common mistake is updating Playwright's npm package in isolation. The package version and the browser binaries must align. When they don't, you'll see cryptic errors about browser launch failures or API mismatches that waste debugging time.

Always update both at once using the Playwright installer:

npm install @playwright/test@latest
npx playwright install

The first command bumps the package version in your package.json. The second command downloads the matching browser binaries (Chromium, Firefox, WebKit) for your operating system. Running them in sequence ensures consistency.

If you're on a CI system like GitHub Actions or GitLab CI, the pipeline likely runs npm ci (clean install) and then installs browsers separately. That's correct, but make sure your Dockerfile or CI config pins the same versions. Here's what a typical CI step looks like:

// .github/workflows/test.yml
- name: Install dependencies
  run: npm ci

- name: Install Playwright browsers
  run: npx playwright install --with-deps

The --with-deps flag installs system dependencies too, which prevents "library not found" errors on Linux runners. On your local machine, you typically don't need it; the browsers already have their system libraries.

For teams sharing a Docker image across environments, consistency matters even more. If you pin Playwright to version 1.40 in your package.json but the Docker image has browsers from 1.38, your tests will fail only in CI—the worst kind of environment-specific bug. We'll cover Docker specifically in the next section.

Read release notes for breaking changes

Playwright's release notes live in the GitHub repository and are also visible on npm. Before merging an upgrade, spend five minutes scanning them. Breaking changes are rare but real, and catching them early saves rollback drama.

Visit https://github.com/microsoft/playwright/releases and look for the version you're upgrading to. The changelog will call out API removals, default behavior shifts, and deprecations. Here's an example of what to watch for:

v1.45.0 (hypothetical): Removed deprecated page.waitForNavigation(). Use page.waitForLoadState() or Promise.all with page.goto() instead.

If your codebase uses the old API, your tests won't even compile after the update. Catching that in the release notes means you can refactor proactively rather than discovering it after npm install breaks your build.

Common types of breaking changes in Playwright:

• API removals: Methods marked "deprecated" in a previous version are actually removed.
• Default timeout changes: Playwright might reduce default wait times for performance, requiring explicit timeouts in slower test scenarios.
• Selector engine deprecations: XPath or CSS selectors sometimes shift in priority or support.
• Platform support drops: Old OS versions might no longer be supported.

Create a checklist in your team's upgrade runbook. Before updating, scan for any of these patterns in your codebase using grep or your IDE's find-and-replace:

grep -r "waitForNavigation\|goto.*waitFor\|deprecated" tests/

This takes two minutes and prevents merge-day surprises.

Update Docker image tags

If your team runs tests in Docker—and most teams do for CI—you need to update the base image tag to match your Playwright version. Playwright publishes official Docker images at mcr.microsoft.com/playwright. These images include Node.js, Playwright, browsers, and system dependencies pre-installed.

Your Dockerfile might look like this:

FROM mcr.microsoft.com/playwright:v1.45.0-noble

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npm", "run", "test"]

The key is pinning the full tag, including the OS suffix (noble for Ubuntu 24.04). Playwright publishes images for multiple Linux distributions. Using a loose tag like v1.45-noble risks pulling a patch update with unexpected dependencies or changes.

When you upgrade Playwright locally, update the Dockerfile tag too. Then rebuild the image and test it locally before pushing:

docker build -t test-runner:1.45.0 .
docker run test-runner:1.45.0

This catch step prevents pushing broken images to your registry. If your team uses a Docker Compose setup for local testing, update the service there as well:

version: '3.8'
services:
  tests:
    image: mcr.microsoft.com/playwright:v1.45.0-noble
    volumes:
      - .:/app
    working_dir: /app
    command: npm run test

Consistency between local Docker and CI Docker matters. If a developer tests locally on their machine (native Playwright) and CI uses Docker, you might miss environment-specific issues. Many teams standardize on Docker everywhere.

Run the full suite before merging

This sounds obvious but it's the step teams skip under pressure. Always run your complete test suite—not just a smoke test—after an upgrade. New Playwright versions can introduce subtle timing changes, new default behaviors, or stricter element detection that breaks tests that previously passed.

Here's a practical CI workflow after an upgrade PR:

1. Merge the upgrade to a feature branch. Update package.json, run npm install and npx playwright install locally.
2. Commit and push. Your CI pipeline kicks off automatically.
3. Watch the full test run. Don't just look for green/red; scan the logs for timing warnings, deprecated API usage, or retry patterns that changed.
4. Fix any breakages. Update tests if Playwright's behavior changed, or file an issue if you think it's a regression.
5. Merge to main only after all tests pass. If CI is green but you see flakiness patterns, investigate before merging.

We recommend running tests against both old and new versions on a feature branch first, if your schedule allows. Use a workflow matrix in GitHub Actions:

strategy:
  matrix:
    playwright-version: ['1.44.0', '1.45.0']
steps:
  - uses: actions/checkout@v4
  - name: Install Playwright ${{ matrix.playwright-version }}
    run: npm install @playwright/test@${{ matrix.playwright-version }}
  - name: Install browsers
    run: npx playwright install --with-deps
  - name: Run tests
    run: npm run test

This ensures your tests pass on both versions, giving you confidence and an easy rollback path if needed.

Common mistakes

• Updating package.json but forgetting to run npx playwright install. This leaves your local browsers out of sync. Always run both commands.
• Pinning Playwright version in package.json but outdated Docker image. CI fails because the image has mismatched browsers. Automate Docker image updates in your upgrade process.
• Skipping release notes and hitting a breaking change in production. Five minutes of reading saves hours of debugging. Make it a rule.
• Partial test runs before merging. Running only happy-path tests masks flakiness or timing issues that show up in the full suite. Run everything.
• Upgrading multiple dependencies at once. If tests fail after upgrading Playwright, Node.js, and three other packages simultaneously, isolation becomes impossible. Upgrade Playwright alone first, verify stability, then move to other changes.

Key takeaways

• Always update the Playwright package and browsers together using npm install @playwright/test@latest followed by npx playwright install.
• Read release notes for breaking changes before upgrading, especially API removals and default behavior shifts.
• Keep Docker image tags in sync with your local Playwright version; pin full tags, not loose ones like latest.
• Run your full test suite—not just smoke tests—after an upgrade to catch timing or detection issues early.
• Isolate Playwright upgrades from other dependency changes to make troubleshooting easier.