playwright-repl 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/{RELEASES.md → CHANGELOG.md} +111 -70
  2. package/README.md +53 -12
  3. package/bin/mcp-server.cjs +32 -0
  4. package/package.json +4 -3
  5. package/src/repl.mjs +604 -582
package/{RELEASES.md → CHANGELOG.md} RENAMED
@@ -1,70 +1,111 @@
1
- # Releases
2
-
3
- ## v0.1.0 — Initial Release
4
-
5
- **2026-02-09**
6
-
7
- First public release of playwright-repl — an interactive REPL for Playwright browser automation.
8
-
9
- ### Features
10
-
11
- **Interactive REPL**
12
- - Persistent socket connection to the Playwright daemon (zero overhead per command)
13
- - 50+ browser commands with short aliases (`c` for click, `s` for snapshot, etc.)
14
- - Tab completion for commands, aliases, and meta-commands
15
- - Command history (persisted across sessions)
16
- - Automatic daemon startup and connection management
17
- - Auto-reconnect on daemon disconnect
18
-
19
- **Session Recording & Replay**
20
- - Record browser interactions to `.pw` files (plain text, one command per line)
21
- - Replay recorded sessions at full speed or step-by-step
22
- - Pause/resume recording mid-session
23
- - Start recording from CLI (`--record`) or inside the REPL (`.record`)
24
-
25
- **Assertions**
26
- - `verify-text` — assert text is visible on the page
27
- - `verify-element` — assert element exists by role and accessible name
28
- - `verify-value` — assert input/select/checkbox value
29
- - `verify-list` — assert list contains expected items
30
-
31
- **Browser Commands**
32
- - Navigation: `goto`, `go-back`, `go-forward`, `reload`
33
- - Interaction: `click`, `dblclick`, `fill`, `type`, `press`, `hover`, `select`, `check`, `uncheck`, `upload`, `drag`
34
- - Inspection: `snapshot`, `screenshot`, `eval`, `console`, `network`, `run-code`
35
- - Tabs: `tab-list`, `tab-new`, `tab-close`, `tab-select`
36
- - Storage: cookies, localStorage, sessionStorage (list/get/set/delete/clear)
37
- - Auth state: `state-save`, `state-load`
38
- - Network: `route`, `route-list`, `unroute`
39
- - Dialogs: `dialog-accept`, `dialog-dismiss`
40
- - Layout: `resize`, `pdf`
41
- - Sessions: `list`, `close`, `close-all`, `kill-all`
42
-
43
- **CLI Options**
44
- - `--headed` — visible browser mode
45
- - `--browser` — choose chrome, firefox, webkit, or msedge
46
- - `--session` — named sessions for parallel workflows
47
- - `--persistent` / `--profile` — persistent browser profiles
48
- - `--replay` / `--step` — session replay from CLI
49
- - `--record` — start with recording enabled
50
- - `--silent` — quiet mode for scripting
51
-
52
- **Cross-Platform**
53
- - Linux, macOS, Windows
54
- - Unix sockets (Linux/macOS) and named pipes (Windows)
55
-
56
- ### Technical Details
57
-
58
- - Pure ESM JavaScript (no build step, no TypeScript)
59
- - Connects to Playwright's MCP terminal daemon over Unix socket / named pipe
60
- - Wire-compatible with `playwright-cli` — produces identical JSON messages
61
- - Requires `playwright >= 1.59.0-alpha` (daemon code in `lib/mcp/terminal/`)
62
- - 218 tests, 96% statement coverage
63
-
64
- ### Known Limitations
65
-
66
- - Low-level keyboard commands (`keydown`, `keyup`) not yet mapped
67
- - Low-level mouse commands (`mousemove`, `mousedown`, `mouseup`, `mousewheel`) not yet mapped
68
- - Tracing (`tracing-start`, `tracing-stop`) not yet mapped
69
- - Video recording (`video-start`, `video-stop`) not yet mapped
70
- - Element refs (e.g., `e5`) are ephemeral — they change between snapshots
1
+ # Changelog
2
+
3
+ ## v0.2.0 — MCP Server
4
+
5
+ **2026-02-16**
6
+
7
+ ### Features
8
+
9
+ - **MCP Server**: Ships a stdio MCP server (`playwright-mcp-server`) that exposes Playwright's full browser automation toolkit to AI agents (Claude, Cursor, etc.)
10
+ - Supports `--headed` flag for visible browser mode
11
+
12
+ ### Configuration
13
+
14
+ VS Code / Cursor — add to `.vscode/mcp.json`:
15
+
16
+ ```json
17
+ {
18
+ "servers": {
19
+ "playwright": {
20
+ "command": "npx",
21
+ "args": ["-p", "playwright-repl", "playwright-mcp-server", "--headed"]
22
+ }
23
+ }
24
+ }
25
+ ```
26
+
27
+ ---
28
+
29
+ ## v0.1.1 — Bug Fixes
30
+
31
+ **2026-02-12**
32
+
33
+ ### Fixes
34
+
35
+ - **`kill-all` on Windows 11**: Replace deprecated `wmic` with PowerShell `Get-CimInstance` — fixes `'wmic' is not recognized` error on modern Windows
36
+ - **Text locator case sensitivity**: `click`, `dblclick`, and `hover` now use a fallback chain (exact text → button role → link role → substring match) so `click "GET STARTED"` works even when the DOM text is "Get Started"
37
+
38
+ ### Tests
39
+
40
+ - Updated tests for new text locator fallback chain and PowerShell kill-all
41
+
42
+ ---
43
+
44
+ ## v0.1.0 — Initial Release
45
+
46
+ **2026-02-09**
47
+
48
+ First public release of playwright-repl — an interactive REPL for Playwright browser automation.
49
+
50
+ ### Features
51
+
52
+ **Interactive REPL**
53
+ - Persistent socket connection to the Playwright daemon (zero overhead per command)
54
+ - 50+ browser commands with short aliases (`c` for click, `s` for snapshot, etc.)
55
+ - Tab completion for commands, aliases, and meta-commands
56
+ - Command history (persisted across sessions)
57
+ - Automatic daemon startup and connection management
58
+ - Auto-reconnect on daemon disconnect
59
+
60
+ **Session Recording & Replay**
61
+ - Record browser interactions to `.pw` files (plain text, one command per line)
62
+ - Replay recorded sessions at full speed or step-by-step
63
+ - Pause/resume recording mid-session
64
+ - Start recording from CLI (`--record`) or inside the REPL (`.record`)
65
+
66
+ **Assertions**
67
+ - `verify-text` — assert text is visible on the page
68
+ - `verify-element` — assert element exists by role and accessible name
69
+ - `verify-value` — assert input/select/checkbox value
70
+ - `verify-list` — assert list contains expected items
71
+
72
+ **Browser Commands**
73
+ - Navigation: `goto`, `go-back`, `go-forward`, `reload`
74
+ - Interaction: `click`, `dblclick`, `fill`, `type`, `press`, `hover`, `select`, `check`, `uncheck`, `upload`, `drag`
75
+ - Inspection: `snapshot`, `screenshot`, `eval`, `console`, `network`, `run-code`
76
+ - Tabs: `tab-list`, `tab-new`, `tab-close`, `tab-select`
77
+ - Storage: cookies, localStorage, sessionStorage (list/get/set/delete/clear)
78
+ - Auth state: `state-save`, `state-load`
79
+ - Network: `route`, `route-list`, `unroute`
80
+ - Dialogs: `dialog-accept`, `dialog-dismiss`
81
+ - Layout: `resize`, `pdf`
82
+ - Sessions: `list`, `close`, `close-all`, `kill-all`
83
+
84
+ **CLI Options**
85
+ - `--headed` — visible browser mode
86
+ - `--browser` — choose chrome, firefox, webkit, or msedge
87
+ - `--session` — named sessions for parallel workflows
88
+ - `--persistent` / `--profile` — persistent browser profiles
89
+ - `--replay` / `--step` — session replay from CLI
90
+ - `--record` — start with recording enabled
91
+ - `--silent` — quiet mode for scripting
92
+
93
+ **Cross-Platform**
94
+ - Linux, macOS, Windows
95
+ - Unix sockets (Linux/macOS) and named pipes (Windows)
96
+
97
+ ### Technical Details
98
+
99
+ - Pure ESM JavaScript (no build step, no TypeScript)
100
+ - Connects to Playwright's MCP terminal daemon over Unix socket / named pipe
101
+ - Wire-compatible with `playwright-cli` — produces identical JSON messages
102
+ - Requires `playwright >= 1.59.0-alpha` (daemon code in `lib/mcp/terminal/`)
103
+ - 218 tests, 96% statement coverage
104
+
105
+ ### Known Limitations
106
+
107
+ - Low-level keyboard commands (`keydown`, `keyup`) not yet mapped
108
+ - Low-level mouse commands (`mousemove`, `mousedown`, `mouseup`, `mousewheel`) not yet mapped
109
+ - Tracing (`tracing-start`, `tracing-stop`) not yet mapped
110
+ - Video recording (`video-start`, `video-stop`) not yet mapped
111
+ - Element refs (e.g., `e5`) are ephemeral — they change between snapshots
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # playwright-repl
2
2
 
