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

Playwright is pre-installed in the base session pod image. Browser automation is available in all sessions without additional setup. The image includes:

1. Playwright Chromium — headless browser
2. playwright-cli — interactive browser tool designed for AI agents
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, auth cookies can be configured via the session pod environment. The WEB_AUTH_COOKIES environment variable accepts a base64-encoded JSON array of cookie objects. When set, the session entrypoint writes a Playwright storage state file that playwright-cli picks up automatically.

Example cookie format:

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

Note

Base64 encoding prevents secret values in the cookie data from being logged. The session entrypoint 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 session pods.

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

Pearl also uses the upload endpoint to capture snippet previews — rendered screenshots of published snippets are hosted on S3 + CloudFront and shared in Slack threads.

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.