cdp-toolkit 1.4.1

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

CDP Toolkit

Freelance demos: https://ameobius-space.github.io/kwork-portfolio/

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	~140MB	~150MB	~13KB
Browser download	Yes (~200MB)	Yes (~100MB)	No
Cold start (import)	~200ms	~500ms	<1ms
Learning curve	Medium	High	Low
Speed	Fast	Slow	Fastest
Cloud-native	Yes	Partial	Yes

Metrics: measured via scripts/benchmark.py in CI (artifact: benchmark_results.json). cdp-toolkit: 12.6KB package, 0.34ms import, 0.3KB peak RAM on parameter-builder path. Playwright: 140MB package (pip, no browser binary). Run python scripts/benchmark.py to reproduce.

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.

Categories

CDP Toolkit is organized into focused, composable modules:

CDPClient

The core HTTP client for the Chrome DevTools Protocol. It manages tabs (targets), navigates pages, evaluates JavaScript, and captures screenshots, all without requiring Playwright, Selenium, or external browser drivers.

CDPInput

Helpers for text input and form handling. It can generate React/Vue/Angular-compatible native setter JavaScript, dispatch key events, and insert text, making it easy to drive forms in modern JavaScript apps.

CDPMouseEvents

Parameter builders for Input.dispatchMouseEvent. It covers clicks, right-clicks, double-clicks, hovers, pointer moves, and drag-and-drop interactions.

CDPNavigation

Page lifecycle helpers for navigation, evaluation, and screenshots. It builds Page.navigate, Runtime.evaluate, Page.captureScreenshot, and DOM.scrollIntoView parameters, and can wait for selectors or elements.

Usage Examples

Run the demo

python demo.py

Connect to a running Chrome instance

from cdp_toolkit import CDPClient

client = CDPClient("127.0.0.1", 9222)
print(client.list_targets())

Fill a React form

from cdp_toolkit import CDPClient, CDPInput

client = CDPClient("127.0.0.1", 9222)
tab = client.create_target("https://example.com")
js = CDPInput.native_setter_js("#email", "[e-mail]")
client.evaluate(tab["id"], js)

Click and drag

from cdp_toolkit import CDPClient, CDPMouseEvents

client = CDPClient("127.0.0.1", 9222)
# Click at (200, 300)
client.evaluate(tab_id, CDPMouseEvents.click(200, 300))
# Drag from (100, 100) to (400, 300)
client.evaluate(tab_id, CDPMouseEvents.drag(100, 100, 400, 300))

Navigate and take a screenshot

from cdp_toolkit import CDPClient, CDPNavigation

client = CDPClient("127.0.0.1", 9222)
client.navigate(tab_id, "https://example.com")
b64 = client.screenshot(tab_id)

Run the tests

python -m pytest tests/ -v

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

39 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

Hire on LaborX: https://laborx.com/gigs/python-automation-telegram-bots-cdp-api-integrations-105867

Real-World Use Cases

• LaborX batch apply: 270+ job applications via JWT Bearer + SOCKS5
• Kwork dialog monitoring: CDP9224 conversation tracking at scale
• Gmail API: OAuth2 automation for inbox monitoring across accounts
• Freelance pipeline: Automated bid → apply → track → report system
• Bug bounty recon: Subdomain enumeration + evidence collection

Articles

• Freelance Automation with CDP
• Automating Freelance Platforms with Python