fast-playwright

What this skill does

# Fast Playwright

This skill provides a persistent, headless browser environment optimized for LLM agents.
It keeps the browser open between calls to enable fast interactions.

## Setup

Run the installation script once to set up dependencies and download browsers:
```bash
node scripts/install.js
```

## Usage

All tools are executed via `client.js`. Arguments must be valid JSON.

```bash
node scripts/client.js <tool_name> '<json_args>'
```

### Options

| Option | Description |
|--------|-------------|
| `--session <id>` | Use isolated browser session (for multi-agent) |
| `--headed` | Show browser window (default: headless) |
| `--sessions` | List active sessions |
| `--stop` | Stop the server |

### Multi-Agent Session Isolation

Each session gets its own isolated browser context (cookies, storage, page state):

```bash
# Agent A uses session "agent-a"
node scripts/client.js --session agent-a browser_navigate '{"url": "https://site-a.com"}'

# Agent B uses session "agent-b" (completely isolated)
node scripts/client.js --session agent-b browser_navigate '{"url": "https://site-b.com"}'

# List active sessions
node scripts/client.js --sessions

# Without --session, uses shared "default" session
node scripts/client.js browser_navigate '{"url": "https://example.com"}'
```

Sessions auto-expire after 15 minutes of inactivity.

### Headed Mode (Visible Browser)

Add `--headed` to see the browser window:
```bash
node scripts/client.js --headed browser_navigate '{"url": "https://example.com"}'
```

Note: The server must be restarted to switch between headed/headless modes:
```bash
node scripts/client.js --stop
```

## Token Optimization

Most tools accept an `expectation` object to control output size:
```json
{
  "expectation": {
    "includeSnapshot": false,
    "diffOptions": { "enabled": true }
  }
}
```

## Tools Reference

### Navigation

#### `browser_navigate`
Navigate to a URL.
```bash
node scripts/client.js browser_navigate '{"url": "https://example.com"}'
```

#### `browser_navigate_back`
Go back to previous page.
```bash
node scripts/client.js browser_navigate_back '{}'
```

#### `browser_navigate_forward`
Go forward to next page.
```bash
node scripts/client.js browser_navigate_forward '{}'
```

### Interaction

#### `browser_click`
Click an element. Supports CSS, text, role selectors.
```bash
node scripts/client.js browser_click '{"selectors": [{"css": "button.submit"}]}'
```

#### `browser_type`
Type text into an element.
```bash
node scripts/client.js browser_type '{"selectors": [{"css": "#search"}], "text": "query"}'
```

#### `browser_press_key`
Press a keyboard key.
```bash
node scripts/client.js browser_press_key '{"key": "Enter"}'
```

#### `browser_hover`
Hover over an element.
```bash
node scripts/client.js browser_hover '{"selectors": [{"css": ".menu-item"}]}'
```

#### `browser_drag`
Drag and drop between elements.
```bash
node scripts/client.js browser_drag '{"startSelectors": [{"css": "#source"}], "endSelectors": [{"css": "#target"}]}'
```

#### `browser_select_option`
Select option in dropdown.
```bash
node scripts/client.js browser_select_option '{"selectors": [{"css": "select#country"}], "values": ["US"]}'
```

#### `browser_file_upload`
Upload files to file input.
```bash
node scripts/client.js browser_file_upload '{"paths": ["/path/to/file.pdf"]}'
```

#### `browser_handle_dialog`
Handle alert/confirm/prompt dialogs.
```bash
node scripts/client.js browser_handle_dialog '{"accept": true}'
```

### Page State

#### `browser_snapshot`
Get accessibility snapshot of current page.
```bash
node scripts/client.js browser_snapshot '{}'
```

#### `browser_take_screenshot`
Take a screenshot.
```bash
node scripts/client.js browser_take_screenshot '{"filename": "page.png"}'
```

#### `browser_evaluate`
Evaluate JavaScript on page.
```bash
node scripts/client.js browser_evaluate '{"function": "() => document.title"}'
```

#### `browser_console_messages`
Get console messages.
```bash
node scripts/client.js browser_console_messages '{}'
```

#### `browser_network_requests`
Get network requests.
```bash
node scripts/client.js browser_network_requests '{}'
```

### Element Discovery

#### `browser_find_elements`
Find elements by text, role, tag, or attributes.
```bash
node scripts/client.js browser_find_elements '{"searchCriteria": {"text": "Submit"}}'
```

#### `browser_inspect_html`
Extract and analyze HTML content.
```bash
node scripts/client.js browser_inspect_html '{"selectors": [{"css": "main"}]}'
```

### Tab Management

#### `browser_tab_list`
List all open tabs.
```bash
node scripts/client.js browser_tab_list '{}'
```

#### `browser_tab_new`
Open a new tab.
```bash
node scripts/client.js browser_tab_new '{"url": "https://example.com"}'
```

#### `browser_tab_select`
Select a tab by index.
```bash
node scripts/client.js browser_tab_select '{"index": 0}'
```

#### `browser_tab_close`
Close a tab.
```bash
node scripts/client.js browser_tab_close '{}'
```

### Browser Control

#### `browser_resize`
Resize browser window.
```bash
node scripts/client.js browser_resize '{"width": 1920, "height": 1080}'
```

#### `browser_close`
Close the browser.
```bash
node scripts/client.js browser_close '{}'
```

#### `browser_install`
Install the configured browser.
```bash
node scripts/client.js browser_install '{}'
```

### Utilities

#### `browser_wait_for`
Wait for text to appear/disappear or time to pass.
```bash
node scripts/client.js browser_wait_for '{"text": "Loading complete"}'
node scripts/client.js browser_wait_for '{"textGone": "Loading..."}'
node scripts/client.js browser_wait_for '{"time": 2}'
```

#### `browser_diagnose`
Analyze page complexity and performance.
```bash
node scripts/client.js browser_diagnose '{}'
```

### Batch Execution

#### `browser_batch_execute`
Execute multiple steps in sequence. Highly recommended for forms.
```bash
node scripts/client.js browser_batch_execute '{
  "steps": [
    {"tool": "browser_type", "arguments": {"selectors": [{"css": "#user"}], "text": "me"}},
    {"tool": "browser_type", "arguments": {"selectors": [{"css": "#pass"}], "text": "123"}},
    {"tool": "browser_click", "arguments": {"selectors": [{"css": "#login"}]}}
  ]
}'
```

## Selector Types

All interaction tools support multiple selector strategies:

- **CSS**: `{"css": "#id"}`, `{"css": ".class"}`, `{"css": "button[type=submit]"}`
- **Role**: `{"role": "button"}`, `{"role": "textbox", "text": "Search"}`
- **Text**: `{"text": "Click me"}`
- **Ref**: `{"ref": "e3"}` (from previous snapshot)

Multiple selectors act as fallbacks:
```json
{"selectors": [{"css": "#submit"}, {"role": "button", "text": "Submit"}]}
```