driver-bump
Skill166 starsChanged 6 days agoApache-2.0View on GitHub
Runbook for moving the bundled Playwright driver to a new version in playwright-rust. Covers how to establish the real delta (the release notes are not it), parity with playwright-python, which files move, the trace fixture, and the gates. Use when a "Driver bump" issue opens, when asked to bump or roll Playwright, or before touching `PLAYWRIGHT_VERSION` in `build.rs`.
In this repository5 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- doctest-conventionsSkill
- release-processSkill
- supply-chainSkill
- playwright-rs-usageSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 62
Check reach first: the crate has an Electron protocol object but no launch API, so Electron fixes do not reach it.
- Very specific: line 108
Leave alone: the README badge and PLAYWRIGHT_RELEASED in hero.rs (both track crates.io and move at release), and historical mentions in …
- Very specific: line 136
If the trace format moved, playwright-rs-trace releases with playwright-rs, and the release commit raises both of the crate's requirements …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Driver bump
The crate pins one Playwright driver (PLAYWRIGHT_VERSION in
crates/playwright/build.rs) and speaks its JSON-RPC protocol. A bump is
small in the diff and large in what it can break, because the driver
drops parameters it does not recognize instead of rejecting them. A
renamed parameter therefore turns a feature off with the whole suite
green. Past releases have done exactly that:
- 1.58 removed the
devtoolslaunch option, which then did nothing. - 1.63 renamed every
tracingStartcapture parameter, and traces came out empty. - 1.64 took a request's
idverbatim as the trace call id, which turned the crate's integer ids intoUnknowntrace actions, and moved the trace format to v10. Neither was in the release notes.
So the job is to establish the delta first, then move the version.
1. Establish the delta
Compare the old and new tags across four sources. Each catches something the others miss.
- The protocol spec. Move
PLAYWRIGHT_VERSION, runcargo xtask sync-protocol-spec, and readgit diff protocol-specwith context, so events, initializers andinternal: truemarkers count as well as added and removed lines. If onlyDRIVER_VERSIONchanges, the wire contract did not move. The sync needs no driver download. - The public API.
docs/src/api/*.mdin the Playwright monorepo (since: vX.Yentries) andtypes/types.d.tsin the publishedplaywright-core. - The implementation.
packages/playwright-core/src/clientandsrc/server, for behavior the spec does not show: the dispatcher, the trace recorder, Chromium switches, selector engines. - playwright-python. Its roll commit and the fixes around it on the
matching
release-X.Ybranch (andmainfor a minor). Its new tests are the behavior spec for ours. It also pins the Node version the driver expects; match it.
For a patch release, gh api repos/microsoft/playwright/compare/vA...vB
lists the cherry-picks and files in one call, and is usually the whole
delta. Check whether packages/playwright-core/browsers.json is in the file
list: if not, the browser builds are unchanged.
Then sort what you found:
- Something the crate sends changed (renamed or removed command or
parameter): fix it in the bump commit, or the bump ships a silent
regression.
cargo xtask verify-protocol-methodscatches a removed command name, not a renamed parameter. - An upstream fix that reaches a surface the crate exposes: port the
upstream regression test, and show it fails on the old pin and passes on
the new one. The red run on the old pin is the evidence the bump fixes
something for Rust callers; without it the CHANGELOG line is a guess.
Check reach first: the crate has an
Electronprotocol object but no launch API, so Electron fixes do not reach it. Port the upstream test server's behavior as it is, fallbacks and fixed URLs included, even where one looks unreachable on macOS: upstream's tests run on every platform, and Windows Chromium can omit request headers that macOS sends. A test that may differ on Windows can be proved before it reachesmainwithgh workflow run test.yml --ref <branch>. - New public API: a minor bump's new surface goes into a just-in-time
plan (
docs/implementation-plans/vX.Y-playwright-A.B.md), one slice per feature, landed after the bump. The 1.64 plan is the worked example. - Behavior changes callers will notice (visibility rules, dropped OS
support such as WebKit on macOS 14 in 1.59, codec changes): name them in
the CHANGELOG entry, under
### Breaking Changesif they are.
2. Move the version
cargo xtask verify-driver-version lists every reference that disagrees
with build.rs, so run it after the edit and fix what it names. As of
1.65.0 the set is:
crates/playwright/build.rs(PLAYWRIGHT_VERSION)crates/playwright/src/build_support/driver_urls.rs:NPM_CORE_INTEGRITY, the version and itsnpm view playwright-core@<version> dist.integrity. The assembler refuses a download that does not match, and the unit tests fail until the pin names the new version. WhenNODE_VERSIONmoves too, replaceNODE_ARCHIVE_SHA256's version and all six rows from that release'sSHASUMS256.txt, aftergpgv --keyring pubring.kbx SHASUMS256.txt.sig SHASUMS256.txtpasses with the keyring fromnodejs/release-keys(gpg/pubring.kbx).crates/playwright/tests/playwright_version_test.rscrates/playwright/src/protocol/root.rs: the note that thesdkLanguageenum was re-checked. Re-check it (it has never hadrust) before moving the version in the comment..github/workflows/{test,release,pages}.yml: browser cache keyscrates/site/src/components/hero.rs(PLAYWRIGHT_DEVonly) andcrates/site-e2e/tests/landing_page.rscrates/playwright-rs-trace/src/lib.rsandtests/parse_fixture.rs, which name the driver that recorded the fixture. Do not just edit the string: re-record withcargo run --package xtask --release -- regenerate-trace-fixture(it drives Chromium, socargo runas the first token, outside the sandbox) and check the header'sversionandplaywrightVersion. If the trace format moved, keep the old recording asbasic-v<N>.trace.zipand teach the parser the new one, as 1.64 did.docs/architecture/model.c4picks up the trace crate's doc comment: runasbuilt survey.
Leave alone: the README badge and PLAYWRIGHT_RELEASED in hero.rs (both
track crates.io and move at release), and historical mentions in
CHANGELOGs, plans and the site's feature cards.
3. Gates
cargo xtask verify-driver-version,sync-protocol-spec --check,verify-protocol-methods,verify-changelog-linksscripts/check-driver-digests.sh, which compares the new pins with what npm and nodejs.org publish (it needs both hosts, so outside the sandbox or with them allowed)- The default lane and doctests locally; the Firefox, WebKit and stress
lanes (
--run-ignored ignored-only) locally on a minor bump, since a browser build changed - fmt and clippy for
crates/siteandcrates/site-e2eby manifest path, because the badge lives there and workspace runs miss them asbuilt check- Linux and Windows are CI's. A new cache key means a cold browser cache on the first run of each workflow.
4. Record it
- A
### Changedentry incrates/playwright/CHANGELOG.md[Unreleased]: old and new version, browser builds, every change that reaches a Rust caller, and a sentence on the protocol diff. - The commit closes the issue
upstream-playwright-check.ymlopened (Closes #N), and the body says what the delta was, not which files moved. - If the trace format moved,
playwright-rs-tracereleases withplaywright-rs, and the release commit raises both of the crate's requirements on it (see the release-process skill).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

