| 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
- Manage Browser Sessions -- Launch, attach to, and close Chromium instances with persistent profiles
- Navigate and Wait -- Load pages and wait for selectors, text, or custom conditions
- Interact with Elements -- Click, hover, scroll, drag, type, and press keys with modifier support
- Inspect the DOM -- Query elements, read properties/attributes/styles, and traverse Shadow DOM
- Fill Forms -- Fill individual fields, batch-fill forms, upload files, and handle dialogs
- Capture Diagnostics -- Take screenshots, read console logs, evaluate JavaScript, and emulate devices
- 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": "user@test.com", "#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
