Chrome CDP Controller (Puppeteer)

Control and automate a Chrome browser that's already running with CDP enabled, using Puppeteer.

Key Features

- Non-intrusive: Connects to your existing Chrome, opens a new tab, operates, then closes only that tab
Your browser stays open: Never closes your existing tabs or browser
Clean automation: Each task runs in its own tab, which is automatically closed when done

1. Chrome with CDP Enabled

Chrome must be running with remote debugging enabled. If not already started:

CODEBLOCK0

2. Get WebSocket URL

Visit http://localhost:9222/json/version to get the webSocketDebuggerUrl, for example:
CODEBLOCK1

Or use this one-liner:
CODEBLOCK2

3. Install Dependencies

CODEBLOCK3

This installs puppeteer-core which is lightweight (doesn't download Chromium).

Usage

Command-Based Execution

Create a JSON file with commands:

commands.json:
CODEBLOCK4

Execute:
CODEBLOCK5

Node.js API

CODEBLOCK6

Available Commands

Navigation

- navigate - Go to URL

- url: Target URL - waitUntil: "load", "domcontentloaded", or "networkidle2" (default)

Interaction

- click - Click an element

- selector: CSS selector - timeout: Timeout in milliseconds (default: 5000)

- fill - Fill a form field (selects all, then types)

- selector: CSS selector - text: Text to fill - timeout: Timeout in milliseconds (default: 5000)

- type - Type text character by character

- selector: CSS selector - text: Text to type - delay: Delay between characters in ms (default: 50) - timeout: Timeout in milliseconds (default: 5000)

- press - Press a key

- key: Key name (Enter, Tab, Escape, etc.)

Data Extraction

- get_text - Get text content of a single element

- selector: CSS selector

- getalltext - Get text content of all matching elements

- selector: CSS selector

- evaluate - Execute JavaScript and return result

- script: JavaScript code

Network Interception

- start_intercept - Start intercepting network responses

- url_pattern: URL pattern to match (substring match, e.g., "api")

- get_intercepted - Get all intercepted responses

- clear_intercepted - Clear intercepted responses list

Utilities

- screenshot - Take a screenshot

- path: Output file path - fullPage: Capture full page (default: false)

- waitforselector - Wait for element to appear

- selector: CSS selector - timeout: Timeout in milliseconds (default: 5000)

- wait - Sleep for a duration

- seconds: Number of seconds to wait

Common Workflows

Example 1: Search Taobao for iPhone Prices

taobao-search.json:
CODEBLOCK7

Run:
CODEBLOCK8

Note: Selectors may vary. Use browser DevTools (F12) to inspect elements.

Example 2: Ask ChatGPT a Question

chatgpt-ask.json:
CODEBLOCK9

Example 3: Intercept API Responses

intercept-api.json:
CODEBLOCK10

For more examples, see references/examples.md.

Workflow

When automating browser tasks:

1. Get WebSocket URL:

- If you already have it (e.g., ws://127.0.0.1:9222/devtools/browser/...), use it directly - Otherwise, fetch from INLINECODE25

2. Determine selectors:

- For known sites (Taobao, ChatGPT, etc.), check references/examples.md - For unknown sites, navigate first and use evaluate with document.querySelector to test selectors - Use browser DevTools (F12) to inspect elements

3. Build command sequence:

- Start with navigate - Add wait or wait_for_selector between steps - Use fill for form inputs, click for buttons - Use evaluate for complex data extraction - Add start_intercept before navigation if monitoring network traffic

4. Execute:

- Save commands to JSON file - Run: node scripts/cdp_controller.js --ws "<websocket-url>" --commands <file> - Parse JSON output

5. Handle failures:

- If selectors fail, inspect with DevTools - If timing issues occur, increase wait times or use wait_for_selector - If connection fails, verify Chrome is running with CDP enabled

Tips

- Wait times: Use wait_for_selector instead of fixed wait when possible
Selectors: Prefer ID (#id) > class (.class) > attribute ([attr='value'])
Network interception: Start intercepting BEFORE navigating
JavaScript: Use evaluate for complex data extraction
Screenshots: Useful for debugging

Troubleshooting

Connection Failed

- Ensure Chrome is running with INLINECODE43
Verify WebSocket URL is correct
Check Chrome version compatibility with puppeteer-core

Element Not Found

- Verify selector with DevTools (F12)
Add wait_for_selector before interaction
Check if element is in an iframe

Module Not Found

CODEBLOCK11

Chrome CDP 控制器 (Puppeteer)

使用 Puppeteer 控制和自动化一个已启用 CDP 并正在运行的 Chrome 浏览器。

主要特性

- 非侵入式：连接到您现有的 Chrome，打开一个新标签页，执行操作，然后仅关闭该标签页
您的浏览器保持打开：绝不会关闭您现有的标签页或浏览器
干净的自动化：每个任务在自己的标签页中运行，完成后自动关闭

1. 启用 CDP 的 Chrome

Chrome 必须以启用远程调试的方式运行。如果尚未启动：

bash

macOS

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 &

Windows

C:\Program Files\Google\Chrome\Application\chrome.exe --remote-debugging-port=9222

Linux

google-chrome --remote-debugging-port=9222 &

2. 获取 WebSocket URL

访问 http://localhost:9222/json/version 获取 webSocketDebuggerUrl，例如：

ws://127.0.0.1:9222/devtools/browser/FFA7276F8E8E51645BD2AC9BE6B79607

或者使用这个单行命令：
bash
curl -s http://localhost:9222/json/version | grep -o webSocketDebuggerUrl:[^]* | cut -d -f4

3. 安装依赖

bash
cd chrome-cdp-controller
npm install

这将安装轻量级的 puppeteer-core（不会下载 Chromium）。

使用方法

基于命令的执行

创建一个包含命令的 JSON 文件：

commands.json:
json
[
{type: navigate, url: https://www.baidu.com},
{type: wait, seconds: 2},
{type: screenshot, path: /tmp/screenshot.png},
{type: evaluate, script: document.title}
]

执行：
bash
node scripts/cdp_controller.js --ws ws://127.0.0.1:9222/devtools/browser/... --commands commands.json

Node.js API

javascript
const { CDPController } = require(./scripts/cdp_controller.js);

(async () => {
const controller = new CDPController(ws://127.0.0.1:9222/devtools/browser/...);
await controller.connect();

// 导航
await controller.navigate(https://www.taobao.com);

// 填写表单
await controller.fill(#q, iPhone);
await controller.press(Enter);
await controller.wait(3);

// 提取数据
const result = await controller.evaluate(
Array.from(document.querySelectorAll(.item))
.slice(0, 10)
.map(item => ({
title: item.querySelector(.title)?.textContent.trim(),
price: item.querySelector(.price)?.textContent.trim()
}))
);
console.log(result.result);

// 拦截网络
await controller.startIntercept(api);
// ... 执行操作 ...
const responses = controller.getInterceptedResponses();

await controller.close();
})();

可用命令

交互

- click - 点击元素

- selector: CSS 选择器 - timeout: 超时时间（毫秒，默认：5000）

- fill - 填写表单字段（全选后输入）

- selector: CSS 选择器 - text: 要填写的文本 - timeout: 超时时间（毫秒，默认：5000）

- type - 逐字符输入文本

- selector: CSS 选择器 - text: 要输入的文本 - delay: 字符间延迟（毫秒，默认：50） - timeout: 超时时间（毫秒，默认：5000）

- press - 按下按键

- key: 按键名称（Enter、Tab、Escape 等）

数据提取

- get_text - 获取单个元素的文本内容

- selector: CSS 选择器

- getalltext - 获取所有匹配元素的文本内容

- selector: CSS 选择器

- evaluate - 执行 JavaScript 并返回结果

- script: JavaScript 代码

网络拦截

- start_intercept - 开始拦截网络响应

- url_pattern: 匹配的 URL 模式（子字符串匹配，例如 api）

- get_intercepted - 获取所有拦截的响应

- clear_intercepted - 清除拦截的响应列表

工具

- screenshot - 截图

- path: 输出文件路径 - fullPage: 捕获整个页面（默认：false）

- waitforselector - 等待元素出现

- selector: CSS 选择器 - timeout: 超时时间（毫秒，默认：5000）

- wait - 等待一段时间

- seconds: 等待的秒数

常见工作流程

示例 1：在淘宝搜索 iPhone 价格

taobao-search.json:
json
[
{type: navigate, url: https://www.taobao.com},
{type: wait, seconds: 2},
{type: fill, selector: #q, text: iPhone},
{type: press, key: Enter},
{type: wait, seconds: 5},
{type: evaluate, script: Array.from(document.querySelectorAll(.item, [class=\Item\])).slice(0, 10).map(item => ({ title: item.querySelector(.title, [class=\title\])?.textContent.trim().substring(0, 80), price: item.querySelector(.price, [class*=\price\])?.textContent.trim() }))}
]

运行：
bash
WS_URL=$(curl -s http://localhost:9222/json/version | grep -o webSocketDebuggerUrl:[^]* | cut -d -f4)
node scripts/cdpcontroller.js --ws $WSURL --commands taobao-search.json

注意：选择器可能有所不同。请使用浏览器开发者工具（F12）检查元素。

示例 2：向 ChatGPT 提问

chatgpt-ask.json:
json
[
{type: navigate, url: https://chat.openai.com},
{type: waitforselector, selector: textarea, timeout: 10000},
{type: type, selector: textarea, text: 什么是人工智能？},
{type: press, key: Enter},
{type: wait, seconds: 10},
{type: get_text, selector: [data-message-author-role=assistant]:last-of-type}
]

示例 3：拦截 API 响应

intercept-api.json:
json
[
{type: startintercept, urlpattern: graphql},
{type: navigate, url: https://example.com},
{type: wait, seconds: 3},
{type: get_intercepted}
]

更多示例请参见 references/examples.md。

工作流程

自动化浏览器任务时：

1. 获取 WebSocket URL：

- 如果已有（例如 ws://127.0.0.1:9222/devtools/browser/...），直接使用 - 否则，从 http://localhost:9222/json/version 获取

2. 确定选择器：

- 对于已知网站（淘宝、ChatGPT 等），查看 references/examples.md - 对于未知网站，先导航并使用 evaluate 配合 document.querySelector 测试选择器 - 使用浏览器开发者工具（F12）检查元素

3. 构建命令序列：

- 以 navigate 开始 - 在步骤之间添加 wait 或 waitforselector - 使用 fill 填写表单输入，click 点击按钮 - 使用 evaluate 进行复杂数据提取 - 如果需要监控网络流量，在导航前添加 start_intercept

4. 执行：

- 将命令保存到 JSON 文件

chrome-cdp-controllerChrome浏览器控制