PL

playwright-roll

Automates the process of rolling Playwright Python drivers to newer versions by porting API changes and updating generated code.

Install

mkdir -p .claude/skills/playwright-roll && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/2008" && unzip -o skill.zip -d .claude/skills/playwright-roll && rm skill.zip

Installs to .claude/skills/playwright-roll

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Roll Playwright Python to a new driver version. Walks the upstream `docs/src/api/` commit range, ports each public-API change, suppresses the rest in `expected_api_mismatch.txt`, regenerates the typed surface, and adds tests.
225 charsno explicit “when” trigger
Advanced

Key capabilities

  • →Port public API changes from upstream
  • →Suppress API mismatches in documentation
  • →Regenerate typed surface wrappers
  • →Introspect Python implementation classes
  • →Verify API surface against api.json

How it works

Walks the upstream commit range, ports API changes, suppresses non-Python changes in mismatch files, and regenerates the typed surface.

Inputs & outputs

You give it
Upstream commit range
You get back
Updated Python wrapper classes

When to use playwright-roll

  • →Upgrading Playwright driver version
  • →Syncing Python wrapper classes with new API definitions
  • →Updating tests for new Playwright releases

About this skill

Rolling Playwright

Read AGENTS.md first. A roll moves DRIVER_VERSION to a new upstream commit and ports everything that changed in between.

1. Pin

python scripts/upstream.py pin main      # or a branch, a tag, a commit
python scripts/update_node_version.py
old=$(git show HEAD:DRIVER_VERSION)
new=$(cat DRIVER_VERSION)

2. Generate

./scripts/update_api.sh
mypy playwright

The mypy errors are the to-do list: new members, options and protocol parameters that _impl/ does not have yet. Until they are ported, the client may not work with the new driver. To see what changed in the public API:

git show HEAD:playwright/async_api/_generated.py > /tmp/old.py
python scripts/codegen/compare_api.py /tmp/old.py playwright/async_api/_generated.py --show all

3. Build

python -m build --wheel
playwright install chromium firefox webkit

4. Port

python scripts/upstream.py changes

It lists each changed upstream file with the Python file to port it to. For each one, read git -C .upstream diff $old $new -- <file> and port it hunk by hunk:

  • client code: into the module it names; (no Python port yet) is a new module;
  • tests: into the async and the sync file it names. New test names come from python scripts/check_test_registry.py --missing <id>;
  • test assets and snapshot images: copy them to the place it names;
  • the "Generated" group: step 2 did it.

Changes in the server or in the injected scripts need nothing: they come with the new driver. A test marked xfail(reason="driver: ...") may pass now; remove the mark then.

Run each changed test file on the three browsers. Then run mypy playwright until it is clean.

5. Check

./test.sh
python scripts/update_versions.py        # the browser versions in README.md
./scripts/lint.sh                        # last: the roll is done when it passes

A failure in a file that the roll did not change may be a flake, or older than the roll. Find out which, and say so in the PR.

Title the PR chore: roll Playwright to <version> (<first 10 characters of $new>), with the version from .upstream/packages/playwright-core/package.json. In the description, list what you ported and what is left, and put the output of python scripts/upstream.py log in a <details> block. The roll workflow adds that list itself.

When it breaks

  • missing ... argument, or Protocol violations at the end of a test: a protocol change that the client does not follow yet. Port its hunk.
  • timeout: expected float, got undefined at launch: playwright/driver/ is older than the pin. Build again.
  • .upstream/ is not at ...: python scripts/upstream.py checkout.

When not to use it

  • →When the Playwright driver version is not being updated

Prerequisites

Python 3.10+Nearby microsoft/playwright checkout

Limitations

  • →Requires manual classification of API changes
  • →Dependent on upstream api.json accuracy

How it compares

Automates the synchronization of hand-written Python wrappers with upstream API definitions using introspection and diffing.

Compared to similar skills

playwright-roll side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
playwright-roll (this skill)25moReviewAdvanced
adk-engineer34moReviewAdvanced
unit-testing-test-generate27moReviewIntermediate
api-test-generator11yReviewIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

More by microsoft

View all by microsoft →

Search skills

Search the agent skills registry