Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
chore(docs): replace render_release_notes.mjs with a release notes skill (#43552)
Yury Semikhatsky4ba650cabb9e
diff --git a/.claude/skills/playwright-release-notes/SKILL.md b/.claude/skills/playwright-release-notes/SKILL.mdnew file mode 100644index 0000000000..e513d88698--- /dev/null+++ b/.claude/skills/playwright-release-notes/SKILL.md@@ -0,0 +1,156 @@+---+name: playwright-release-notes+description: Write the release notes for a Playwright release - the Node.js notes in docs/src/release-notes-js.md together with the Python, Java and .NET translations, and the GitHub markdown for each language's release. Use when asked to write, translate or publish release notes.+---++# Release notes++In this skill, `1.xx` is the release (for example `1.64`).++Every release has a `## Version 1.xx` section in four files in `docs/src/`:++| Language | Notes | Docs base URL | GitHub release in |+|---|---|---|---|+| Node.js | `release-notes-js.md` | `https://playwright.dev/docs/` | `microsoft/playwright` |+| Python | `release-notes-python.md` | `https://playwright.dev/python/docs/` | `microsoft/playwright-python` |+| Java | `release-notes-java.md` | `https://playwright.dev/java/docs/` | `microsoft/playwright-java` |+| .NET | `release-notes-csharp.md` | `https://playwright.dev/dotnet/docs/` | `microsoft/playwright-dotnet` |++Write the Node.js notes and the three translations in the same PR, so every language has its notes when it starts its release. The language repos then add only their own significant changes, and each one writes its GitHub release from its section (step 3).++## 1. Node.js notes++In `docs/src/release-notes-js.md`, add a `## Version 1.xx` section above the previous version, and use previous versions as a guide:++- Highlights come first, each with an emoji heading and a short sample. Ask teammates for help with them.+- Then `### New APIs` with `####` groups, `### Breaking Changes ⚠️`, `### Announcements` and `### Browser Versions`. Print the browser versions with `node utils/print_versions.js`.+- Refer to APIs with docs link macros: `` [`method: Page.frameLocator`] ``, `` [`property: Page.webmcp`] ``, `` [`event: Page.dialogClosed`] ``, `` [`option: Tracing.start.ariaSnapshots`] ``, `[Locator]`. Each language's docs show them with that language's names.+- Link other docs pages with relative paths: `[test locks](./test-parallel.md#test-locks)`.++## 2. Python, Java and .NET translations++In each of `release-notes-python.md`, `release-notes-java.md` and `release-notes-csharp.md`, add a `## Version 1.xx` section above the previous version. Translate it from the Node.js section. Compare the `Version 1.63` sections of the files to see what past translations dropped and changed.++For every language:++- Keep the structure: highlights with emoji headings, `### New APIs` with `####` groups, `### Breaking Changes ⚠️`, `### Announcements` and `### Browser Versions`.+- Remove what the language does not have:+ - the test runner: `@playwright/test`, `test.*`, config, fixtures, projects, reporters and `npx playwright test` options+ - UI mode, the HTML report, component testing and the VS Code extension+ - TypeScript-only features (generics, JSX, `tsconfig`) and `devices` descriptors+ - every API whose `langs` excludes the language (`python`, `java`, `csharp`). Check `langs` in `docs/src/api/`; options shared between methods are defined in `docs/src/api/params.md`.+- Use the language's API where it differs from Node.js:+ - A language-specific option has its own `langs`. For example, `recordVideoFps` is `langs: csharp, java, python`, while Node.js has `recordVideo.fps`.+ - `alias-<lang>` renames a member, e.g. `alias-java: isVisible` for `LocatorAssertions.toBeVisible`.+ - The generated APIs in sibling checkouts confirm the names: `../playwright-python/playwright/sync_api/_generated.py`, `../playwright-java/playwright/src/main/java/com/microsoft/playwright/` and `../playwright-dotnet/src/Playwright/API/Generated/`.+- When a Node.js sample shows a library feature through `playwright.config.ts`, show the API call instead. For example, the 1.64 video config became calls to `Screencast.start` and `Screencast.showActions`.+- Keep API links as docs link macros, and link the language's own option where it differs (`` [`option: Browser.newContext.recordVideoFps`] ``). In plain text, use the language's names.+- A relative link must point to a page that exists in the language: `*-js.md` pages are Node.js only. `npm run doc` reports broken links for each language.+- Do not add changes that only a language port made. The language repo adds those to its notes.++Rewrite code samples in each language's style. The `infra` workflow checks the syntax of `python`, `java` and `csharp` snippets.++### Python++- Use the sync API: `page.get_by_role("button").click()`. Use snake_case names and Python values (`True`, `False`, `None`).+- Options become keyword arguments: `page.get_by_role("button", name="Save")`. Objects and arrays become dicts and lists: `size={"width": 1920, "height": 1080}`.+- Aria roles and other string values stay strings: `"button"`, `"ai"`.+- Events: `page.on("dialogclosed", handler)`. Assertions: `expect(locator).to_have_text([...])`. Print with `print(...)`.+- Use the `alias-python` names: `route.continue_()`, `locator.or_()`, `page.expect_request()`.+- Commands: write `playwright install`, not `npx playwright install`.++### Java++| Node.js | Java |+|---|---|+| `await page.goto('...')` | `page.navigate("...");`: no `await`, double quotes, semicolons, typed locals (`Locator dialog = ...`) |+| `page.getByRole('button', { name: 'Save' })` | `page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Save"))` |+| options object `{ path: 'video.webm', fps: 60 }` | options builder `new Screencast.StartOptions().setPath(Paths.get("video.webm")).setFps(60)` |+| object literal `{ name: 'session-id', value: '42', url }` | value class `new Cookie("session-id", "42").setUrl(url)` |+| `['a', 'b']`, `{ a: 2 }` | `Arrays.asList("a", "b")`, `Map.of("a", 2)`; `new String[] {"a", "b"}` for assertion arguments |+| property `page.webmcp`, `context.tracing` | getter `page.webmcp()`, `context.tracing()` |+| event `page.on('dialogclosed', handler)` | `page.onDialogClosed(handler)` |+| `expect(locator).toHaveText(...)` | `assertThat(locator).hasText(...)`. Likewise `toBeX` → `isX`, `toHaveX` → `hasX`, `toContainX` → `containsX`, `toMatchX` → `matchesX` |+| `route.continue()` and other members with `alias-java` | the alias, e.g. `route.resume()` |+| `npx playwright install --no-remove` | `mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --no-remove"` |+| "array", `undefined`, `'ai'` in prose | "list", `null`, `"ai"` |++### .NET++| Node.js | .NET |+|---|---|+| `await page.goto('...')` | `await page.GotoAsync("...");`: PascalCase members, `Async` suffix on async methods, `var` locals, double quotes, semicolons |+| `page.getByRole('button', { name: 'Save' })` | `page.GetByRole(AriaRole.Button, new() { Name = "Save" })` |+| options object `{ path: 'video.webm', fps: 60 }` | options initializer `new() { Path = "video.webm", Fps = 60 }` |+| nested object `size: { width: 1920, height: 1080 }` | `Size = new() { Width = 1920, Height = 1080 }` |+| object literal `{ name: 'session-id', value: '42', url }` | `new Cookie { Name = "session-id", Value = "42", Url = url }` |+| `['a', 'b']`, free-form object `{ a: 2 }` | `new[] { "a", "b" }`, anonymous object `new { a = 2 }` |+| string-literal union value `'ai'`, `'button'` | enum member `AriaSnapshotMode.Ai`, `AriaRole.Button` |+| property `page.webmcp`, `context.tracing` | property `page.Webmcp`, `context.Tracing` |+| event `page.on('dialogclosed', handler)` | `page.DialogClosed += (_, dialog) => { ... };` |+| `expect(locator).toHaveText(...)` | `await Expect(locator).ToHaveTextAsync(...);` |+| `console.log(x)` | `Console.WriteLine(x);` |+| members with `alias-csharp` | the alias, e.g. `page.request` → `page.APIRequest` |+| union-typed option, e.g. `httpCredentials` as a list | one property per type, e.g. `HttpCredentialsList` |+| `npx playwright install --no-remove` | `pwsh bin/Debug/netX/playwright.ps1 install --no-remove` |+| option names in prose (`fontSize`), `undefined` | `FontSize`, `null` |++Open one PR for all four files, titled `docs: release notes for v1.xx`. After it merges, cherry-pick it to `release-1.xx` with the `playwright-cherry-pick` skill.++## 3. GitHub release markdown++Each repo publishes the GitHub release for its language, with markdown converted from its `## Version 1.xx` section on `release-1.xx`. Convert the notes yourself:++- Leave out the `## Version 1.xx` heading. Move every other heading up one level (`###` becomes `##`, `####` becomes `###`).+- Replace each link macro with a full link: the language's docs base URL from the table at the top, plus the path below. Use the language's name as the link text:++ | Macro | Path after the docs base URL | Node.js | Python | Java | .NET |+ |---|---|---|---|---|---|+ | `[Locator]` | `api/class-locator` | `Locator` | `Locator` | `Locator` | `Locator` |+ | `` [`method: Page.frameLocator`] `` | `api/class-page#page-frame-locator` | `page.frameLocator()` | `page.frame_locator()` | `page.frameLocator()` | `Page.FrameLocator()` |+ | `` [`method: Page.ariaSnapshot`] `` | `api/class-page#page-aria-snapshot` | `page.ariaSnapshot()` | `page.aria_snapshot()` | `page.ariaSnapshot()` | `Page.AriaSnapshotAsync()` |+ | `` [`method: Locator.first`] `` | `api/class-locator#locator-first` | `locator.first()` | `locator.first` | `locator.first()` | `Locator.First` |+ | `` [`property: Page.webmcp`] `` | `api/class-page#page-webmcp` | `page.webmcp` | `page.webmcp` | `page.webmcp()` | `Page.Webmcp` |+ | `` [`event: BrowserContext.dialogClosed`] `` | `api/class-browsercontext#browser-context-event-dialog-closed` | `browserContext.on('dialogclosed')` | `browser_context.on("dialogclosed")` | `browserContext.onDialogClosed()` | `BrowserContext.DialogClosed` |+ | `` [`method: LocatorAssertions.toBeVisible`] `` | `api/class-locatorassertions#locator-assertions-to-be-visible` | `expect(locator).toBeVisible()` | `expect(locator).to_be_visible()` | `assertThat(locator).isVisible()` | `Expect(Locator).ToBeVisibleAsync()` |+ | `` [`option: Page.content.includeShadow`] `` | `api/class-page#page-content-option-include-shadow` | `` `includeShadow` `` | `` `include_shadow` `` | `` `includeShadow` `` | `` `IncludeShadow` `` |+ | `[Playwright MCP](./getting-started-mcp.md)` | `getting-started-mcp` | `Playwright MCP` | `Playwright MCP` | `Playwright MCP` | `Playwright MCP` |++- An image `` becomes `` in every language.++The page is `class-` and the class name in lower case. The anchor is the class and member names in kebab-case, so `APIRequestContext.addCookies` becomes `api-request-context-add-cookies`. Options add `-option-<name>`, and events add `-event-<name>`. Anchors use the names from `docs/src/api/` even where a language renames the member, so Java's `isVisible()` links to `#locator-assertions-to-be-visible`.++The link text follows the language:++- **Node.js:** the class in lower camel case (`page`, `apiRequestContext`, `testConfig`). Methods get `()`, properties none, events become `on('<event in lower case>')`, and assertions start with `expect(locator).`, `expect(page).` or `expect(response).`.+- **Python:** the class and member in snake_case (`browser_context`, `api_request_context`). Methods get `()`. A member is a property, without `()`, if `_generated.py` declares it with `@property`. Events become `on("<event in lower case>")`, and assertions start with `expect(locator).`.+- **Java:** the class in lower camel case and the `alias-java` member name. Methods and properties get `()`, events become `on<Event>()`, and assertions start with `assertThat(locator).`.+- **.NET:** the class without the interface `I` (`Page`, `APIRequestContext`) and the member exactly as the generated `I<Class>.cs` declares it. Async methods take the `Async` suffix and `()`, sync methods get `()`, and properties and events get no parentheses. Assertions start with `Expect(Locator).`.++Check that every link resolves. playwright.dev already documents the release once the Node.js docs roll has landed. It serves minified HTML, so an anchor may appear without quotes (`id=page-webmcp>`):++```bash+grep -oE 'https://playwright\.dev/[^) ]+' <notes-file> | sort -u | while read -r url; do+ page=${url%%#*}+ html=$(curl -sfL "$page") || { echo "MISSING PAGE $url"; continue; }+ if [[ "$url" == *"#"* ]]; then+ anchor=${url#*#}+ grep -qE "id=\"?${anchor}[\" >]" <<<"$html" || echo "MISSING ANCHOR $url"+ fi+done+```++Then scan for anything that wasn't converted, and for stray spaces inside link text (`[Page. DialogClosed]`, `` [`HttpCredentialsList `] ``). The first command applies to every language; then run the one for the language. They should print nothing:++```bash+# every language+grep -nE '\[`(method|property|event|option|param): |\]\(\./|\[[A-Z][A-Za-z]*\]([^(]|$)|\[[A-Za-z_]+\. |\[`[^`]+ `\]' <notes-file>+# Python: camelCase names in link text+grep -nE '\[[a-z_]+\.[a-z_]*[A-Z]|\[`[a-z]+[A-Z]' <notes-file>+# Java: JS-style events, assertions and properties+grep -nE "\.on\('|\b(toBe|toHave|toContain|toMatch)[A-Z]|\bawait\b|\barray\b|\bundefined\b|\[[a-z][A-Za-z]*\.[a-z][A-Za-z]*\]\(" <notes-file>+# .NET: lower-case classes or members, JS-style events+grep -nE "\.on\('|\bundefined\b|\[[a-z][A-Za-z]*\.|\[[A-Z][A-Za-z]*\.[a-z]|\[Expect\([a-z]" <notes-file>+```++If the conversion shows a problem in the notes themselves, such as an API the language does not have or a sample in the wrong style, fix the notes too (step 2). Otherwise the problem stays on playwright.dev.diff --git a/utils/doclint/linkUtils.js b/utils/doclint/linkUtils.jsindex 86372398b9..ec9763ff45 100644--- a/utils/doclint/linkUtils.js+++ b/utils/doclint/linkUtils.js@@ -14,8 +14,6 @@* limitations under the License.*/-/** @typedef {'Types'|'ReleaseNotesMd'} OutputType */-// @ts-checkconst toKebabCase = require('lodash/kebabCase.js')const Documentation = require('./documentation');@@ -53,10 +51,9 @@ function createClassMarkdownLink(languagePath, clazz) {/*** @param {string} language- * @param {OutputType} outputType* @returns {Documentation.Renderer}*/-function docsLinkRendererForLanguage(language, outputType) {+function docsLinkRendererForLanguage(language) {const languagePath = languageToRelativeDocsPath(language);return ({ clazz, member, param, option }) => {if (clazz)@@ -68,10 +65,8 @@ function docsLinkRendererForLanguage(language, outputType) {if (option)return createMarkdownLink(languagePath, member, `\`${option.alias}\``, option.name);const className = member.clazz.varName === 'playwrightAssertions' ? '' : member.clazz.varName + '.';- if (member.kind === 'method') {- const args = outputType === 'ReleaseNotesMd' ? '' : renderJSSignature(member.argsArray);- return createMarkdownLink(languagePath, member, `${formatClassName(className, language)}${member.alias}(${args})`);- }+ if (member.kind === 'method')+ return createMarkdownLink(languagePath, member, `${formatClassName(className, language)}${member.alias}(${renderJSSignature(member.argsArray)})`);if (member.kind === 'event')return createMarkdownLink(languagePath, member, `${className}on('${member.alias.toLowerCase()}')`);if (member.kind === 'property')@@ -149,16 +144,10 @@ function renderJSSignature(args) {* @param {string} content* @param {string} languagePath* @param {string} relativePath- * @param {boolean} releaseNotesMode* @returns {string}*/-function renderPlaywrightDevLinks(content, languagePath, relativePath, releaseNotesMode = false) {+function renderPlaywrightDevLinks(content, languagePath, relativePath) {return content.replace(/\[([^\]]+)\]\((\.[^\)]+)\)/g, (match, p1, p2) => {- if (releaseNotesMode && p2.includes('/images/')) {- const url = new URL(p2, `https://github.com/microsoft/playwright/blob/main/docs/src/`);- url.searchParams.set('raw', 'true');- return `[${p1}](${url.toString()})`;- }return `[${p1}](${new URL(p2.replace('.md', ''), `https://playwright.dev${languagePath}/docs${relativePath}/`).toString()})`;});}@@ -166,5 +155,4 @@ function renderPlaywrightDevLinks(content, languagePath, relativePath, releaseNomodule.exports = {docsLinkRendererForLanguage,renderPlaywrightDevLinks,- languageToRelativeDocsPath,}\ No newline at end of filediff --git a/utils/generate_types/index.js b/utils/generate_types/index.jsindex 3a734e0c60..a0aad8dede 100644--- a/utils/generate_types/index.js+++ b/utils/generate_types/index.js@@ -78,7 +78,7 @@ class TypesGenerator {* @returns {Promise<string>}*/async generateTypes(overridesFile) {- this.documentation.setLinkRenderer(docsLinkRendererForLanguage('js', 'Types'));+ this.documentation.setLinkRenderer(docsLinkRendererForLanguage('js'));this.documentation.setCodeGroupsTransformer('js', tabs => tabs.filter(tab => tab.value === 'ts').map(tab => tab.spec));this.documentation.generateSourceCodeComments();diff --git a/utils/render_release_notes.mjs b/utils/render_release_notes.mjsdeleted file mode 100644index 1946f2003e..0000000000--- a/utils/render_release_notes.mjs+++ /dev/null@@ -1,78 +0,0 @@-/**- * Copyright (c) Microsoft Corporation.- *- * Licensed under the Apache License, Version 2.0 (the "License");- * you may not use this file except in compliance with the License.- * You may obtain a copy of the License at- *- * http://www.apache.org/licenses/LICENSE-2.0- *- * Unless required by applicable law or agreed to in writing, software- * distributed under the License is distributed on an "AS IS" BASIS,- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.- * See the License for the specific language governing permissions and- * limitations under the License.- */-// @ts-check--import path from 'path';-import fs from 'fs';--import { parseApi } from './doclint/api_parser.js';-import md, { visitAll } from './markdown.js';-import { renderPlaywrightDevLinks, docsLinkRendererForLanguage, languageToRelativeDocsPath } from './doclint/linkUtils.js';--const __dirname = new URL('.', import.meta.url).pathname;--const PROJECT_DIR = path.join(__dirname, '..');-const documentationRoot = path.join(PROJECT_DIR, 'docs', 'src');--const allowedLanguages = ['js', 'python', 'csharp', 'java'];-const [, , language, version] = process.argv;--if (!allowedLanguages.includes(language) || !version.match(/^\d+\.\d+$/))- throw new Error(`Usage: node ${path.basename(process.argv[1])} <language> <version>\n\nWhere <version> is a version tag without v prefix, e.g. 1.45`);--let documentation = parseApi(path.join(documentationRoot, 'api'));-if (language === 'js') {- documentation = documentation- .mergeWith(parseApi(path.join(documentationRoot, 'test-api'), path.join(documentationRoot, 'api', 'params.md')))- .mergeWith(parseApi(path.join(documentationRoot, 'test-reporter-api')))- .mergeWith(parseApi(path.join(documentationRoot, 'electron-api'), path.join(documentationRoot, 'api', 'params.md')))- .mergeWith(parseApi(path.join(documentationRoot, 'mobile-api'), path.join(documentationRoot, 'api', 'params.md')));-}--documentation.setLinkRenderer(docsLinkRendererForLanguage(language, 'ReleaseNotesMd'));-const content = fs.readFileSync(path.join(documentationRoot, `release-notes-${language}.md`)).toString();-let nodes = md.parse(content);-documentation.renderLinksInNodes(nodes);--{- // Reduce by one heading level- visitAll(nodes, node => {- if (node.type === 'h4')- node.type = 'h3';- else if (node.type === 'h3')- node.type = 'h2';- else if (node.type === 'h2')- node.type = 'h1';- else if (node.type === 'h1')- node.type = 'h0';- });-}--// Find the version heading and use it as a starting point in the output.-{- let foundVersion = false;- visitAll(nodes, node => {- if (node.type === 'h1' && node.text === `Version ${version}`) {- nodes = node.children;- foundVersion = true;- }- });- if (!foundVersion)- throw new Error(`Could not find version ${version} in release notes.\nUsage: node ${path.basename(process.argv[1])} <language> <version>\n\nWhere <version> is a version tag without v prefix, e.g. 1.45`);-}--const output = renderPlaywrightDevLinks(md.render(nodes), languageToRelativeDocsPath(language), '', true);-process.stdout.write(output);