chore: roll driver to 1.65.0-alpha-2026-10-19 (#3273)

Author: pavelfeldman

.claude/skills/playwright-release/SKILL.md

@@ -31,9 +31,9 @@ gh issue list --repo microsoft/playwright-python --state open \
 If any are open, list them for the user and ask whether to continue. Do not
 close or comment on issues.
 
-Check that the driver is rolled. `DRIVER_VERSION` must be the driver for the
-release: a `1.xx.y` build, or a `1.xx.0-beta-…` build from `release-1.xx`, as the
-user says. If it is not, roll with the `playwright-roll` skill. This is often
+Check that the driver is rolled. `DRIVER_VERSION` (`npm=`) must be the driver
+for the release: a `1.xx.y` build, or a `1.xx.0-beta-…` build from `release-1.xx`,
+as the user says, and `rev=` the commit that it is built from. If it is not, roll with the `playwright-roll` skill. This is often
 already done. The roll commit goes into the release commit PR (step 3). When the
 API roll for 1.xx is already on `main`, that PR only moves `DRIVER_VERSION`.
 

.claude/skills/playwright-roll/SKILL.md

@@ -39,37 +39,37 @@ The upstream documentation source of truth is `docs/src/api/*.md` in the playwri
 
 ### 2. Bump the driver pin, download it, and generate api.json
 
+`DRIVER_VERSION` has two lines: `npm=`, the `playwright-core` npm version
+(a release such as `1.62.0`, a beta, or a nightly such as
+`1.65.0-alpha-2026-10-19`), and `rev=`, the `microsoft/playwright` commit that
+the package is built from. npm records that commit:
+
+```sh
+npm view playwright-core@<version> gitHead
+```
+
 The docs walk and codegen read the upstream docs from a `microsoft/playwright`
 checkout at `$PW_SRC_DIR`. **Use a separate checkout that exists only for
-rolls, on the exact release branch you roll to**: `release-<new>`, the
-`major.minor` of the new `DRIVER_VERSION` (the branch has the release's docs
-plus any cherry-picks). Never point `PW_SRC_DIR` at a checkout that someone
-works in: on `main` or a feature branch the docs differ, and the generator
-silently emits that API instead of the release's.
+rolls, at exactly the `rev=` commit.** Never point `PW_SRC_DIR` at a checkout
+that someone works in: on any other commit the docs differ, and the generator
+silently emits that API instead of the driver's. `./scripts/update_api.sh`
+refuses to run when the checkout is not at `rev=` or has local changes.
 
 ```sh
 export PW_SRC_DIR=../playwright-for-python      # the roll checkout, nothing else
 # First roll on this machine: clone it (no npm install needed).
 git clone https://github.com/microsoft/playwright.git "$PW_SRC_DIR"
-# Every roll: move it to the release branch.
+# Every roll: move it to the new rev.
 git -C "$PW_SRC_DIR" fetch origin
-git -C "$PW_SRC_DIR" checkout release-<new>     # e.g. release-1.62
-git -C "$PW_SRC_DIR" merge --ff-only origin/release-<new>
-```
-
-Check the checkout before you generate, and again before you commit:
-
-```sh
-git -C "$PW_SRC_DIR" rev-parse --abbrev-ref HEAD                  # must print release-<new>
-git -C "$PW_SRC_DIR" status --porcelain                           # must print nothing
-git -C "$PW_SRC_DIR" rev-parse HEAD origin/release-<new>          # both lines must be equal
+git -C "$PW_SRC_DIR" checkout --detach <rev>
 ```
 
 Then bump the pins and assemble the driver:
 
 ```sh
-# Edit DRIVER_VERSION (repo root): the playwright-core npm version for the new
-# release, no "v" prefix, e.g.  1.62.0
+# Edit DRIVER_VERSION (repo root), for example:
+#   npm=1.62.0
+#   rev=<npm view playwright-core@1.62.0 gitHead>
 python scripts/update_node_version.py     # refresh NODE_VERSION to the current LTS
 
 source env/bin/activate
@@ -89,32 +89,18 @@ the walk.
 
 ### 3. Identify the commit range
 
-Use the roll checkout at `$PW_SRC_DIR` (from step 2).
-Bring it up to date and ensure release branches/tags are present before walking
-the range:
-
-```sh
-git -C "$PW_SRC_DIR" fetch --tags
-git -C "$PW_SRC_DIR" fetch origin 'release-*:release-*'
-```
-
-There is sometimes no `vX.Y.0` tag for the latest release (the bots cut release branches first and tag later). Anchor on commits, not tags.
-
-The diff range is "every commit on the new release branch since the previous release was cut". Anchor commits:
-
-- **Previous release end**: the `chore: bump version to vX.Y.0-next` commit on `main`. That commit is the first commit *after* the previous release (X.Y-1) was cut. Use its parent (`<sha>~1`) as the lower bound.
-  ```sh
-  git -C "$PW_SRC_DIR" log --all --grep="bump version to v" --oneline | head
-  ```
-- **New release end**: the tip of `release-<new>` (or the matching tag if it exists).
-
-Save the commit list, oldest first, scoped to `docs/src/api/`:
+The range is every commit between the old `rev=` (in `DRIVER_VERSION` before the
+bump) and the new one. Save the commit list, oldest first, scoped to
+`docs/src/api/`:
 
 ```sh
-git -C "$PW_SRC_DIR" log <prev-anchor>~1..release-<new> --oneline --reverse -- docs/src/api > /tmp/roll-<new>-commits.md
+git -C "$PW_SRC_DIR" log <old-rev>..<new-rev> --oneline --reverse -- docs/src/api > /tmp/roll-<new>-commits.md
 ```
 
-A normal roll yields 50–100 commits. If you see 0 or thousands, the range is wrong.
+If the old `DRIVER_VERSION` has no `rev=` line (rolls before the two-line
+format), take the old commit from npm: `npm view playwright-core@<old version>
+gitHead`. A release-to-release roll yields 50–100 commits; a nightly-to-nightly
+roll a handful. If you see thousands, the range is wrong.
 
 Format the file as a markdown checklist and add the standard preamble (status legend, where to look up `api.json` etc.) — see the file from the 1.58→1.59 roll for the template.
 
@@ -266,7 +252,7 @@ Failure modes and fixes:
 | mypy: incompatible argument type in `_generated.py` | The docs type changed, or `_impl/` declares a narrower type. | Match the type in `_impl/`, or fix the docs with a Python-only declaration (`* langs: python`). |
 | generator: `No Python name for the struct at X.y.z` | A new inline `[Object]` with no name in the docs. | Name it in the docs: `` "Name" <[Object]> ``. |
 | generator: `The struct X has different fields at A and B` | Two places in the docs share one struct name, but their fields differ. | Give one place its own name in the docs. |
-| `_generated.py` gains or loses members that the commit walk never mentioned | `PW_SRC_DIR` is not on `release-<new>` (for example on `main` or a feature branch), or is behind `origin/release-<new>`. | Run the checkout checks from step 2, fix the checkout, regenerate. |
+| `_generated.py` gains or loses members that the commit walk never mentioned | `PW_SRC_DIR` is not at the `rev=` commit, or the range of the walk is wrong. | Check out `rev=` (step 2), regenerate, and recompute the range (step 3). |
 | generator: `Unknown docs type "T" at X.y` | A docs type the type table in `generate_api.js` (`toPy`) does not know. | Add it to `toPy`. |
 | generator: `required parameter z follows an optional one` | The docs order params so that Python would need a default before a non-default. | Fix the docs, for example with a Python-only `### param:` or `### option:`, as `select_option(value)` has. |
 | generator: `the entry "…" no longer matches anything; remove it` | An upstream change made a rules entry unnecessary (or renamed what it points at). | Delete it, or re-key it to the new docs name. |
@@ -300,7 +286,7 @@ For each PORT, port the upstream test that covers it, as an async test and a mat
 
 ### 8. Final verification
 
-Repeat the checkout checks from step 2: the committed `_generated.py` must come from `release-<new>`.
+Check that `$PW_SRC_DIR` is still at the `rev=` commit, with no local changes: the committed `_generated.py` must come from it.
 
 ```sh
 pre-commit run --all-files

AGENTS.md

@@ -18,10 +18,10 @@ Python bindings for [Playwright](https://playwright.dev). The Python client talk
   - `_protocol.py` has the parameters of every command. With `PW_CHECK_PROTOCOL=1`, `playwright/_impl/_protocol_check.py` checks each message that the client sends against it. The test suite sets this, and fails a test that sends an unknown command, an unknown or missing parameter, or a value of the wrong type.
 - `scripts/codegen/compare_api.py` — compares two generated files (signatures, annotations, call bodies, docstrings) and lists every difference. Use it to check that a generator change does not change the API.
 - `tests/async/`, `tests/sync/` — pytest suites, ported from the upstream tests. Most new tests are added to the async file with a sync mirror. See [Tests](#tests).
-- `DRIVER_VERSION` — the single source of truth for which Playwright release the driver is assembled from (one line, the `playwright-core` npm version, e.g. `1.61.0`, no `v` prefix). Read by `setup.py`, `scripts/build_driver.py`, and CI. The wheel build downloads `playwright-core` at this version from npm plus the matching Node.js binary and assembles the per-platform bundles — no source build. The version is baked into the staged bundle filenames (`driver/playwright-<version>-<suffix>.zip`), so it doubles as the build cache key.
+- `DRIVER_VERSION` — the single source of truth for which Playwright build the driver is assembled from. Two lines: `npm=<version>`, the `playwright-core` npm version (e.g. `npm=1.61.0`, no `v` prefix), and `rev=<sha>`, the `microsoft/playwright` commit that the package is built from (`npm view playwright-core@<version> gitHead`). Read by `setup.py`, `scripts/build_driver.py`, `scripts/update_api.sh`, and CI (through `setup.py`). The wheel build downloads `playwright-core` at this version from npm plus the matching Node.js binary and assembles the per-platform bundles — no source build. The version is baked into the staged bundle filenames (`driver/playwright-<version>-<suffix>.zip`), so it doubles as the build cache key.
 - `NODE_VERSION` — the Node.js version bundled with the driver (one line, e.g. `24.16.0`). Maintained at roll time by `scripts/update_node_version.py` (latest LTS, mirroring upstream's `utils/build/update-playwright-node.mjs`).
 - `scripts/build_driver.py` — assembles the per-platform driver bundles into `driver/` by downloading the `playwright-core` npm package (`DRIVER_VERSION`) and the official Node.js binaries (`NODE_VERSION`). Fetches `playwright-core` with `npm pack` (needs Node.js/npm on PATH; honours a root `.npmrc`) and the Node.js binaries over plain HTTP; invoked from `setup.py`'s `bdist_wheel` with the target platform's suffix (no arg builds all six).
-- The API docs are **not** shipped in the bundle. `scripts/update_api.sh` reads them from a separate `microsoft/playwright` checkout (`$PW_SRC_DIR`) on the exact release branch for `DRIVER_VERSION`, never from a checkout on `main` or a feature branch. Needed only when regenerating the API, never at runtime.
+- The API docs are **not** shipped in the bundle. `scripts/update_api.sh` reads them from a separate `microsoft/playwright` checkout (`$PW_SRC_DIR`) at the exact commit in `DRIVER_VERSION` (`rev=`), and refuses to run on any other commit or on local changes. Needed only when regenerating the API, never at runtime.
 - `ROLLING.md`, `CONTRIBUTING.md` — human-facing setup and roll docs.
 
 ## Setup

CONTRIBUTING.md

@@ -37,7 +37,7 @@ pip install -r local-requirements.txt
 Build and install drivers:
 
 The driver is assembled from published artifacts — the `playwright-core` npm
-package (version pinned in `DRIVER_VERSION`) and the official Node.js binary
+package (version pinned in `DRIVER_VERSION`, `npm=`) and the official Node.js binary
 (pinned in `NODE_VERSION`). Building a wheel downloads them with `npm pack` and
 plain HTTP, so Node.js/npm must be installed; no git or source build is needed.
 
@@ -77,8 +77,9 @@ For more details look at the [CI configuration](./.github/workflows/ci.yml).
 
 `update_api.sh` generates `playwright/{async,sync}_api/_generated.py` and the
 public TypedDicts in `playwright/_impl/_api_structures.py` from the API docs in
-a separate `microsoft/playwright` checkout on the exact release branch for
-`DRIVER_VERSION` (for example `release-1.64`); point `PW_SRC_DIR` at it. The
+a separate `microsoft/playwright` checkout at the commit in `DRIVER_VERSION`
+(`rev=`, the commit that the `npm=` package is built from); point `PW_SRC_DIR`
+at it. The
 generator is
 `scripts/codegen/generate_api.js`; Python facts that the docs do not contain
 live in `scripts/codegen/python_rules.js`.

DRIVER_VERSION

@@ -1 +1,2 @@
-1.65.0-alpha-1792021904000
+npm=1.65.0-alpha-2026-10-19
+rev=b335271cdc2b57cac2be8ad37c5dd283ac6b8938

ROLLING.md

@@ -11,9 +11,9 @@ pip install -r local-requirements.txt
 pre-commit install
 pip install -e .
 ```
-* change the driver pin in `DRIVER_VERSION` (the `playwright-core` npm version, e.g. `1.61.0`) and refresh `NODE_VERSION`: `python scripts/update_node_version.py`
+* change the driver pin in `DRIVER_VERSION`: `npm=` the `playwright-core` npm version (e.g. `1.61.0`) and `rev=` the commit it is built from (`npm view playwright-core@<version> gitHead`); refresh `NODE_VERSION`: `python scripts/update_node_version.py`
 * download the new driver: `python -m build --wheel` (fetches `playwright-core` via `npm pack` + the matching Node.js binary and assembles the bundle; no source build).
-* generate API from the docs. This needs a separate `microsoft/playwright` checkout used only for rolls, on the exact release branch for the new version (e.g. `release-1.64`), clean and up to date with `origin`: `PW_SRC_DIR=../playwright-for-python ./scripts/update_api.sh`
+* generate API from the docs. This needs a separate `microsoft/playwright` checkout used only for rolls, at the `rev=` commit of `DRIVER_VERSION` and clean (`git -C ../playwright-for-python fetch origin && git -C ../playwright-for-python checkout --detach <rev>`): `PW_SRC_DIR=../playwright-for-python ./scripts/update_api.sh`
 * run `mypy playwright`: every error in `_generated.py` points at an implementation method in `playwright/_impl/` that lacks a new member or option. Implement it there, or record the difference in `scripts/codegen/python_rules.js`.
 * commit changes & send PR
 * wait for bots to pass & merge the PR

playwright/_impl/_cdp_session.py

@@ -44,8 +44,15 @@ def _on_event(self, event: "channels.CDPSessionEventEvent") -> None:
             {key: value for key, value in event.items() if value is not None},
         )
 
