Omair Saleh
2fb612b1df
- Static site: /manifesto, /live, /hire pages - Ship-log Pi extension: calvana_ship, calvana_oops, calvana_deploy tools - Docker + nginx deploy to calvana.quikcue.com - Terminal-ish dark aesthetic, mobile responsive - Auto-updating /live page from extension state
121 lines
4.7 KiB
Markdown
121 lines
4.7 KiB
Markdown
---
|
|
name: bowser
|
|
description: Headless browser automation using Playwright CLI. Use when you need headless browsing, parallel browser sessions, UI testing, screenshots, web scraping, or browser automation that can run in the background. Keywords - playwright, headless, browser, test, screenshot, scrape, parallel.
|
|
allowed-tools: Bash
|
|
---
|
|
|
|
# Playwright Bowser
|
|
|
|
## Purpose
|
|
|
|
Automate browsers using `playwright-cli` (via `@playwright/cli`) — a token-efficient CLI for Playwright. Runs headless by default, supports parallel sessions via named sessions (`-s=`), and doesn't load tool schemas into context.
|
|
|
|
## Prerequisites
|
|
|
|
Ensure the package is installed in the project:
|
|
```bash
|
|
bun add -d @playwright/cli
|
|
bunx playwright install chromium
|
|
```
|
|
|
|
## Key Details
|
|
|
|
- **Headless by default** — pass `--headed` to `open` to see the browser
|
|
- **Parallel sessions** — use `-s=<name>` to run multiple independent browser instances
|
|
- **Persistent profiles** — cookies and storage state preserved between calls
|
|
- **Token-efficient** — CLI-based, no accessibility trees or tool schemas in context
|
|
- **Vision mode** (opt-in) — set `PLAYWRIGHT_MCP_CAPS=vision` to receive screenshots as image responses in context instead of just saving to disk
|
|
|
|
## Sessions
|
|
|
|
**Always use a named session.** Derive a short, descriptive kebab-case name from the user's prompt. This gives each task a persistent browser profile (cookies, localStorage, history) that accumulates across calls.
|
|
|
|
```bash
|
|
# Derive session name from prompt context:
|
|
# "test the checkout flow on mystore.com" → -s=mystore-checkout
|
|
# "scrape pricing from competitor.com" → -s=competitor-pricing
|
|
# "UI test the login page" → -s=login-ui-test
|
|
|
|
bunx playwright-cli -s=mystore-checkout open https://mystore.com --persistent
|
|
bunx playwright-cli -s=mystore-checkout snapshot
|
|
bunx playwright-cli -s=mystore-checkout click e12
|
|
```
|
|
|
|
Managing sessions:
|
|
```bash
|
|
bunx playwright-cli list # list all sessions
|
|
bunx playwright-cli close-all # close all sessions
|
|
bunx playwright-cli -s=<name> close # close specific session
|
|
bunx playwright-cli -s=<name> delete-data # wipe session profile
|
|
```
|
|
|
|
## Quick Reference
|
|
|
|
```
|
|
Core: open [url], goto <url>, click <ref>, fill <ref> <text>, type <text>, snapshot, screenshot [ref], close
|
|
Navigate: go-back, go-forward, reload
|
|
Keyboard: press <key>, keydown <key>, keyup <key>
|
|
Mouse: mousemove <x> <y>, mousedown, mouseup, mousewheel <dx> <dy>
|
|
Tabs: tab-list, tab-new [url], tab-close [index], tab-select <index>
|
|
Save: screenshot [ref], pdf, screenshot --filename=f
|
|
Storage: state-save, state-load, cookie-*, localstorage-*, sessionstorage-*
|
|
Network: route <pattern>, route-list, unroute, network
|
|
DevTools: console, run-code <code>, tracing-start/stop, video-start/stop
|
|
Sessions: -s=<name> <cmd>, list, close-all, kill-all
|
|
Config: open --headed, open --browser=chrome, resize <w> <h>
|
|
```
|
|
|
|
## Workflow
|
|
|
|
1. Derive a session name from the user's prompt and open with `--persistent` to preserve cookies/state. Always set the viewport via env var at launch:
|
|
```bash
|
|
PLAYWRIGHT_MCP_VIEWPORT_SIZE=1440x900 bunx playwright-cli -s=<session-name> open <url> --persistent
|
|
# or headed:
|
|
PLAYWRIGHT_MCP_VIEWPORT_SIZE=1440x900 bunx playwright-cli -s=<session-name> open <url> --persistent --headed
|
|
# or with vision (screenshots returned as image responses in context):
|
|
PLAYWRIGHT_MCP_VIEWPORT_SIZE=1440x900 PLAYWRIGHT_MCP_CAPS=vision bunx playwright-cli -s=<session-name> open <url> --persistent
|
|
```
|
|
|
|
3. Get element references via snapshot:
|
|
```bash
|
|
bunx playwright-cli snapshot
|
|
```
|
|
|
|
4. Interact using refs from snapshot:
|
|
```bash
|
|
bunx playwright-cli click <ref>
|
|
bunx playwright-cli fill <ref> "text"
|
|
bunx playwright-cli type "text"
|
|
bunx playwright-cli press Enter
|
|
```
|
|
|
|
5. Capture results:
|
|
```bash
|
|
bunx playwright-cli screenshot
|
|
bunx playwright-cli screenshot --filename=output.png
|
|
```
|
|
|
|
6. **Always close the session when done.** This is not optional — close the named session after finishing your task:
|
|
```bash
|
|
bunx playwright-cli -s=<session-name> close
|
|
```
|
|
|
|
## Configuration
|
|
|
|
If a `playwright-cli.json` exists in the working directory, use it automatically. If the user provides a path to a config file, use `--config path/to/config.json`. Otherwise, skip configuration — the env var and CLI defaults are sufficient.
|
|
|
|
```json
|
|
{
|
|
"browser": {
|
|
"browserName": "chromium",
|
|
"launchOptions": { "headless": true },
|
|
"contextOptions": { "viewport": { "width": 1440, "height": 900 } }
|
|
},
|
|
"outputDir": "./screenshots"
|
|
}
|
|
```
|
|
|
|
## Full Help
|
|
|
|
Run `bunx playwright-cli --help` or `bunx playwright-cli --help <command>` for detailed command usage.
|