cdp-toolkit 1.4.0

Chrome DevTools Protocol automation toolkit — zero-dependency, ~15KB vs 300MB Playwright

CDP Toolkit

Chrome DevTools Protocol automation without external dependencies. No Playwright, no Selenium, no Puppeteer. Pure Python stdlib.

Install

pip install cdp-toolkit

Why CDP Toolkit?

Feature	Playwright	Selenium	cdp-toolkit
Dependencies	50+ packages	20+ packages	0
Install size	~300MB	~150MB	~15KB
Browser download	Yes (~200MB)	Yes (~100MB)	No
Learning curve	Medium	High	Low
Speed	Fast	Slow	Fastest
Cloud-native	Yes	Partial	Yes

CDP Toolkit talks directly to Chrome's DevTools Protocol via HTTP and WebSocket. You bring your own Chrome instance (local, Docker, or cloud), and CDP Toolkit handles the rest.

Quick Start

from cdp_toolkit import CDPClient

# Connect to a Chrome instance with --remote-debugging-port=9222
client = CDPClient("127.0.0.1", 9222)

# List open tabs
tabs = client.list_targets()
for tab in tabs:
    print(f"{tab['id'][:8]} | {tab['url'][:60]}")

# Create a new tab
new_tab = client.create_target("https://example.com")

# Navigate
client.navigate(new_tab['id'], "https://httpbin.org/forms/post")

# Execute JavaScript
title = client.evaluate(new_tab['id'], "document.title")
print(f"Page title: {title}")

React/Vue Form Filling

The most common CDP use case: filling forms on React/Vue/Angular sites where standard input.value = "x" does not trigger reactivity.

from cdp_toolkit import CDPInput

# Generate native setter JavaScript for React
js_code = CDPInput.native_setter_js(
    selector="#email",
    value="[e-mail]"
)
# Execute via CDP — triggers React's onChange handler

# For Vue.js
js_code = CDPInput.vue_setter_js(
    selector="input[name='phone']",
    value="[phone]"
)

# Key-by-key typing simulation
js_code = CDPInput.simulate_typing(
    selector="#search",
    text="hello world",
    delay_ms=50
)

Mouse Events

from cdp_toolkit import CDPMouseEvents

# Click at coordinates
params = CDPMouseEvents.click(x=200, y=300)

# Right-click
params = CDPMouseEvents.click(x=200, y=300, button="right")

# Double-click
params = CDPMouseEvents.double_click(x=200, y=300)

# Drag and drop
params = CDPMouseEvents.drag(
    start_x=100, start_y=200,
    end_x=400, end_y=300
)

Navigation and Screenshots

from cdp_toolkit import CDPNavigation

# Navigate and wait for load
client.navigate_and_wait(tab_id, "https://example.com")

# Take screenshot
screenshot_b64 = client.screenshot(tab_id)

# Scroll to element
js = CDPNavigation.scroll_to_element("#footer")
client.evaluate(tab_id, js)

# Wait for selector
js = CDPNavigation.wait_for_selector(".result-card", timeout_ms=5000)

Anti-Detection

CDP Toolkit includes JavaScript snippets to make automation less detectable:

from cdp_toolkit import stealth

# Remove webdriver flag
client.evaluate(tab_id, stealth.remove_webdriver_flag())

# Override navigator properties
client.evaluate(tab_id, stealth.override_navigator())

# Add realistic timing jitter
CDPInput.set_typing_delay(min_ms=30, max_ms=120)

Docker Integration

Run Chrome in Docker and control it with CDP Toolkit:

# Dockerfile
FROM chrome/headless
EXPOSE 9222
CMD ["chrome", "--remote-debugging-port=9222", "--no-sandbox"]

# Connect to Docker Chrome
client = CDPClient("chrome-container", 9222)

Testing

python -m pytest tests/ -v --tb=short

38 tests covering all modules. Zero external dependencies in tests.

API Reference

CDPClient

Method	Description
list_targets()	List all open tabs/pages
create_target(url)	Open a new tab
close_target(id)	Close a tab
activate_target(id)	Focus a tab
navigate(id, url)	Navigate to URL
evaluate(id, js)	Execute JavaScript
screenshot(id)	Capture page screenshot

CDPInput

Method	Description
native_setter_js(sel, val)	React-compatible value setter
vue_setter_js(sel, val)	Vue.js-compatible value setter
simulate_typing(sel, text, delay)	Human-like typing simulation
key_event(key)	Send keyboard event

CDPMouseEvents

Method	Description
click(x, y, button)	Mouse click
double_click(x, y)	Double click
drag(sx, sy, ex, ey)	Drag and drop
hover(x, y)	Mouse hover

License

MIT — see LICENSE

Links

• GitHub
• PyPI
• Full templates collection