-    async def send(self, method: str, params: Optional[Dict]) -> Dict:
-        return (await self._channel.send(method=method, params=params))["result"]
+    async def send(
+        self, method: str, params: Optional[Dict], timeout: Optional[float]
+    ) -> Dict:
+        # No timeout by default, as send() in client/cdpSession.ts.
+        return (
+            await self._channel.send(
+                method=method, params=params, timeout=0 if timeout is None else timeout
+            )
+        )["result"]
 
     async def detach(self) -> None:
         await self._channel.detach()

playwright/async_api/_generated.py

@@ -4622,7 +4622,11 @@ def once(
         return super().once(event=event, f=f)
 
     async def send(
-        self, method: str, params: typing.Optional[typing.Dict] = None
+        self,
+        method: str,
+        params: typing.Optional[typing.Dict] = None,
+        *,
+        timeout: typing.Optional[typing.Union[float, datetime.timedelta]] = None,
     ) -> typing.Dict:
         """CDPSession.send
 
@@ -4632,14 +4636,20 @@ async def send(
             Protocol method name.
         params : Union[Dict, None]
             Optional method parameters.
+        timeout : Union[float, None]
+            Maximum time in milliseconds to wait for the response. Defaults to `0` - no timeout.
 
         Returns
         -------
         Dict
         """
 
         return mapping.from_maybe_impl(
-            await self._impl_obj.send(method=method, params=mapping.to_impl(params))
+            await self._impl_obj.send(
+                method=method,
+                params=mapping.to_impl(params),
+                timeout=to_milliseconds(timeout),
+            )
         )
 
 

playwright/sync_api/_generated.py

@@ -4530,7 +4530,11 @@ def once(self, event: str, f: typing.Callable[..., None]) -> None:
         return super().once(event=event, f=f)
 
     def send(
-        self, method: str, params: typing.Optional[typing.Dict] = None
+        self,
+        method: str,
+        params: typing.Optional[typing.Dict] = None,
+        *,
+        timeout: typing.Optional[typing.Union[float, datetime.timedelta]] = None,
     ) -> typing.Dict:
         """CDPSession.send
 
@@ -4540,6 +4544,8 @@ def send(
             Protocol method name.
         params : Union[Dict, None]
             Optional method parameters.
+        timeout : Union[float, None]
+            Maximum time in milliseconds to wait for the response. Defaults to `0` - no timeout.
 
         Returns
         -------
@@ -4548,7 +4554,11 @@ def send(
 
         return mapping.from_maybe_impl(
             self._sync(
-                self._impl_obj.send(method=method, params=mapping.to_impl(params))
+                self._impl_obj.send(
+                    method=method,
+                    params=mapping.to_impl(params),
+                    timeout=to_milliseconds(timeout),
+                )
             )
         )
 

scripts/build_driver.py

@@ -84,6 +84,21 @@ def read_pin(name: str) -> str:
     return value
 
 
+def read_driver_version() -> str:
+    # DRIVER_VERSION has two lines: npm=<playwright-core version> and
+    # rev=<the microsoft/playwright commit that the package is built from>.
+    pins = dict(
+        line.split("=", 1)
+        for line in read_pin("DRIVER_VERSION").splitlines()
+        if line.strip()
+    )
+    if "npm" not in pins:
+        raise SystemExit(
+            f"DRIVER_VERSION has no npm= line at {REPO_ROOT / 'DRIVER_VERSION'}"
+        )
+    return pins["npm"].strip()
+
+
 def download(url: str, destination: Path) -> None:
     last_error: Exception = RuntimeError("no attempt made")
     for attempt in range(1, 6):
@@ -219,7 +234,7 @@ def assemble(
 
 
 def build(suffixes: Set[str]) -> None:
-    version = read_pin("DRIVER_VERSION")
+    version = read_driver_version()
     node_version = read_pin("NODE_VERSION")
     DRIVER_DIR.mkdir(exist_ok=True)