3
+ ![playwright-repl](cover-image.png)
4
+
3
5
  Interactive REPL for Playwright browser automation — keyword-driven testing from your terminal.
4
6
 
5
7
  Inspired by [playwright-cli](https://github.com/anthropics/playwright-cli), reusing its command vocabulary and Playwright MCP daemon. Where playwright-cli is designed for AI agents (one command per process), playwright-repl is designed for **humans** — a persistent session with recording, replay, and instant feedback.
@@ -46,13 +48,12 @@ $ playwright-repl --replay smoke-test.pw
46
48
  ## Install
47
49
 
48
50
  ```bash
49
- # Prerequisites: Node.js >= 18 and Playwright
50
- npm install -g playwright@latest
51
-
52
- # Install playwright-repl
53
51
  npm install -g playwright-repl
54
52
 
55
- # Or from source
53
+ # If you don't have browser binaries yet
54
+ npx playwright install
55
+
56
+ # Or install from source
56
57
  git clone https://github.com/stevez/playwright-repl.git
57
58
  cd playwright-repl && npm install && npm link
58
59
  ```
@@ -129,6 +130,52 @@ playwright-repl --session checkout-flow --headed
129
130
  | `-q, --silent` | Suppress banner and status messages |
130
131
  | `-h, --help` | Show help |
131
132
 
133
+ ## MCP Server
134
+
135
+ `playwright-repl` also ships an MCP server that exposes Playwright's full browser automation toolkit to AI agents (Claude, Cursor, etc.) over stdio.
136
+
137
+ ```bash
138
+ # Run directly
139
+ npx -p playwright-repl playwright-mcp-server
140
+
141
+ # With visible browser
142
+ npx -p playwright-repl playwright-mcp-server --headed
143
+ ```
144
+
145
+ ### VS Code / Cursor Configuration
146
+
147
+ Add to `.vscode/mcp.json` in your project:
148
+
149
+ ```json
150
+ {
151
+ "servers": {
152
+ "playwright": {
153
+ "command": "npx",
154
+ "args": ["-p", "playwright-repl", "playwright-mcp-server"]
155
+ }
156
+ }
157
+ }
158
+ ```
159
+
160
+ Or with a visible browser:
161
+
162
+ ```json
163
+ {
164
+ "servers": {
165
+ "playwright": {
166
+ "command": "npx",
167
+ "args": ["-p", "playwright-repl", "playwright-mcp-server", "--headed"]
168
+ }
169
+ }
170
+ }
171
+ ```
172
+
173
+ ### MCP Server Options
174
+
175
+ | Option | Description |
176
+ |--------|-------------|
177
+ | `--headed` | Run browser in headed (visible) mode |
178
+
132
179
  ## Commands
133
180
 
134
181
  ### Navigation
@@ -337,13 +384,7 @@ playwright-repl --replay examples/05-ci-pipe.pw --silent
337
384
 
338
385
  ## Architecture
339
386
 
340
- ```
341
- ┌──────────────┐ Unix Socket ┌──────────────────┐ CDP ┌─────────┐
342
- │ playwright- │◄──── JSON/newline ───►│ Daemon Process │◄────────────►│ Browser │
343
- │ repl │ │ (Playwright │ │(Chrome/ │
344
- │ │ │ MCP backend) │ │ FF/WK) │
345
- └──────────────┘ └──────────────────┘ └─────────┘
346
- ```
387
+ ![Architecture](architecture-diagram.png)
347
388
 
348
389
  The REPL replaces only the **client half** of playwright-cli. The daemon, browser, and all tool handlers are unchanged — both CLI and REPL produce identical wire messages.
349
390
 
package/bin/mcp-server.cjs ADDED
@@ -0,0 +1,32 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * Thin MCP server entrypoint — uses Playwright's built-in MCP infrastructure.
5
+ * Starts a stdio MCP server with all browser tools available.
6
+ *
7
+ * Uses only publicly exported paths:
8
+ * - playwright/lib/mcp/index → createConnection()
9
+ * - playwright-core/lib/mcpBundle → StdioServerTransport
10
+ */
11
+
12
+ const { createConnection } = require('playwright/lib/mcp/index');
13
+ const { StdioServerTransport } = require('playwright-core/lib/mcpBundle');
14
+
15
+ // ─── Parse CLI args ───
16
+
17
+ const args = process.argv.slice(2);
18
+ const headed = args.includes('--headed');
19
+
20
+ (async () => {
21
+ const server = await createConnection({
22
+ browser: {
23
+ launchOptions: { headless: !headed },
24
+ },
25
+ });
26
+
27
+ const transport = new StdioServerTransport();
28
+ await server.connect(transport);
29
+ })().catch(e => {
30
+ console.error(e.message);
31
+ process.exit(1);
32
+ });
package/package.json CHANGED
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "name": "playwright-repl",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Interactive REPL for Playwright browser automation — keyword-driven testing from your terminal",
5
5
  "type": "module",
6
6
  "bin": {
7
- "playwright-repl": "./bin/playwright-repl.mjs"
7
+ "playwright-repl": "./bin/playwright-repl.mjs",
8
+ "playwright-mcp-server": "./bin/mcp-server.cjs"
8
9
  },
9
10
  "main": "./src/index.mjs",
10
11
  "exports": {
@@ -36,7 +37,7 @@
36
37
  "examples/",
37
38
  "LICENSE",
38
39
  "README.md",
39
- "RELEASES.md"
40
+ "CHANGELOG.md"
40
41
  ],
41
42
  "engines": {
42
43
  "node": ">=18.0.0"