Browser Automation

Bucky supports interactive browser automation via playwright-cli in web preset sessions. This enables visual testing, screenshot capture, form interactions, and authenticated browsing.

How it works

The setup-playwright action (called by setup-web) installs:

1. Playwright Chromium — headless browser (npx playwright install --with-deps chromium)
2. playwright-cli — interactive browser tool (npm install -g @playwright/cli)
3. CLI config — .playwright/cli.config.json auto-discovered by playwright-cli

The config sets:

• Headless Chromium browser
• ignoreHTTPSErrors: true
• Optional authentication cookies via storage state

Caution

Claude runners must use playwright-cli for browser automation, not Playwright’s Node.js API directly. The CLI handles auth cookies, browser config, and provides an interactive interface designed for AI agents.

Authentication cookies

For testing authenticated pages, pass cookies via the web-auth-cookies input on your caller workflow:

jobs:
  dispatch:
    uses: fetch-rewards/buck-bronson/.github/workflows/bucky-dispatch.yml@v1
    with:
      preset: web
      web-auth-cookies: ${{ secrets.WEB_AUTH_COOKIES }}
    secrets: inherit

The web-auth-cookies value is a base64-encoded JSON array of cookie objects:

[
  {
    "name": "session_id",
    "value": "abc123",
    "domain": ".example.com",
    "path": "/",
    "httpOnly": true,
    "secure": true,
    "sameSite": "Lax",
    "expires": 1735689600
  }
]

Note

Base64 encoding prevents GitHub Actions from masking secret values in the cookie data. The setup action decodes it and writes a Playwright storage state file to /tmp/playwright-storage-state.json.

Cookie object fields

Field	Type	Description
name	string	Cookie name
value	string	Cookie value
domain	string	Cookie domain (include leading . for subdomains)
path	string	Cookie path
httpOnly	boolean	HTTP-only flag
secure	boolean	Secure flag
sameSite	string	Strict, Lax, or None
expires	number	Unix timestamp expiry

Screenshots and file upload

During sessions, Claude runners can capture screenshots and upload them via the agent’s POST /api/upload endpoint. The FILE_UPLOAD_URL environment variable is set automatically in dispatch workflows.

Screenshots should be included in PR descriptions for web changes — showing before/after visual state.

CLI config

The generated .playwright/cli.config.json:

{
  "browser": {
    "browserName": "chromium",
    "headless": true
  },
  "contextOptions": {
    "ignoreHTTPSErrors": true,
    "storageState": "/tmp/playwright-storage-state.json"
  }
}

The storageState field is only included when cookies are provided. The config file is auto-discovered by playwright-cli via the .playwright/ directory convention.