cdp-toolkit 1.3.0

Chrome DevTools Protocol automation toolkit — WebSocket CDP client, screenshots, DOM, network interception

CDP Toolkit

Chrome DevTools Protocol automation — WebSocket client, screenshots, DOM, network. Zero dependencies.

What's New in 1.3.0

• CDPWebSocket — full RFC 6455 WebSocket client for CDP communication
• CDPClient.send_command() — send any CDP method over WebSocket
• Screenshots — screenshot() and save_screenshot() with full-page capture
• DOM methods — query_selector(), get_dom_tree(), set_input_value(), click_element()
• Navigation — navigate(), evaluate(), wait_for_element(), scroll_to()
• CDPNetwork — cookie management, user agent override, extra headers, request inspection
• CDPNavigation — print-to-PDF parameters, enhanced evaluate with awaitPromise
• CDPInput — type_text_js() for realistic character-by-character typing
• CDPMouseEvents — drag_params() for drag-and-drop sequences

Features

• CDPWebSocket — RFC 6455 WebSocket client using only stdlib (socket, struct, base64, hashlib)
• CDPClient — HTTP tab management + WebSocket CDP session in one client
• CDPMouseEvents — mouse click, release, move, drag parameters for Input.dispatchMouseEvent
• CDPInput — text injection, key events, React/Vue native setter JS, realistic typing simulation
• CDPNavigation — navigate, evaluate JS, screenshot, print-to-PDF parameters
• CDPNetwork — cookie management, user agent spoofing, custom headers, request inspection
• Pure Python stdlib — no playwright, no selenium, no puppeteer, no websockets, no requests

Quick Start

pip install cdp-toolkit

Launch Chrome with remote debugging:

google-chrome --remote-debugging-port=9222
# or headless:
google-chrome --headless --remote-debugging-port=9222 --no-sandbox

Tab Management (HTTP)

from cdp_client import CDPClient

client = CDPClient("127.0.0.1", 9222)

# List all open tabs
tabs = client.list_targets()

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

# Activate and close
client.activate_target(tab["targetId"])
client.close_target(tab["targetId"])

# Browser version info
print(client.get_version())

Full CDP Session (WebSocket)

from cdp_client import CDPClient

client = CDPClient("127.0.0.1", 9222)
client.connect_ws()  # Connect to first page tab

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

# Evaluate JavaScript
title = client.evaluate("document.title")
print(f"Page title: {title}")

# Take screenshot
client.save_screenshot("page.png")

# Full-page screenshot as JPEG
img_bytes = client.screenshot(format="jpeg", quality=90, full_page=True)

# DOM interaction
client.set_input_value("#search", "hello world")
client.click_element("#submit-btn")

# Wait for dynamic content
if client.wait_for_element(".results", timeout=10):
    text = client.get_text(".results")

# Raw CDP command
resp = client.send_command("Network.enable")
resp = client.send_command("Runtime.evaluate", {
    "expression": "1 + 1",
    "returnByValue": True,
})

client.disconnect_ws()

Network Interception

from cdp_client import CDPClient, CDPNetwork

client = CDPClient("127.0.0.1", 9222)
client.connect_ws()

# Set custom user agent
client.send_command("Network.enable")
client.send_command("Network.setUserAgentOverride",
    CDPNetwork.set_user_agent_params(
        "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
        accept_language="en-US",
        platform="iPhone",
    ))

# Set cookies
client.send_command("Network.setCookie",
    CDPNetwork.set_cookie_params(
        name="session",
        value="abc123",
        domain=".example.com",
        http_only=True,
        secure=True,
        same_site="Lax",
    ))

# Get all cookies
cookies = client.send_command("Network.getCookies")
print(cookies["result"]["cookies"])

Print to PDF

from cdp_client import CDPClient, CDPNavigation

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

import base64
resp = client.send_command("Page.printToPDF",
    CDPNavigation.print_to_pdf_params(
        print_background=True,
        paper_width=8.27,  # A4
        paper_height=11.69,
    ))
pdf_bytes = base64.b64decode(resp["result"]["data"])
with open("page.pdf", "wb") as f:
    f.write(pdf_bytes)

React/Vue Form Fill

from cdp_client import CDPInput

# Native setter bypasses React's synthetic event system
js = CDPInput.native_setter_js("#email", "[e-mail]")
# Send via CDP Runtime.evaluate

# Or use the high-level method:
client.set_input_value("#email", "[e-mail]")

Testing

python -m pytest tests/ -v

Use Cases

• Browser automation without Playwright/Selenium dependencies
• Screenshot capture for monitoring and CI
• Web scraping with JavaScript rendering
• Form automation on React/Vue/Angular sites
• PDF generation from web pages
• Cookie/session management for authenticated scraping
• Docker-friendly — ~50MB image vs 250MB+ with Playwright

API Reference

CDPClient(host, port)

Method	Description
list_targets()	List all browser tabs (HTTP)
create_target(url)	Open new tab (HTTP)
close_target(id)	Close tab (HTTP)
activate_target(id)	Focus tab (HTTP)
get_version()	Browser version info (HTTP)
find_target(url_contains)	Find tab by URL substring
connect_ws(url_contains)	Connect WebSocket to tab
send_command(method, params)	Raw CDP command over WebSocket
navigate(url, wait)	Navigate and optionally wait for load
evaluate(js)	Execute JavaScript, return result
screenshot(fmt, quality, full_page)	Capture screenshot as bytes
save_screenshot(path, ...)	Save screenshot to file
query_selector(sel)	Find element, return nodeId
set_input_value(sel, val)	Set input value (React-safe)
click_element(sel)	Click element by selector
get_text(sel)	Get text content of element
scroll_to(x, y)	Scroll to coordinates
wait_for_element(sel, timeout)	Poll for element
disconnect_ws()	Close WebSocket

License

MIT