browser-automation

name	browser-automation
source	botcore
description	Guides browser automation via botcore's CDP (Chrome DevTools Protocol) command suite. Covers session management (launch/attach/close), navigation and waiting, element interaction (click/type/fill/drag), DOM inspection with Shadow DOM traversal, diagnostics (screenshot/console/network/eval), form filling, multi-page management, and device emulation. Use when automating browsers, scraping web pages, testing web UIs, filling forms, taking screenshots, debugging frontend issues, or working with Shadow DOM components. Triggers: CDP, browser, Chrome, Chromium, automation, screenshot, click, fill form, Shadow DOM, console log, navigate, scrape, headless.
version	1.0.0
triggers	["CDP","browser","Chrome","Chromium","automation","screenshot","click","fill form","Shadow DOM","console log","navigate","scrape","headless","browser automation","web testing","cdp launch","cdp close","DevTools Protocol"]
portable	true

Automating Browsers

Expert guidance for browser automation using botcore's CDP command suite — 28+ commands for controlling Chromium via the Chrome DevTools Protocol.

Capabilities

1. Manage Browser Sessions -- Launch, attach to, and close Chromium instances with persistent profiles
2. Navigate and Wait -- Load pages and wait for selectors, text, or custom conditions
3. Interact with Elements -- Click, hover, scroll, drag, type, and press keys with modifier support
4. Inspect the DOM -- Query elements, read properties/attributes/styles, and traverse Shadow DOM
5. Fill Forms -- Fill individual fields, batch-fill forms, upload files, and handle dialogs
6. Capture Diagnostics -- Take screenshots, read console logs, evaluate JavaScript, and emulate devices
7. Manage Pages -- Open, close, list, and switch between browser tabs

Routing Logic

Request Type	Load Reference
Launching, attaching, closing sessions, profile directories	references/session-management.md
Click, hover, scroll, drag, type, press, modifier keys	references/interaction.md
Query elements, inspect properties, Shadow DOM, accessibility snapshot	references/inspection.md
Screenshot, console, eval, emulate, network	references/diagnostics.md
Form filling, file upload, dialogs, page management	references/forms-and-pages.md

Core Principles

1. Session-First Workflow

Always launch or attach before any other CDP command. Always close when done to avoid orphaned Chrome processes. The workflow is: launch → interact → close.

Sessions are persisted to .botcore/cdp-session.json. If a session file exists, commands connect to the existing session automatically.

2. Selectors and Shadow DOM

Use CSS selectors for element targeting. Set `deep=True` to traverse Shadow DOM boundaries automatically. Use `::shadow` syntax for explicit shadow root traversal: `host-element::shadow .inner`.

Most modern web components use Shadow DOM. If a selector doesn't match, try deep=True before assuming the element doesn't exist.

3. Wait Before Interacting

After navigation, wait for the target element before interacting with it. Use `cdp_wait(selector=...)` for elements, `cdp_wait(text=...)` for content, or `cdp_wait(ms=...)` for timed delays.

4. Console Logs Are Accumulated

Console messages are captured throughout the session and saved to the session file. Use `cdp_console()` to review them. Use `cdp_console(clear=True)` to reset.

Command Quick Reference

Session Lifecycle

Command	Purpose
cdp_launch(url, headless, port, profile_dir)	Launch new Chromium instance
cdp_attach(endpoint, port)	Attach to existing Chrome
cdp_close()	Close session and optionally kill process

Navigation

Command	Purpose
cdp_navigate(url, wait_until)	Navigate to URL
cdp_wait(selector, ms, text, hidden)	Wait for condition

Interaction

Command	Purpose
cdp_click(selector, button, double, ctrl, shift, deep)	Click element
cdp_hover(selector, deep)	Hover over element
cdp_scroll(selector, x, y, deep)	Scroll to element or by offset
cdp_drag(selector, to, dx, dy)	Drag element
cdp_type(text, selector, delay_ms, deep)	Type text
cdp_press(key, selector, deep)	Press key combination

Inspection

Command	Purpose
cdp_query(selector, deep)	Find elements (returns up to 10)
cdp_inspect(selector, prop, attr, style, text, visible)	Read element details
cdp_snapshot(root_selector)	Accessibility tree snapshot

Forms and Pages

Command	Purpose
cdp_fill(selector, value, deep)	Fill input/select
cdp_fill_form(fields)	Batch fill {selector: value}
cdp_upload(selector, file_path, deep)	Upload file
cdp_handle_dialog(action, prompt_text)	Handle alert/confirm/prompt
cdp_list_pages()	List open tabs
cdp_select_page(index)	Switch to tab
cdp_new_page(url)	Open new tab
cdp_close_page(index)	Close tab
cdp_resize(width, height)	Resize viewport

Diagnostics

Command	Purpose
cdp_screenshot(path, full_page)	Capture screenshot
cdp_console(tail, level, grep, clear)	Read/filter console logs
cdp_eval(expression)	Execute JavaScript
cdp_emulate(color_scheme, viewport, user_agent, offline)	Emulate device

Typical Workflow

1. cdp_launch(url="https://example.com")
2. cdp_wait(selector="#main-content")
3. cdp_screenshot()                        — verify page loaded
4. cdp_fill_form({"#email": "[e-mail]", "#password": "pass"})
5. cdp_click("#submit-button")
6. cdp_wait(selector=".success-message")
7. cdp_screenshot()                        — verify result
8. cdp_console(level="error")              — check for JS errors
9. cdp_close()

Checklist

• Session launched or attached before first interaction
• cdp_wait() used after navigation and before interaction
• Shadow DOM traversal enabled where needed (deep=True)
• Screenshots taken at key checkpoints for verification
• Console logs checked for JavaScript errors
• Session closed when done (cdp_close())