Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 8 additions & 9 deletions .claude/skills/playwright-roll/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ new=$(cat scripts/DRIVER_VERSION)

List the upstream commits between the two commits that changed a path the Java client depends on:

- `docs/src/api/` — the source of `api.json`. A new or removed method or option, or a changed `langs:` filter, comes from here.
- `docs/src/api/` — the input of the API generator. A new or removed method or option, or a changed `langs:` filter, comes from here.
- `packages/playwright-core/src/client/` — the JS client. The Java client is a port of it.
- `packages/isomorphic/` — selector engines, locator generation and parsing, and the aria snapshot code. The client and the server share this code. A change here can change client helpers such as `getByRoleSelector`.
- `packages/playwright/src/matchers/matchers.ts` — the assertion methods. A change here is usually a new option of `LocatorAssertions` or `PageAssertions`.
Expand Down Expand Up @@ -108,26 +108,25 @@ Key translation rules:

After running `./scripts/roll_driver.sh`, the build often fails because the generated Java interfaces reference new types or methods that the generator doesn't know how to handle yet, and the `*Impl` classes don't implement new interface methods.

### ApiGenerator.java fixes (tools/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java)
### API generator fixes (scripts/generate_java_api.mts)

The generator has hardcoded lists that control which imports are added to each generated file. When new classes appear in the API, add them to the relevant lists in `Interface.writeTo`:
The generator has hardcoded lists that control which imports are added to each generated file. When new classes appear in the API, add them to the relevant lists in `INTERFACE_IMPORTS`:
- `options.*` import list — add new classes that use types from the options package
- `java.util.*` import list — add new classes that use `List`, `Map`, etc.
- `java.util.function.Consumer` list — add new classes with `Consumer`-typed event handlers

Type mapping: when JS-only types (like `Disposable`) are used as return types in Java-compatible methods, add a mapping in `convertBuiltinType`. For example, `Disposable` → `AutoCloseable`.
Type mapping: when JS-only types (like `Disposable`) are used as return types in Java-compatible methods, add a mapping in `BUILTIN_TYPES`. For example, `Disposable` → `AutoCloseable`.

Event handler generation: events with `void` type generate invalid `Consumer<void>`. Handle this case in `Event.writeListenerMethods` by emitting `Runnable` instead.

