chore: add release notes for v1.53 (#36196)

mxschmitt · web-flow · commit 2e57a78da8f1 · 2025-06-04T16:10:51.000+01:00
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
@@ -587,6 +587,33 @@ When all steps combined have not finished during the specified [`option: timeout
 Describes the locator, description is used in the trace viewer and reports.
 Returns the locator pointing to the same element.
 
+**Usage**
+
+```js
+const button = page.getByTestId('btn-sub').describe('Subscribe button');
+await button.click();
+```
+
+```java
+Locator button = page.getByTestId("btn-sub").describe("Subscribe button");
+button.click();
+```
+
+```python async
+button = page.get_by_test_id("btn-sub").describe("Subscribe button")
+await button.click()
+```
+
+```python sync
+button = page.get_by_test_id("btn-sub").describe("Subscribe button")
+button.click()
+```
+
+```csharp
+var button = Page.GetByTestId("btn-sub").Describe("Subscribe button");
+await button.ClickAsync();
+```
+
 ### param: Locator.describe.description
 * since: v1.53
 - `description` <[string]>
diff --git a/docs/src/release-notes-csharp.md b/docs/src/release-notes-csharp.md
@@ -4,6 +4,30 @@ title: "Release notes"
 toc_max_heading_level: 2
 ---
 
+## Version 1.53
+
+### Miscellaneous
+
+- New Steps in Trace Viewer: 
+  ![New Trace Viewer Steps](https://github.com/user-attachments/assets/1963ff7d-4070-41be-a79b-4333176921a2)
+- New method [`method: Locator.describe`] to describe a locator. Used for trace viewer.
+  ```csharp
+  var button = Page.GetByTestId("btn-sub").Describe("Subscribe button");
+  await button.ClickAsync();
+  ```
+- `pwsh bin/Debug/netX/playwright.ps1 install --list` will now list all installed browsers, versions and locations.
+
+### Browser Versions
+
+- Chromium 138.0.7204.4
+- Mozilla Firefox 139.0
+- WebKit 18.5
+
+This version was also tested against the following stable channels:
+
+- Google Chrome 137
+- Microsoft Edge 137
+
 ## Version 1.52
 
 ### Highlights
diff --git a/docs/src/release-notes-java.md b/docs/src/release-notes-java.md
@@ -4,6 +4,30 @@ title: "Release notes"
 toc_max_heading_level: 2
 ---
 
+## Version 1.53
+
+### Miscellaneous
+
+- New Steps in Trace Viewer: 
+  ![New Trace Viewer Steps](https://github.com/user-attachments/assets/1963ff7d-4070-41be-a79b-4333176921a2)
+- New method [`method: Locator.describe`] to describe a locator. Used for trace viewer.
+  ```java
+  Locator button = page.getByTestId("btn-sub").describe("Subscribe button");
+  button.click();
+  ```
+- `mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --list"` will now list all installed browsers, versions and locations.
+
+### Browser Versions
+
+- Chromium 138.0.7204.4
+- Mozilla Firefox 139.0
+- WebKit 18.5
+
+This version was also tested against the following stable channels:
+
+- Google Chrome 137
+- Microsoft Edge 137
+
 ## Version 1.52
 
 ### Highlights
diff --git a/docs/src/release-notes-js.md b/docs/src/release-notes-js.md
@@ -6,6 +6,42 @@ toc_max_heading_level: 2
 
 import LiteYouTube from '@site/src/components/LiteYouTube';
 
+## Version 1.53
+
+### Trace Viewer and HTML Reporter Updates
+
+- New Steps in Trace Viewer and HTML reporter: 
+  ![New Trace Viewer Steps](https://github.com/user-attachments/assets/1963ff7d-4070-41be-a79b-4333176921a2)
+- New option in `'html'` reporter to set the title of a specific test run:
+  ```js
+  import { defineConfig } from '@playwright/test';
+
+  export default defineConfig({
+    reporter: [['html', { title: 'Custom test run #1028' }]]
+  });
+  ```
+
+### Miscellaneous
+
+- New option [`option: TestInfo.snapshotPath.kind`] in [`method: TestInfo.snapshotPath`] controls which snapshot path template is used.
+- New method [`method: Locator.describe`] to describe a locator. Used for trace viewer and reports.
+  ```js
+  const button = page.getByTestId('btn-sub').describe('Subscribe button');
+  await button.click();
+  ```
+- `npx playwright install --list` will now list all installed browsers, versions and locations.
+
+### Browser Versions
+
+- Chromium 138.0.7204.4
+- Mozilla Firefox 139.0
+- WebKit 18.5
+
+This version was also tested against the following stable channels:
+
+- Google Chrome 137
+- Microsoft Edge 137
+
 ## Version 1.52
 
 ### Highlights
diff --git a/docs/src/release-notes-python.md b/docs/src/release-notes-python.md
@@ -4,6 +4,30 @@ title: "Release notes"
 toc_max_heading_level: 2
 ---
 
+## Version 1.53
+
+### Miscellaneous
+
+- New Steps in Trace Viewer: 
+  ![New Trace Viewer Steps](https://github.com/user-attachments/assets/1963ff7d-4070-41be-a79b-4333176921a2)
+- New method [`method: Locator.describe`] to describe a locator. Used for trace viewer.
+  ```python
+  button = page.get_by_test_id("btn-sub").describe("Subscribe button")
+  button.click()
+  ```
+- `python -m playwright install --list` will now list all installed browsers, versions and locations.
+
+### Browser Versions
+
+- Chromium 138.0.7204.4
+- Mozilla Firefox 139.0
+- WebKit 18.5
+
+This version was also tested against the following stable channels:
+
+- Google Chrome 137
+- Microsoft Edge 137
+
 ## Version 1.52
 
 ### Highlights
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
@@ -12913,6 +12913,14 @@ export interface Locator {
   /**
    * Describes the locator, description is used in the trace viewer and reports. Returns the locator pointing to the
    * same element.
+   *
+   * **Usage**
+   *
+   * ```js
+   * const button = page.getByTestId('btn-sub').describe('Subscribe button');
+   * await button.click();
+   * ```
+   *
    * @param description Locator description.
    */
   describe(description: string): Locator;
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
@@ -12913,6 +12913,14 @@ export interface Locator {
   /**
    * Describes the locator, description is used in the trace viewer and reports. Returns the locator pointing to the
    * same element.
+   *
+   * **Usage**
+   *
+   * ```js
+   * const button = page.getByTestId('btn-sub').describe('Subscribe button');
+   * await button.click();
+   * ```
+   *
    * @param description Locator description.
    */
   describe(description: string): Locator;
