mirror of
https://github.com/bitsocialnet/5chan.git
synced 2026-08-03 07:41:04 +02:00
Tommaso Casaburi
1a33f7dc88
Playwright disables normal background throttling, so a hidden 5chan page keeps doing P2P and rendering work after a check finishes. Agents verifying in parallel across worktrees stacked whole browser engines on one machine. Add scripts/pw-session.sh, a wrapper that permits one active Playwright browser at a time and records who holds it: - The lock is machine-wide, not per-repository, because the contended resource is RAM and CPU. Every worktree and checkout shares one slot. - Acquisition is an atomic mkdir. Stale locks clear themselves: `open` reclaims any slot whose recorded browser is no longer `status: open` in `playwright-cli list --all`, so an interrupted workflow cannot strand the budget. When that list cannot be read the lock is left alone, so a broken CLI never silently disables the budget. - `open` exits 75 when the slot is busy; `--wait[=SECONDS]` blocks instead. - `close` always stops the browser, even when the lock was already lost, and never releases a slot held by a different session. - `status` reports the holder and whether its browser is still alive. Agent policy now runs browser engines and profiler batches sequentially, uses Chrome/Blink during iteration and the full engine matrix only for final verification, and never uses `close-all` or `kill-all` while other agents may own sessions. Covered by scripts/pw-session.test.js.
326 lines
10 KiB
Markdown
326 lines
10 KiB
Markdown
---
|
|
name: playwright-cli
|
|
description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
|
|
allowed-tools: Bash(playwright-cli:*), Bash(./scripts/pw-session.sh:*)
|
|
---
|
|
|
|
# Browser Automation with playwright-cli
|
|
|
|
## Resource Budget (MUST)
|
|
|
|
One Playwright browser session may be active at a time, machine-wide. The budget is shared by every worktree and by any other checkout that ships this wrapper, because the contended resource is machine RAM and CPU rather than the repository. Playwright disables normal background throttling, so hidden 5chan pages keep P2P and rendering work active after a check.
|
|
|
|
- During iteration, use Chrome/Blink only. Run the full cross-browser matrix once the change is ready for final verification.
|
|
- Open every fresh session through `./scripts/pw-session.sh open <session> ...`; it acquires the shared browser slot.
|
|
- Reuse the same engine session for desktop and mobile by resizing it.
|
|
- Close it with `./scripts/pw-session.sh close <session>` in a finally-style cleanup before opening another engine. `close` stops the browser even when the lock was already lost, so it is always the right cleanup call.
|
|
- Run browser engines and profiler batches sequentially. Never spawn browser-driving agents in parallel.
|
|
- Exit code 75 means the slot is busy. Finish non-browser work and retry, or block on `./scripts/pw-session.sh open --wait[=SECONDS] <session> ...` (default 300s). Do not bypass the lock.
|
|
- Never use `playwright-cli close-all` or `kill-all` while concurrent agents may own sessions.
|
|
- A lock left behind by an interrupted workflow clears itself: the next `open` reclaims any slot whose browser is no longer running. Inspect the holder with `./scripts/pw-session.sh status`, which reports whether that browser is still alive. `release <session>` is a last resort for the rare case where `status` cannot verify the browser state.
|
|
|
|
## Cross-Browser UI Verification
|
|
|
|
When using `playwright-cli` to verify rendering, styling, layout, or interactions in this repo, run the relevant flow in all three major browser engines:
|
|
|
|
- `chrome` for Blink
|
|
- `firefox` for Gecko
|
|
- `webkit` for Safari/WebKit coverage
|
|
|
|
Use separate short named sessions per engine, compare the results, and record any engine-specific differences instead of treating Chromium output as sufficient. Run them sequentially:
|
|
|
|
```bash
|
|
./scripts/pw-session.sh open verify-chrome http://example.com --browser=chrome
|
|
# Run the desktop and mobile flow, then release the slot.
|
|
./scripts/pw-session.sh close verify-chrome
|
|
|
|
./scripts/pw-session.sh open verify-firefox http://example.com --browser=firefox
|
|
# Run the desktop and mobile flow, then release the slot.
|
|
./scripts/pw-session.sh close verify-firefox
|
|
|
|
./scripts/pw-session.sh open verify-webkit http://example.com --browser=webkit
|
|
# Run the desktop and mobile flow, then release the slot.
|
|
./scripts/pw-session.sh close verify-webkit
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# open new browser
|
|
playwright-cli open
|
|
# navigate to a page
|
|
playwright-cli goto https://playwright.dev
|
|
# interact with the page using refs from the snapshot
|
|
playwright-cli click e15
|
|
playwright-cli type "page.click"
|
|
playwright-cli press Enter
|
|
# take a screenshot
|
|
playwright-cli screenshot
|
|
# close the browser
|
|
playwright-cli close
|
|
```
|
|
|
|
## Session mode selection
|
|
|
|
Default to a fresh isolated browser session for reproducible verification.
|
|
|
|
Before browser work where existing state may matter, explicitly confirm the mode if the user has not already said which one they want:
|
|
|
|
1. Fresh isolated `playwright-cli` session
|
|
2. Current browser session reuse
|
|
|
|
Existing state usually matters when the task depends on auth, cookies, extensions, open tabs, or reproducing something already happening in the contributor's browser.
|
|
|
|
Do not attach to a live personal browser session without explicit approval.
|
|
|
|
If current-session reuse is requested, prefer the supported attach path in the local setup:
|
|
|
|
```bash
|
|
# Fresh isolated browser (default)
|
|
playwright-cli -s=verify open https://example.com
|
|
|
|
# Reusable Playwright-managed profile
|
|
playwright-cli -s=verify open https://example.com --persistent
|
|
|
|
# Attach to an existing browser when the local extension bridge is set up
|
|
playwright-cli open --extension
|
|
```
|
|
|
|
If the task requires the contributor's current browser session and the attach path is not available in the current setup, stop and ask whether to switch to a fresh session or provide an explicit CDP-based Playwright script.
|
|
|
|
## Commands
|
|
|
|
### Core
|
|
|
|
```bash
|
|
playwright-cli open
|
|
# open and navigate right away
|
|
playwright-cli open https://example.com/
|
|
playwright-cli goto https://playwright.dev
|
|
playwright-cli type "search query"
|
|
playwright-cli click e3
|
|
playwright-cli dblclick e7
|
|
playwright-cli fill e5 "user@example.com"
|
|
playwright-cli drag e2 e8
|
|
playwright-cli hover e4
|
|
playwright-cli select e9 "option-value"
|
|
playwright-cli upload ./document.pdf
|
|
playwright-cli check e12
|
|
playwright-cli uncheck e12
|
|
playwright-cli snapshot
|
|
playwright-cli snapshot --filename=after-click.yaml
|
|
playwright-cli eval "document.title"
|
|
playwright-cli eval "el => el.textContent" e5
|
|
playwright-cli dialog-accept
|
|
playwright-cli dialog-accept "confirmation text"
|
|
playwright-cli dialog-dismiss
|
|
playwright-cli resize 1920 1080
|
|
playwright-cli close
|
|
```
|
|
|
|
### Navigation
|
|
|
|
```bash
|
|
playwright-cli go-back
|
|
playwright-cli go-forward
|
|
playwright-cli reload
|
|
```
|
|
|
|
### Keyboard
|
|
|
|
```bash
|
|
playwright-cli press Enter
|
|
playwright-cli press ArrowDown
|
|
playwright-cli keydown Shift
|
|
playwright-cli keyup Shift
|
|
```
|
|
|
|
### Mouse
|
|
|
|
```bash
|
|
playwright-cli mousemove 150 300
|
|
playwright-cli mousedown
|
|
playwright-cli mousedown right
|
|
playwright-cli mouseup
|
|
playwright-cli mouseup right
|
|
playwright-cli mousewheel 0 100
|
|
```
|
|
|
|
### Save as
|
|
|
|
```bash
|
|
playwright-cli screenshot
|
|
playwright-cli screenshot e5
|
|
playwright-cli screenshot --filename=page.png
|
|
playwright-cli pdf --filename=page.pdf
|
|
```
|
|
|
|
### Tabs
|
|
|
|
```bash
|
|
playwright-cli tab-list
|
|
playwright-cli tab-new
|
|
playwright-cli tab-new https://example.com/page
|
|
playwright-cli tab-close
|
|
playwright-cli tab-close 2
|
|
playwright-cli tab-select 0
|
|
```
|
|
|
|
### Storage
|
|
|
|
```bash
|
|
playwright-cli state-save
|
|
playwright-cli state-save auth.json
|
|
playwright-cli state-load auth.json
|
|
|
|
# Cookies
|
|
playwright-cli cookie-list
|
|
playwright-cli cookie-list --domain=example.com
|
|
playwright-cli cookie-get session_id
|
|
playwright-cli cookie-set session_id abc123
|
|
playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
|
|
playwright-cli cookie-delete session_id
|
|
playwright-cli cookie-clear
|
|
|
|
# LocalStorage
|
|
playwright-cli localstorage-list
|
|
playwright-cli localstorage-get theme
|
|
playwright-cli localstorage-set theme dark
|
|
playwright-cli localstorage-delete theme
|
|
playwright-cli localstorage-clear
|
|
|
|
# SessionStorage
|
|
playwright-cli sessionstorage-list
|
|
playwright-cli sessionstorage-get step
|
|
playwright-cli sessionstorage-set step 3
|
|
playwright-cli sessionstorage-delete step
|
|
playwright-cli sessionstorage-clear
|
|
```
|
|
|
|
### Network
|
|
|
|
```bash
|
|
playwright-cli route "**/*.jpg" --status=404
|
|
playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
|
|
playwright-cli route-list
|
|
playwright-cli unroute "**/*.jpg"
|
|
playwright-cli unroute
|
|
```
|
|
|
|
### DevTools
|
|
|
|
```bash
|
|
playwright-cli console
|
|
playwright-cli console warning
|
|
playwright-cli network
|
|
playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
|
|
playwright-cli tracing-start
|
|
playwright-cli tracing-stop
|
|
playwright-cli video-start
|
|
playwright-cli video-stop video.webm
|
|
```
|
|
|
|
### Install
|
|
|
|
```bash
|
|
playwright-cli install --skills
|
|
playwright-cli install-browser
|
|
```
|
|
|
|
### Configuration
|
|
```bash
|
|
# Use specific browser when creating session
|
|
playwright-cli open --browser=chrome
|
|
playwright-cli open --browser=firefox
|
|
playwright-cli open --browser=webkit
|
|
playwright-cli open --browser=msedge
|
|
# Connect to browser via extension
|
|
playwright-cli open --extension
|
|
|
|
# Use persistent profile (by default profile is in-memory)
|
|
playwright-cli open --persistent
|
|
# Use persistent profile with custom directory
|
|
playwright-cli open --profile=/path/to/profile
|
|
|
|
# Start with config file
|
|
playwright-cli open --config=my-config.json
|
|
|
|
# Close the browser
|
|
playwright-cli close
|
|
# Delete user data for the default session
|
|
playwright-cli delete-data
|
|
```
|
|
|
|
### Browser Sessions
|
|
|
|
```bash
|
|
# create new browser session named "mysession" with persistent profile
|
|
playwright-cli -s=mysession open example.com --persistent
|
|
# same with manually specified profile directory (use when requested explicitly)
|
|
playwright-cli -s=mysession open example.com --profile=/path/to/profile
|
|
playwright-cli -s=mysession click e6
|
|
playwright-cli -s=mysession close # stop a named browser
|
|
playwright-cli -s=mysession delete-data # delete user data for persistent session
|
|
|
|
playwright-cli list
|
|
# Never use these during concurrent agent work; they affect unrelated sessions.
|
|
# Close all browsers
|
|
playwright-cli close-all
|
|
# Forcefully kill all browser processes
|
|
playwright-cli kill-all
|
|
```
|
|
|
|
## Example: Form submission
|
|
|
|
```bash
|
|
playwright-cli open https://example.com/form
|
|
playwright-cli snapshot
|
|
|
|
playwright-cli fill e1 "user@example.com"
|
|
playwright-cli fill e2 "password123"
|
|
playwright-cli click e3
|
|
playwright-cli snapshot
|
|
playwright-cli close
|
|
```
|
|
|
|
## Example: Multi-tab workflow
|
|
|
|
```bash
|
|
playwright-cli open https://example.com
|
|
playwright-cli tab-new https://example.com/other
|
|
playwright-cli tab-list
|
|
playwright-cli tab-select 0
|
|
playwright-cli snapshot
|
|
playwright-cli close
|
|
```
|
|
|
|
## Example: Debugging with DevTools
|
|
|
|
```bash
|
|
playwright-cli open https://example.com
|
|
playwright-cli click e4
|
|
playwright-cli fill e7 "test"
|
|
playwright-cli console
|
|
playwright-cli network
|
|
playwright-cli close
|
|
```
|
|
|
|
```bash
|
|
playwright-cli open https://example.com
|
|
playwright-cli tracing-start
|
|
playwright-cli click e4
|
|
playwright-cli fill e7 "test"
|
|
playwright-cli tracing-stop
|
|
playwright-cli close
|
|
```
|
|
|
|
## Specific tasks
|
|
|
|
* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
|
|
* **Running Playwright code** [references/running-code.md](references/running-code.md)
|
|
* **Browser session management** [references/session-management.md](references/session-management.md)
|
|
* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
|
|
* **Test generation** [references/test-generation.md](references/test-generation.md)
|
|
* **Tracing** [references/tracing.md](references/tracing.md)
|
|
* **Video recording** [references/video-recording.md](references/video-recording.md)
|