@armynante/playwright-cli

Playwright browser automation CLI designed for agent-driven execution. Execute browser actions via JSON commands with structured output for programmatic parsing.

Output Location

Default: Screenshots and reports are saved to the system temp directory ($TMPDIR/playwright-cli/).

Console Output

Console entries (console.log, console.error, etc.) are always captured inline in the JSON output:

{
  "success": true,
  "screenshots": [...],
  "console": [
    { "type": "log", "text": "User clicked button" },
    { "type": "error", "text": "API returned 404" }
  ],
  ...
}

Use --console-log <file> to also save detailed logs (timestamps, source locations) to a file.

This is ideal for agentic workflows:

• Files are temporary and don't need version control
• Multiple agents can run without conflicts
• Automatic OS cleanup handles old files

Override with -o, --output-dir if needed (not recommended for agentic use).

Command Types

Init Commands (Interactive)

One-time setup commands:

• init - Initialize config file
• install-agents - Install Claude Code subagents

Exec Commands (Non-Interactive, Agentic)

Designed for AI agents - no prompts, structured JSON output:

• exec - Execute JSON action sequences
• screenshot - Single URL screenshot
• batch - Multiple URL screenshots
• screenshot-storybook-component - Storybook component screenshots

JSON Output Format

All exec commands output structured JSON to stdout:

{
  "success": true,
  "screenshots": [
    "/var/folders/.../playwright-cli/screenshot-1234.png"
  ],
  "console": [
    { "type": "log", "text": "Page loaded" },
    { "type": "error", "text": "API error: 404" }
  ],
  "reports": {
    "console": "/path/to/console.json",
    "network": "/path/to/network.json"
  },
  "message": "Captured 1 screenshot",
  "exitCode": 0,
  "results": [...]
}

Note: console is always present (inline entries). reports only appears when --console-log or --network-log flags are used.

Parsing Output

# Capture and parse in one command
OUTPUT=$(playwright-cli exec '[{"action":"goto","url":"..."},{"action":"screenshot"}]')
SCREENSHOT=$(echo $OUTPUT | jq -r '.screenshots[0]')
# AI agent can now read the screenshot file

Agent Quick Reference

# Execute browser actions via JSON
playwright-cli exec '[{"action":"goto","url":"https://example.com"},{"action":"screenshot"}]'

# With console and network capture
playwright-cli exec \
  --console-log console.json \
  --network-log network.json \
  '[{"action":"goto","url":"..."},{"action":"click","selector":"#btn"}]'

# Screenshot a Storybook component
playwright-cli screenshot-storybook-component src/components/Button.stories.tsx --storybook-url http://localhost:6006

Exit Codes: 0=success, 1=general error, 2=navigation, 3=element not found, 4=timeout, 5=browser launch, 6=invalid action

Exec Command (Agent Mode)

The exec command is designed for non-interactive, agent-driven browser automation.

Usage

playwright-cli exec [options] '<json-actions>'

Options

| Option | Description | |--------|-------------| | -o, --output-dir <dir> | Screenshot output directory (default: system temp) | | -b, --browser <type> | Browser: chromium, firefox, webkit (default: chromium) | | --headless | Run headless (default: true) | | --no-headless | Run with visible browser | | -t, --timeout <ms> | Global timeout in milliseconds (default: 30000) | | --verbose | Show progress on stderr | | --console-log <file> | Save detailed console log to file (console always captured inline) | | --network-log <file> | Capture network activity to JSON file |

JSON Actions

All actions are passed as a JSON array. Each action supports an optional timeout field (ms).

goto - Navigate to URL

{"action": "goto", "url": "https://example.com", "timeout": 30000}

click - Click element

{"action": "click", "selector": "#submit-btn", "force": false, "timeout": 5000}

fill - Fill input field

{"action": "fill", "selector": "input[name='email']", "value": "[email protected]", "timeout": 5000}

select - Select dropdown option(s)

{"action": "select", "selector": "#country", "values": "US", "timeout": 5000}
{"action": "select", "selector": "#fruits", "values": ["apple", "banana"], "timeout": 5000}

wait - Wait for element

{"action": "wait", "selector": "#loading", "state": "hidden", "timeout": 10000}

States: visible (default), hidden, attached, detached

waitForText - Wait for text to appear

{"action": "waitForText", "text": "Success!", "timeout": 10000}

delay - Wait fixed time

{"action": "delay", "ms": 2000}

screenshot - Take screenshot

{"action": "screenshot", "filename": "result.png", "fullPage": true}

info - Get page metadata

{"action": "info"}

Returns: url, title, meta, links, headings

Exit Codes

| Code | Meaning | When | |------|---------|------| | 0 | Success | All actions completed | | 1 | General error | Unexpected error | | 2 | Navigation error | Failed to load URL, network error | | 3 | Element not found | Selector didn't match any element | | 4 | Timeout | Action exceeded timeout | | 5 | Browser launch error | Failed to start browser | | 6 | Invalid action | Malformed JSON or unknown action |

Console Log Format

