Skip to content

Commit a5cb6c9

Browse files
pavelfeldmanpavelfeldman
committed
cherry-pick(#39972): chore: expose browser.bind and browser.unbind APIs
1 parent 99a17b5 commit a5cb6c9

28 files changed

Lines changed: 482 additions & 108 deletions

‎docs/src/api/class-browser.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,6 +295,44 @@ testing frameworks should explicitly create [`method: Browser.newContext`] follo
295295
### option: Browser.newPage.storageStatePath = %%-csharp-java-context-option-storage-state-path-%%
296296
* since: v1.9
297297

298+
## async method: Browser.bind
299+
* since: v1.59
300+
- returns: <[Object]>
301+
- `endpoint` <[string]>
302+
303+
Binds the browser to a named pipe or web socket, making it available for other clients to connect to.
304+
305+
### param: Browser.bind.title
306+
* since: v1.59
307+
- `title` <[string]>
308+
309+
Title of the browser server, used for identification.
310+
311+
### option: Browser.bind.workspaceDir
312+
* since: v1.59
313+
- `workspaceDir` <[string]>
314+
315+
Working directory associated with this browser server.
316+
317+
### option: Browser.bind.metadata
318+
* since: v1.59
319+
* langs: js
320+
- `metadata` <[Object]<[string], [any]>>
321+
322+
Additional metadata to associate with the browser server.
323+
324+
### option: Browser.bind.host
325+
* since: v1.59
326+
- `host` <[string]>
327+
328+
Host to bind the web socket server to. When specified, a web socket server is created instead of a named pipe.
329+
330+
### option: Browser.bind.port
331+
* since: v1.59
332+
- `port` <[int]>
333+
334+
Port to bind the web socket server to. When specified, a web socket server is created instead of a named pipe. Use `0` to let the OS pick an available port.
335+
298336
## async method: Browser.removeAllListeners
299337
* since: v1.47
300338
* langs: js
@@ -382,6 +420,11 @@ This API controls [Chromium Tracing](https://www.chromium.org/developers/how-tos
382420

383421
Returns the buffer with trace data.
384422

423+
## async method: Browser.unbind
424+
* since: v1.59
425+
426+
Unbinds the browser server previously bound with [`method: Browser.bind`].
427+
385428
## method: Browser.version
386429
* since: v1.8
387430
- returns: <[string]>

‎docs/src/images/release-notes-1.59-dashboard.png‎

90.8 KB
Loading

‎docs/src/release-notes-csharp.md‎

Lines changed: 59 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,14 @@ import LiteYouTube from '@site/src/components/LiteYouTube';
1010

1111
### 🎬 Screencast
1212

13-
New [`property: Page.screencast`] API provides a unified interface for capturing page content — both as video recordings and as real-time frame streams.
13+
New [`property: Page.screencast`] API provides a unified interface for capturing page content — both as video recordings, annotations, overlays, and a real-time frame stream.
1414

15+
<center>
1516
<img src="https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/images/release-notes-1.59-screencast-demo.gif" alt="Demo" width="500" height="313" />
17+
</center>
1618

17-
**Video recording** — record video with precise start/stop control, as an alternative to the [`option: Browser.newContext.recordVideoDir`] option:
19+
20+
**Screencast recording** — record video with precise start/stop control, as an alternative to the [`option: Browser.newContext.recordVideoDir`] option:
1821

1922
```csharp
2023
await page.Screencast.StartAsync(new() { Path = "video.webm" });
@@ -103,10 +106,63 @@ The resulting video serves as a receipt: chapter titles provide context, action
103106
- Method [`method: BrowserContext.isClosed`].
104107
- Method [`method: Request.existingResponse`] returns the response without waiting.
105108
- Method [`method: Response.httpVersion`] returns the HTTP version used by the response.
106-
- Event [`event: CDPSession.close`] for CDP sessions.
107109
- Option `Live` in [`method: Tracing.start`] for real-time trace updates.
108110
- Option `ArtifactsDir` in [`method: BrowserType.launch`] to configure the artifacts directory.
109111

112+
### 🔗 Interoperability
113+
114+
New [`method: Browser.bind`] API makes a launched browser available for `playwright-cli`, `@playwright/mcp`, and other clients to connect to.
115+
116+
**Bind a browser** — start a browser and bind it so others can connect:
117+
118+
```csharp
119+
var browser = await chromium.LaunchAsync();
120+
var serverInfo = await browser.BindAsync("my-session", new() {
121+
WorkspaceDir = "/my/project",
122+
});
123+
```
124+
125+
**Connect from playwright-cli**
126+
127+
```bash
128+
playwright-cli attach my-session
129+
```
130+
131+
**Connect from playwright/mcp**
132+
133+
```bash
134+
@playwright/mcp --endpoint=my-session
135+
```
136+
137+
**Connect from another client**
138+
139+
```csharp
140+
var browser = await chromium.ConnectAsync(serverInfo.Endpoint);
141+
```
142+
143+
Pass `Host` and `Port` options to bind over WebSocket instead of a named pipe:
144+
145+
```csharp
146+
var serverInfo = await browser.BindAsync("my-session", new() {
147+
Host = "localhost",
148+
Port = 0,
149+
});
150+
// serverInfo.Endpoint is a ws:// URL
151+
```
152+
153+
Call [`method: Browser.unbind`] to stop accepting new connections.
154+
155+
### 📊 Observability
156+
157+
Run `playwright-cli show` to open the Dashboard that lists all bound browsers, their status, and workspace.
158+
159+
<center>
160+
<img src="https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/images/release-notes-1.59-dashboard.gif" alt="Demo" width="1169" height="835" />
161+
</center>
162+
163+
- `playwright-cli` binds all of its browsers automatically, so you can see what your agents are doing.
164+
- Pass `PLAYWRIGHT_DASHBOARD=1` env variable to see all `@playwright/test` browsers in the dashboard.
165+
110166
### Breaking Changes ⚠️
111167

112168
- Removed macOS 14 support for WebKit. We recommend upgrading your macOS version, or keeping an older Playwright version.

‎docs/src/release-notes-java.md‎

Lines changed: 56 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,14 @@ import LiteYouTube from '@site/src/components/LiteYouTube';
1010

1111
### 🎬 Screencast
1212

13-
New [`property: Page.screencast`] API provides a unified interface for capturing page content — both as video recordings and as real-time frame streams.
13+
New [`property: Page.screencast`] API provides a unified interface for capturing page content — both as video recordings, annotations, overlays, and a real-time frame stream.
1414

15+
<center>
1516
<img src="https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/images/release-notes-1.59-screencast-demo.gif" alt="Demo" width="500" height="313" />
17+
</center>
1618

17-
**Video recording** — record video with precise start/stop control, as an alternative to the [`option: Browser.newContext.recordVideoDir`] option:
19+
20+
**Screencast recording** — record video with precise start/stop control, as an alternative to the [`option: Browser.newContext.recordVideoDir`] option:
1821

1922
```java
2023
page.screencast().start(new Screencast.StartOptions().setPath(Paths.get("video.webm")));
@@ -103,10 +106,60 @@ The resulting video serves as a receipt: chapter titles provide context, action
103106
- Method [`method: BrowserContext.isClosed`].
104107
- Method [`method: Request.existingResponse`] returns the response without waiting.
105108
- Method [`method: Response.httpVersion`] returns the HTTP version used by the response.
106-
- Event [`event: CDPSession.close`] for CDP sessions.
107109
- Option `live` in [`method: Tracing.start`] for real-time trace updates.
108110
- Option `artifactsDir` in [`method: BrowserType.launch`] to configure the artifacts directory.
109111

112+
### 🔗 Interoperability
113+
114+
New [`method: Browser.bind`] API makes a launched browser available for `playwright-cli`, `@playwright/mcp`, and other clients to connect to.
115+
116+
**Bind a browser** — start a browser and bind it so others can connect:
117+
118+
```java
119+
Browser browser = chromium.launch();
120+
Browser.BindResult serverInfo = browser.bind("my-session",
121+
new Browser.BindOptions().setWorkspaceDir("/my/project"));
122+
```
123+
124+
**Connect from playwright-cli**
125+
126+
```bash
127+
playwright-cli attach my-session
128+
```
129+
130+
**Connect from playwright/mcp**
131+
132+
```bash
133+
@playwright/mcp --endpoint=my-session
134+
```
135+
136+
**Connect from another client**
137+
138+
```java
139+
Browser browser = chromium.connect(serverInfo.endpoint);
140+
```
141+
142+
Pass `host` and `port` options to bind over WebSocket instead of a named pipe:
143+
144+
```java
145+
Browser.BindResult serverInfo = browser.bind("my-session",
146+
new Browser.BindOptions().setHost("localhost").setPort(0));
147+
// serverInfo.endpoint is a ws:// URL
148+
```
149+
150+
Call [`method: Browser.unbind`] to stop accepting new connections.
151+
152+
### 📊 Observability
153+
154+
Run `playwright-cli show` to open the Dashboard that lists all bound browsers, their status, and workspace.
155+
156+
<center>
157+
<img src="https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/images/release-notes-1.59-dashboard.gif" alt="Demo" width="1169" height="835" />
158+
</center>
159+
160+
- `playwright-cli` binds all of its browsers automatically, so you can see what your agents are doing.
161+
- Pass `PLAYWRIGHT_DASHBOARD=1` env variable to see all `@playwright/test` browsers in the dashboard.
162+
110163
### Breaking Changes ⚠️
111164

112165
- Removed macOS 14 support for WebKit. We recommend upgrading your macOS version, or keeping an older Playwright version.

‎docs/src/release-notes-js.md‎

Lines changed: 61 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,14 @@ import LiteYouTube from '@site/src/components/LiteYouTube';
1010

1111
### 🎬 Screencast
1212

13-
New [`property: Page.screencast`] API provides a unified interface for capturing page content — both as video recordings and as real-time frame streams.
13+
New [`property: Page.screencast`] API provides a unified interface for capturing page content — both as video recordings, annotations, overlays, and a real-time frame stream.
1414

15+
<center>
1516
<img src="https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/images/release-notes-1.59-screencast-demo.gif" alt="Demo" width="500" height="313" />
17+
</center>
1618

17-
**Video recording** — record video with precise start/stop control, as an alternative to the [`option: Browser.newContext.recordVideo`] option:
19+
20+
**Screencast recording** — record video with precise start/stop control, as an alternative to the [`option: Browser.newContext.recordVideo`] option:
1821

1922
```js
2023
await page.screencast.start({ path: 'video.webm' });
@@ -91,9 +94,62 @@ await page.screencast.stop();
9194

9295
The resulting video serves as a receipt: chapter titles provide context, action annotations highlight each interaction, and the visual walkthrough is faster to review than text logs.
9396

94-
### 🤖 Agentic Tools
97+
### 🔗 Interoperability
98+
99+
New [`method: Browser.bind`] API makes a launched browser available for `playwright-cli`, `@playwright/mcp`, and other clients to connect to.
100+
101+
**Bind a browser** — start a browser and bind it so others can connect:
102+
103+
```js
104+
const browser = await chromium.launch();
105+
const { endpoint } = await browser.bind('my-session', {
106+
workspaceDir: '/my/project',
107+
});
108+
```
109+
110+
**Connect from playwright-cli**
111+
112+
```bash
113+
playwright-cli attach my-session
114+
playwright-cli -s my-session snapshot
115+
```
116+
117+
**Connect from playwright/mcp**
118+
119+
```bash
120+
@playwright/mcp --endpoint=my-session
121+
```
122+
123+
**Connect from another client**
124+
125+
```js
126+
const browser = await chromium.connect(endpoint);
127+
```
128+
129+
Pass `host` and `port` options to bind over WebSocket instead of a named pipe:
130+
131+
```js
132+
const { endpoint } = await browser.bind('my-session', {
133+
host: 'localhost',
134+
port: 0,
135+
});
136+
// endpoint is a ws:// URL
137+
```
138+
139+
Call [`method: Browser.unbind`] to stop accepting new connections.
140+
141+
### 📊 Observability
142+
143+
Run `playwright-cli show` to open the Dashboard that lists all bound browsers, their status, and workspace.
144+
145+
<center>
146+
<img src="https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/images/release-notes-1.59-dashboard.gif" alt="Demo" width="1169" height="835" />
147+
</center>
148+
149+
- `playwright-cli` binds all of its browsers automatically, so you can see what your agents are doing.
150+
- Pass `PLAYWRIGHT_DASHBOARD=1` env variable to see all `@playwright/test` browsers in the dashboard.
95151

96-
#### CLI debugger
152+
### 🐛 CLI debugger for agents
97153

98154
Coding agents can now run `npx playwright test --debug=cli` to attach and debug tests over `playwright-cli` — perfect for automatically fixing tests in agentic workflows:
99155

@@ -116,7 +172,7 @@ $ playwright-cli --session tw-87b59e step-over
116172
- Expect "toHaveTitle" at output/tests/example.spec.ts:7
117173
```
118174

119-
#### CLI trace analysis
175+
### 📋 CLI trace analysis for agents
120176

121177
Coding agents can run `npx playwright trace` to explore [Playwright Trace](./trace-viewer.md) and understand failing or flaky tests from the command line:
122178

‎docs/src/release-notes-python.md‎

Lines changed: 59 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,14 @@ import LiteYouTube from '@site/src/components/LiteYouTube';
1010

1111
### 🎬 Screencast
1212

13-
New [`property: Page.screencast`] API provides a unified interface for capturing page content — both as video recordings and as real-time frame streams.
13+
New [`property: Page.screencast`] API provides a unified interface for capturing page content — both as video recordings, annotations, overlays, and a real-time frame stream.
1414

15+
<center>
1516
<img src="https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/images/release-notes-1.59-screencast-demo.gif" alt="Demo" width="500" height="313" />
17+
</center>
1618

17-
**Video recording** — record video with precise start/stop control, as an alternative to the [`option: Browser.newContext.recordVideoDir`] option:
19+
20+
**Screencast recording** — record video with precise start/stop control, as an alternative to the [`option: Browser.newContext.recordVideoDir`] option:
1821

1922
```python
2023
page.screencast.start(path="video.webm")
@@ -103,10 +106,63 @@ The resulting video serves as a receipt: chapter titles provide context, action
103106
- Method [`method: BrowserContext.isClosed`].
104107
- Method [`method: Request.existingResponse`] returns the response without waiting.
105108
- Method [`method: Response.httpVersion`] returns the HTTP version used by the response.
106-
- Event [`event: CDPSession.close`] for CDP sessions.
107109
- Option `live` in [`method: Tracing.start`] for real-time trace updates.
108110
- Option `artifacts_dir` in [`method: BrowserType.launch`] to configure the artifacts directory.
109111

112+
### 🔗 Interoperability
113+
114+
New [`method: Browser.bind`] API makes a launched browser available for `playwright-cli`, `@playwright/mcp`, and other clients to connect to.
115+
116+
**Bind a browser** — start a browser and bind it so others can connect:
117+
118+
```python
119+
browser = await chromium.launch()
120+
server_info = await browser.bind("my-session",
121+
workspace_dir="/my/project",
122+
)
123+
```
124+
125+
**Connect from playwright-cli**
126+
127+
```bash
128+
playwright-cli attach my-session
129+
```
130+
131+
**Connect from playwright/mcp**
132+
133+
```bash
134+
@playwright/mcp --endpoint=my-session
135+
```
136+
137+
**Connect from another client**
138+
139+
```python
140+
browser = await chromium.connect(server_info["endpoint"])
141+
```
142+
143+
Pass `host` and `port` options to bind over WebSocket instead of a named pipe:
144+
145+
```python
146+
server_info = await browser.bind("my-session",
147+
host="localhost",
148+
port=0,
149+
)
150+
# server_info["endpoint"] is a ws:// URL
151+
```
152+
153+
Call [`method: Browser.unbind`] to stop accepting new connections.
154+
155+
### 📊 Observability
156+
157+
Run `playwright-cli show` to open the Dashboard that lists all bound browsers, their status, and workspace.
158+
159+
<center>
160+
<img src="https://raw.githubusercontent.com/microsoft/playwright/main/docs/src/images/release-notes-1.59-dashboard.gif" alt="Demo" width="1169" height="835" />
161+
</center>
162+
163+
- `playwright-cli` binds all of its browsers automatically, so you can see what your agents are doing.
164+
- Pass `PLAYWRIGHT_DASHBOARD=1` env variable to see all `@playwright/test` browsers in the dashboard.
165+
110166
### Breaking Changes ⚠️
111167

112168
- Removed macOS 14 support for WebKit. We recommend upgrading your macOS version, or keeping an older Playwright version.

‎packages/dashboard/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
<head>
1919
<meta charset="UTF-8">
2020
<meta name="viewport" content="width=device-width, initial-scale=1.0">
21-
<title>Playwright Monitor</title>
21+
<title>Playwright Dashboard</title>
2222
</head>
2323
<body>
2424
<div id="root"></div>

0 commit comments

Comments
 (0)