playwright-cli

Files (3)

• SKILL.md
• openai.yaml · agents/
• command-map.md · references/

SKILL.md (first lines)

# Playwright CLI

Use `playwright-cli` directly (already installed) to execute browser automation from natural-language requests.

## Quick Start

1. Verify the CLI is available:
   ```bash
   command -v playwright-cli >/dev/null 2>&1
   ```
2. Open a browser session:
   ```bash
   playwright-cli open https://example.com
   ```
3. Capture refs before ref-based commands:
   ```bash
   playwright-cli snapshot
   ```

## Natural-Language Execution Workflow

1. Parse the request into atomic actions.
2. Convert each action to command templates from `references/command-map.md`.
3. Run `playwright-cli snapshot` before commands that require element refs (`click`, `fill`, `check`, `select`, `hover`, `drag`, etc.) unless a fresh snapshot is already available.
4. Re-run `playwright-cli snapshot` after navigation or major DOM changes.
5. For assertions, prefer `playwright-cli eval` and parse the `### Result` value from stdout.
6. Treat `### Error` output as command failure, even when process exit code is `0`.
7. For screenshots, capture PNG first, then compress to JPEG with `ffmpeg` before final save/return.
8. Use explicit filenames when saving artifacts (screenshots, snapshots, PDFs, videos, storage state).
9. Return executed commands and key results (URLs, counts, file paths, errors).

## Command Mapping Rules

- Map intent verbs directly:
  - open/launch -> `open`
  - navigate -> `goto`
  - click/tap -> `click`
  - double click/double tap -> `dblclick`
  - type/input -> `type`
  - fill/set field -> `fill`
  - back/forward/refresh -> `go-back`/`go-forward`/`reload`
- Preserve user-provided optional flags and values.
- Omit optional args when unspecified.
- Use `-s=<name>` when the user asks for a named/session-isolated browser.
- Prefer native commands over `eval` and `run-code`; use `eval` or `run-code` only if no first-class command exists.
- Keep session names short and filesystem-safe (lowercase letters + numbers, no punctuation, target <= 12 chars) to avoid local socket path errors on macOS.

## Reliability Guardrails (Must Follow)

- Do not classify pass/fail from shell exit codes for `eval` or `run-code`.
- Always inspect command output:
  - If output contains `### Error`, treat as failure.
  - If output contains `### Result`, use that value for assertions.
- Prefer `eval` for boolean checks and DOM assertions.
- Use `run-code` for imperative Playwright flows only.
- `run-code` expects a valid JS expression; statements like bare `return ...` or `throw ...` are invalid.
- For JS snippets passed to `eval`, prefer expression-safe patterns:
  - Good: `Array.from(...).some(function(x){ ... })`
  - Risky in this CLI context: snippets that are parsed as non-expression wrappers.
- When user requests pass and fail screenshots:
  - Capture one screenshot per scenario after assertion.
  - Capture to temporary PNG, then convert with `ffmpeg` to JPEG as the final artifact.
  - Name final files with scenario status prefix, e.g. `pass-<name>.jpg`, `fail-<name>.jpg`.
  - Save a machine-readable index file (`results.txt` or JSON) mapping scenario -> status -> final JPEG artifact path.

## Screenshot Compression Rule (Required)

- Always return compressed JPEG screenshots, not raw PNG screenshots.
- Required flow:
  1. Capture screenshot to temporary PNG path.
  2. Compress to JPEG with `ffmpeg`.
  3. Return/report only the JPEG path.
- Default command pattern:
  ```bash
  playwright-cli screenshot --full-page --filename "$TMP_PNG"
  ffmpeg -y -i "$TMP_PNG" -q:v 4 "$FINAL_JPG"
  ```
- If `ffmpeg` is unavailable, stop and report the missing dependency instead of returning an uncompressed PNG.

## Session and Artifact Conventions

- Use default session unless the user requests named sessions.
- Keep multi-step flows in one session for continuity.
- Place generated artifacts in predictable paths when the user does not specify:
  - `output/playwright/*.jpg`
  - `output/playwright/*.pdf`
  - `output/playwright/*.json`
  - `output/playwright/*.zip`

## Full Command Coverage

Load `references/command-map.md` when mapping or validating command usage. It contains the complete command catalog for:

- Core
- Navigation
- Keyboard
- Mouse
- Save as
- Tabs
- Storage (state, cookies, localStorage, sessionStorage)
- Network
- DevTools
- Install
- Configuration
- Sessions

From IvanCampos/agents, MIT.

More from IvanCampos/agents