{
  "capturedAt": "2025-12-08T20:00:00.000Z",
  "entries": [
    {
      "timestamp": "2025-12-08T20:00:00.100Z",
      "type": "log",
      "text": "User clicked button",
      "args": ["User clicked button"],
      "location": {"url": "https://...", "lineNumber": 42, "columnNumber": 10}
    }
  ]
}

Types: log, debug, info, error, warning, trace

Network Log Format

{
  "capturedAt": "2025-12-08T20:00:00.000Z",
  "requests": [
    {
      "id": "req-123",
      "timestamp": "2025-12-08T20:00:00.050Z",
      "method": "GET",
      "url": "https://api.example.com/data",
      "resourceType": "fetch",
      "headers": {"accept": "application/json"},
      "postData": null
    }
  ],
  "responses": [
    {
      "id": "req-123",
      "timestamp": "2025-12-08T20:00:00.150Z",
      "status": 200,
      "statusText": "OK",
      "url": "https://api.example.com/data",
      "headers": {"content-type": "application/json"}
    }
  ],
  "failures": []
}

Storybook Screenshot Command

Screenshot a Storybook component from its .stories.tsx file.

Prerequisites

• Storybook must be running (npm run storybook)
• --storybook-url is required

Usage

playwright-cli screenshot-storybook-component <story-file> --storybook-url <url> [options]

Options

| Option | Description | |--------|-------------| | --storybook-url <url> | Storybook server URL (required) | | -o, --output-dir <dir> | Screenshot output directory (default: system temp) |

Examples

# Screenshot a component (--storybook-url is REQUIRED)
playwright-cli screenshot-storybook-component src/components/Button.stories.tsx --storybook-url http://localhost:6006

Output

{
  "success": true,
  "screenshots": [
    "/var/folders/.../playwright-cli/components-button--primary.png"
  ],
  "reports": {
    "console": "/var/folders/.../playwright-cli/console-1702156800000.json"
  },
  "message": "Screenshot captured for Components/Button",
  "exitCode": 0,
  "results": {
    "title": "Components/Button",
    "storyId": "components-button--primary"
  }
}

Other Commands

screenshot - Single URL screenshot

Take a screenshot of a single URL with optional console capture.

playwright-cli screenshot <url> [options]
playwright-cli screenshot https://example.com -f

| Option | Description | |--------|-------------| | -f, --full-page | Capture full page (not just viewport) | | -w, --wait <ms> | Wait time after page load in ms | | --verbose | Show progress on stderr | | -o, --output-dir <dir> | Screenshot output directory (default: system temp) | | -v, --viewport <WxH> | Viewport size (e.g., "1280x720") |

batch - Multiple URL screenshots

Take screenshots of multiple URLs from a file. Each URL should be on a separate line.

playwright-cli batch <urls-file> [options]
playwright-cli batch urls.txt -c 3 -d 1000

| Option | Description | |--------|-------------| | -c, --concurrency <n> | Number of concurrent screenshots (default: 3) | | -d, --delay <ms> | Delay between screenshots in ms (default: 0) | | -w, --wait <ms> | Wait time after page load in ms |

Each URL gets its own browser page for true parallel processing. Progress is reported via onProgress callback in programmatic API.

init - Initialize project config

playwright-cli init

install-agents - Install Claude Code agents

playwright-cli install-agents

Configuration

Create .playwright-cli.json:

{
  "browser": "chromium",
  "headless": true,
  "viewport": "1280x720",
  "timeout": 30000,
  "waitAfterLoad": 0,
  "fullPage": false
}

Note: outputDir defaults to the system temp directory and is not typically needed in the config file.

Programmatic API

import { createPlaywrightService } from '@armynante/playwright-cli';

const service = createPlaywrightService({
  browser: 'chromium',
  headless: true,
});

await service.launch();
await service.navigate('https://example.com');
await service.click('#btn');
await service.fill('#input', 'value');
await service.waitFor('#element');
await service.waitForText('Success');
const result = await service.screenshotCurrentPage({ filename: 'test.png' });
const info = await service.getPageInfo();
await service.close();

Installation

bun add @armynante/playwright-cli

Or with CodeArtifact:

aws codeartifact login --tool npm --repository npm-private --domain armynante --domain-owner 846818564997 --region us-east-1 --profile default
bun add @armynante/playwright-cli

Development & Bug Fixes

Source Location: Modules/playwright-cli/

If you encounter bugs or need new features:

1. Fix the issue in the source package
2. Test locally: bun run src/cli/index.ts exec '[...]'
3. Bump version in package.json
4. Republish to CodeArtifact:

   bun run build
   npm publish

5. Update dependent projects: bun update @armynante/playwright-cli

Do not work around bugs in consuming code - fix them at the source and republish.

Testing

Run the test suite:

bun test

Run specific test files:

bun test test/cli/screenshot.test.ts
bun test test/cli/exec.test.ts

Test structure:

• test/backend/ - Unit tests for config and service
• test/cli/ - CLI command integration tests
• test/*.test.ts - Integration tests for PlaywrightService

License

MIT