Playwright pins the browser builds it downloads; what does that buy a team and what does it cost?

"It drives a browser build it ships itself" sounds like an installation detail. For a lead it is a **supply-chain and coverage decision**, because it makes the browser a dependency of your test library rather than a property of the machine. ## What pinning actually means - A Playwright release names specific browser builds; `npx playwright install` downloads them into a version-scoped cache (relocatable with `PLAYWRIGHT_BROWSERS_PATH`). - Those builds carry patches Playwright needs to drive them, so they are not interchangeable with whatever is installed on the host. - Upgrading the library therefore moves the browsers with it. There is no supported "new library, old browser" combination to fall back on. ```bash npx playwright install --with-deps # fetch the builds this library version pins npx playwright --version # the library version is also the browser version ``` ## What pinning buys 1. **Reproducibility.** A laptop, a CI runner and a colleague's rerun all drive the same build. "Works on my machine" stops being a browser-version question. 2. **One less variable in flake triage.** When a test starts failing, the browser did not silently update overnight; something you control changed. 3. **No version matrix to operate.** There is no driver-to-browser compatibility table to keep aligned, and no fleet of machines whose installed browsers drift apart. 4. **Deterministic upgrades.** The browser moves when you decide to move the library, on a change you can review, revert and date. ## What pinning costs - **Coverage gap.** Users run branded, auto-updating builds. Proprietary codecs, DRM playback, enterprise policy, password managers and vendor-specific integrations differ from the bundled build, so a green suite is not evidence about those surfaces. - **Coupled upgrades.** A routine dependency bump changes the rendering engine underneath every test. It deserves a burn-in run, not a rubber stamp. - **You cannot hold a browser back.** Reproducing a defect a user hit on an older browser is awkward, because the build is tied to the library version rather than chosen freely. - **Weight.** Each pinned version means downloads and cache space on every machine and image that runs the suite. - **A lag against the newest release.** You test what the current library pins, which is close to but not identical with what shipped to users this week. ## The escape hatch, and its price The `channel` launch option points Playwright at a stock browser installed on the machine instead of the bundled build: ```typescript import { chromium } from '@playwright/test'; const pinned = await chromium.launch(); // the build this library pins const branded = await chromium.launch({ channel: 'chrome' }); // the installed branded build ``` | | Pinned bundled build | Branded build via `channel` | |---|---|---| | Reproducibility | identical everywhere | depends on what each machine has installed | | Realism | engine behaviour only | branded features, codecs, policy | | Upgrade control | moves with the library | moves when the vendor updates | | Availability | downloaded by the suite | must be installed on the machine or image | That is a straight swap of determinism for realism, which is why it belongs on a small, deliberate slice of the suite rather than everywhere. ## How a lead should decide - **Pin by default.** The bulk of a suite is checking your application, not the browser; determinism is worth more there than branded fidelity. - **Carve out a branded lane** for the journeys that genuinely depend on branded behaviour in a legacy quote flow: document generation, media, print or download paths, policy-restricted enterprise desktops. - **Treat a library upgrade as an engine upgrade.** Schedule it, run the suite twice, and read new failures as possible real behaviour changes before assuming the tests rotted. - **Budget for the cache.** Pinned builds are an artefact your images and machines must carry; make that explicit rather than a surprise on a cold runner. - **Decide who owns the cadence.** Pinning removes drift only if someone is deliberately moving the pin; a suite frozen for a year is reproducibly testing a browser nobody uses.