Type names: give every new object type an explicit alias upstream. When a roll brings in a new object type (an option or return value written as `<[Object]>` in `docs/src/api/`), it should usually have its own `* alias: <Name>` line. Without one, each language's generator makes up a name, and the Java one can be vague (e.g. `Style`) or differ between Java and .NET.
- Prefer a plain `alias:` so every language gets the same name. Use `alias-java:` / `alias-csharp:` only when a language really needs a different name.
- Add the aliases in a small upstream docs PR (e.g. microsoft/playwright#43164, `Style` → `ScreencastActionStyle`). Don't special-case names in `ApiGenerator`.
- Add the aliases in a small upstream docs PR (e.g. microsoft/playwright#43164, `Style` → `ScreencastActionStyle`). Don't special-case names in the generator.
- After the upstream change lands, roll to a driver that includes it. Don't hand-edit the generated files.

After editing the generator, recompile and re-run it:
After editing the generator, re-run it. Node.js runs the TypeScript file as is:
```
mvn -f tools/api-generator/pom.xml compile -q
mvn -f tools/api-generator/pom.xml exec:java -Dexec.mainClass=com.microsoft.playwright.tools.ApiGenerator
node scripts/generate_java_api.mts .upstream
```

### Impl class fixes (playwright/src/main/java/com/microsoft/playwright/impl/)
Expand Down Expand Up @@ -161,7 +160,7 @@ Common patterns:

## Rebuilding the driver modules after a roll

`./scripts/roll_driver.sh` does the full roll. It moves `scripts/DRIVER_VERSION` to the new commit. It builds the driver from `.upstream/` into `driver/src/main/resources/driver/package/` and `driver-bundle/src/main/resources/driver/<platform>/`. It generates `api.json` and the Java interfaces, and it updates the README. If all steps pass, the next `mvn` command uses the new driver.
`./scripts/roll_driver.sh` does the full roll. It moves `scripts/DRIVER_VERSION` to the new commit. It builds the driver from `.upstream/` into `driver/src/main/resources/driver/package/` and `driver-bundle/src/main/resources/driver/<platform>/`. It generates the Java interfaces from the upstream docs, and it updates the README. If all steps pass, the next `mvn` command uses the new driver.

If a step fails, the script stops before Maven installs the new driver. The most frequent cause is the API generator, which fails on a new type (see *Fixing generator and compilation errors*). After that, the test JVM loads the **old** driver from `target/classes` or from the installed jar, although the source resources already hold the new driver.

Expand Down
2 changes: 0 additions & 2 deletions .github/workflows/verify_api.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,12 @@ on:
- release-*
paths:
- 'scripts/*'
- 'api-generator/*'
pull_request:
branches:
- main
- release-*
paths:
- 'scripts/**'
- 'api-generator/**'
jobs:
verify:
timeout-minutes: 30
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Paths such as `~/code/playwright` in this file assume that you check the repos o
- **The driver.** The Java client talks to the Node.js driver. The driver is the `playwright-core` package of `microsoft/playwright`. We build it from source at the commit in `scripts/DRIVER_VERSION`. `scripts/build_driver.sh` clones `microsoft/playwright` into `.upstream/` (gitignored), checks out that commit, builds it and puts the package into `driver/src/main/resources/driver/package/`. Do not edit, commit or switch branches in `.upstream/`. `scripts/roll_driver.sh` moves the commit: to the tip of upstream `main`, to the tip of an upstream `release-1.X` branch, or to an exact commit. We do not use the published npm packages or their versions. `git show v1.X.0:scripts/DRIVER_VERSION` prints the upstream commit of a release. For releases up to 1.65, it prints the `playwright-core` version of the driver.
- **Upstream code.** In `.upstream/`, at the commit of the driver, or in `~/code/playwright`, which may be ahead of it: the client in `packages/playwright-core/src/client/`, the API docs in `docs/src/api/`, the tests in `tests/page/` and `tests/library/`. Its `AGENTS.md` says how to build it and run a test.
- **Where a bug is.** When the same calls fail in a Node.js test upstream too, the cause is in the driver or a browser, and the fix lands in `microsoft/playwright`. When Node.js passes, the bug is in the Java client: compare the `*Impl.java` with its JavaScript counterpart, and fix it here.
- **The generated API.** `scripts/generate_api.sh` runs `utils/doclint/generateApiJson.js` of `.upstream/`, and `tools/api-generator` writes every interface and options class in `playwright/src/main/java/com/microsoft/playwright/`, `options/` and `assertions/`. Only `CLI.java`, `PlaywrightException.java`, `TimeoutError.java`, `assertions/PlaywrightAssertions.java` and the `package-info.java` files there are written by hand. Never edit a generated file: the next roll reverts it. A missing method or option is a change to `docs/src/api/` upstream.
- **The generated API.** `scripts/generate_api.sh` runs `scripts/generate_java_api.mts`. It parses `docs/src/api/*.md` of `.upstream/` with the upstream parser (`utils/doclint/api_parser.js`) and writes every interface and options class in `playwright/src/main/java/com/microsoft/playwright/`, `options/` and `assertions/`. Only `CLI.java`, `PlaywrightException.java`, `TimeoutError.java`, `options/Annotate.java`, `options/BindingCallback.java`, `options/BrowserChannel.java`, `options/FunctionCallback.java` and the `package-info.java` files there are written by hand. Never edit a generated file: the next roll reverts it. A missing method or option is a change to `docs/src/api/` upstream.

## Build and test

Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ with a `@Fixture` method reading its `@Parameter` field to run the same tests wi

### Generating API

Public Java API is generated from api.json, which is generated from `.upstream/`, the `microsoft/playwright` checkout at the commit in [scripts/DRIVER_VERSION](scripts/DRIVER_VERSION) that the driver is built from (run `scripts/build_driver.sh` first). Set `PW_SRC_DIR` to generate from another `microsoft/playwright` checkout instead, to try a change to the upstream docs; the committed files must come from `.upstream/`. To regenerate Java interfaces for the current driver run:
Public Java API is generated by [scripts/generate_java_api.mts](scripts/generate_java_api.mts) from the API docs (`docs/src/api/*.md`) in `.upstream/`, the `microsoft/playwright` checkout at the commit in [scripts/DRIVER_VERSION](scripts/DRIVER_VERSION) that the driver is built from (run `scripts/build_driver.sh` first). Set `PW_SRC_DIR` to generate from another `microsoft/playwright` checkout instead, to try a change to the upstream docs; the committed files must come from `.upstream/`. The generator is a TypeScript file that Node.js runs as is, so it needs Node.js 22.18 or newer. To regenerate Java interfaces for the current driver run:

```bash
./scripts/generate_api.sh
Expand Down
18 changes: 9 additions & 9 deletions scripts/generate_api.sh
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ cd "$(dirname "$0")/.."

DRIVER_VERSION=$(head -1 ./scripts/DRIVER_VERSION)

# The script generates api.json from .upstream/. This is the microsoft/playwright checkout
# at the commit in scripts/DRIVER_VERSION. scripts/build_driver.sh makes it.
# The script generates the API from the docs in .upstream/ (docs/src/api/*.md). This is the
# microsoft/playwright checkout at the commit in scripts/DRIVER_VERSION. scripts/build_driver.sh makes it.
# To try a change to the upstream docs or to the generator, set PW_SRC_DIR to a different
# checkout. Do not commit files that come from PW_SRC_DIR: CI generates the files again
# from .upstream/ and fails if they are different.
Expand All @@ -24,14 +24,14 @@ else
fi
fi

echo "Updating api.json from $UPSTREAM_DIR"
API_JSON_MODE=1 node "$UPSTREAM_DIR/utils/doclint/generateApiJson.js" \
> ./tools/api-generator/src/main/resources/api.json

mvn compile -f ./tools/api-generator --no-transfer-progress
# Node.js runs the TypeScript file of the generator as is. Older versions cannot.
if ! node -e 'process.exit(process.features.typescript ? 0 : 1)'; then
echo "The API generator needs Node.js 22.18 or newer, got $(node --version)"
exit 1
fi

echo "Regenerating Java interfaces"
mvn exec:java --f ./tools/api-generator -D exec.mainClass=com.microsoft.playwright.tools.ApiGenerator
echo "Regenerating Java interfaces from $UPSTREAM_DIR"
node ./scripts/generate_java_api.mts "$UPSTREAM_DIR"

# The protocol types are generated last: they avoid names of the public API types generated above.
# utils/protocol_spec.js needs the 'yaml' package. .upstream/ has it after scripts/build_driver.sh.
Expand Down
Loading
Loading