Browser Use

Browser automation (Playwright)

Use native Python Playwright scripts to automate browsing and UI verification for any URL, including local development servers and external sites.

Prerequisites

Read skill-local guidance only when .kilocode/skills/browser-use/AGENTS.md is confirmed to exist; otherwise use root AGENTS.md for project-specific Playwright installation notes, server commands, and local URLs.

Helper scripts available (all paths project-relative):

• .kilocode/skills/browser-use/scripts/with_server.py - Optional. Manages local dev server lifecycle (supports multiple servers).

Always run scripts with --help first to see usage. DO NOT read the source until you try running the script first and find that a customized solution is absolutely necessary. These scripts can be very large and thus pollute your context window. They exist to be called directly as black-box scripts rather than ingested into your context window.

Output files: Examples and scripts write screenshots/logs to an outputs/ folder relative to the current working directory. The folder is created automatically if it does not exist.

Decision tree: choosing your approach

User task → What is the target?
    ├─ Local HTML file (file://) → Read HTML file directly to identify selectors.
    │     💡 Use `Path(file).as_uri()` to get the correct `file:///` URL — never use `http://localhost/filename`.
    │     ├─ Success → Write Playwright script using selectors.
    │     └─ Fails/Incomplete → Treat as dynamic (below).
    └─ URL (http/https) → Do you control the server process?
          ├─ Yes (local dev server) → Is it already running?
          │     ├─ No → Run the local `.kilocode/skills/browser-use/scripts/with_server.py` helper with `--help`
          │     │        Then use the helper + write a simplified Playwright script.
          │     └─ Yes → Reconnaissance-then-action (below).
          └─ No (external site) → Reconnaissance-then-action (below).

Example: using with_server.py (optional)

Use this only when you need to start and manage one or more local dev servers as part of automation. with_server.py starts the server(s), waits until they are ready, runs your automation script, then cleans up. Run --help first before using it.

Single server (run from project root):

python .kilocode/skills/browser-use/scripts/with_server.py --server "<start command>" --port <port> -- python <automation-script>.py

Multiple servers (e.g., backend + frontend):

python .kilocode/skills/browser-use/scripts/with_server.py `
  --server "<backend start command>" --port <backend-port> `
  --server "<frontend start command>" --port <frontend-port> `
  -- python <automation-script>.py --url <url>

Your automation script only needs Playwright logic — servers are managed automatically by with_server.py. See this skill folder's examples for robust, ready-to-use boilerplate.

Reconnaissance-Then-Action Pattern

💡 Tip for Users: You can rapidly generate selectors and scripts by running playwright codegen <url> in your terminal.

1. Inspect rendered DOM.

   page.screenshot(path='outputs/inspect.png', full_page=True)
   content = page.content()
   page.locator('button').all()
   

2. Identify selectors from inspection results.
3. Execute actions using discovered selectors.

Common Pitfall

❌ Don't rely on networkidle as it is flaky on modern apps with background polling. ✅ Do wait for a specific element to be visible: page.wait_for_selector('.main-content') before inspection. ❌ Don't use operating-system-specific temp paths unless the project guidance confirms them. ✅ Do use a relative outputs/ directory (auto-created by examples). ❌ Don't default to async_playwright — async adds complexity without benefit for one-off automation scripts. ✅ Do use sync_playwright() (synchronous) unless you have an explicit reason to use async (e.g., integrating with an async framework).

Best Practices

• Use bundled scripts as black boxes - To accomplish a task, consider whether one of the scripts available in this skill folder's scripts/ directory can help. These scripts handle common, complex workflows reliably without cluttering the context window. Use --help to see usage, then invoke directly.
• Use sync_playwright() for synchronous scripts
• Always close the browser when done (use try/finally)
• Use descriptive selectors: text=, role=, CSS selectors, or IDs
• Add appropriate waits: page.wait_for_selector() — not networkidle
• Output files go in a relative outputs/ directory; create it with Path('outputs').mkdir(parents=True, exist_ok=True)

Reference Files

All paths below are project-relative.

• scripts/ - Helper scripts (call with --help first; do NOT read source):

  • .kilocode/skills/browser-use/scripts/with_server.py - Starts one or more local dev servers, runs your automation script, then cleans up

• examples/ - Automation scripts (pass these to with_server.py or run standalone):

  • .kilocode/skills/browser-use/examples/basic_automation.py - Robust boilerplate with error handling and wait_for_selector
  • .kilocode/skills/browser-use/examples/element_discovery.py - Discovering buttons, links, and inputs on a page
  • .kilocode/skills/browser-use/examples/static_html_automation.py - Using file:// URLs for local HTML
  • .kilocode/skills/browser-use/examples/console_logging.py - Capturing console logs during automation