CDPWave Testing

Files (8)

• SKILL.md
• conftest.py · assets/templates/
• test_events.py · assets/templates/
• test_multi_tab.py · assets/templates/
• test_screenshot.py · assets/templates/
• async-patterns.md · references/
• cdp-domains.md · references/
• migration-pyppeteer.md · references/

SKILL.md (first lines)

# CDPWave Testing

## Description

cdpwave is a low-level Chrome DevTools Protocol (CDP) client for Python. It talks directly to Chrome's WebSocket endpoint — no Node.js, no ChromeDriver, no Selenium, no Playwright. Just pure async Python with full type hints. It is the CDP backend that powers wavexis and wavexis-mcp.

This skill covers writing browser automation tests with cdpwave at the CDP level, including async test patterns, multi-tab sessions, event handling, screenshots in CI, and the escape hatch for uncovered CDP methods.

## When to Invoke

- Writing CDP-level browser tests in Python
- Needing direct Chrome DevTools Protocol access without abstractions
- Migrating from pyppeteer or pychrome to cdpwave
- Setting up pytest-asyncio fixtures for CDP testing
- Needing multi-tab session management in tests
- Handling CDP events in async test flows
- Using the escape hatch for CDP methods without typed wrappers

## Prerequisites

- Python 3.11+
- A Chromium-based browser (Chrome, Edge, Brave, or Chromium) installed
- `pip install cdpwave`
- `pip install pytest pytest-asyncio` (for testing)

## CDPClient Setup

### Launch a new browser

```python
import asyncio
from cdpwave import CDPClient

async def main() -> None:
    async with await CDPClient.launch(headless=True) as client:
        session = await client.new_page("https://example.com")
        result = await session.runtime.evaluate("document.title", return_by_value=True)
        print(result["result"]["value"])
        await session.close()

asyncio.run(main())
```

### Connect to an existing browser

```python
from cdpwave import CDPClient

async with await CDPClient.connect(host="localhost", port=9222) as client:
    session = await client.new_page("https://example.com")
```

### Connect via direct WebSocket URL

```python
from cdpwave import CDPClient

async with await CDPClient.connect(ws_url="ws://localhost:9222/devtools/page/123") as client:
    session = await client.new_page("https://example.com")
```

### Launch options

```python
client = await CDPClient.launch(
    headless=False,
    browser_path="/usr/bin/google-chrome",
    extra_args=["--disable-gpu", "--no-sandbox"],
    keepalive_interval=30,
    keepalive_timeout=10,
)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `headless` | `bool` | `True` | Run browser without UI |
| `browser_path` | `str \| None` | Auto-detect | Path to browser executable |
| `extra_args` | `list[str]` | `[]` | Extra Chrome flags |
| `keepalive_interval` | `int` | `30` | WebSocket ping interval (seconds) |
| `keepalive_timeout` | `int` | `10` | WebSocket pong timeout (seconds) |

## Session Management

### Create and close sessions

```python
async with await CDPClient.launch() as client:
    session = await client.new_page("https://example.com")
    # Work with session...
    await session.close()
```

### Multi-tab sessions

```python
async with await CDPClient.launch() as client:
    tab1 = await client.new_page("https://example.com")
    tab2 = await client.new_page("https://example.org")

    title1 = await tab1.runtime.evaluate("document.title", return_by_value=True)
    title2 = await tab2.runtime.evaluate("document.title", return_by_value=True)

    print(title1["result"]["value"])  # "Example Domain"
    print(title2["result"]["value"])  # "IANA-managed domains"

    # Track all active sessions
    for sid, session in client.sessions.items():
        print(f"Session {sid}: {await session.runtime.evaluate('location.href', return_by_value=True)}")
```

### Session lifecycle

```python
session = await client.new_page("https://example.com")

# Navigate
await session.page.navigate("https://example.org")

# Reload

From MathiasPaulenko/ai-toolkit, MIT.

More from MathiasPaulenko/ai-toolkit