WDIO CDP Bridge

A lightweight connector for the Node debugger using the Chrome DevTools Protocol (CDP), designed for the WebdriverIO Electron Service.

📋 Table of Contents

• WDIO CDP Bridge
  • 📋 Table of Contents
  • 📦 Installation
  • 🔍 Overview
  • 💻 Usage Examples
    • DevTool
    • CdpBridge
  • 📚 API Reference
    • DevTool
      • Constructor Options
      • Methods
        • version()
        • list()
    • CdpBridge
      • Constructor Options
      • Methods
        • connect()
        • on(event, listener)
        • send(method, params?)
        • close()
        • state
  • 🔧 Troubleshooting
    • Connection Issues
    • Command Failures
  • 🤝 Contributing
  • 📄 License
  • 📚 Further Reading

📦 Installation

1# Using npm
2npm install @wdio/cdp-bridge
3
4# Using yarn
5yarn add @wdio/cdp-bridge
6
7# Using pnpm
8pnpm add @wdio/cdp-bridge

🔍 Overview

The CDP Bridge provides a simple interface for connecting to and interacting with the Node debugger through the Chrome DevTools Protocol (CDP). It offers:

• Automatic connection and reconnection to Node debugger instances
• Type-safe command execution with TypeScript support
• Event-based communication for receiving debugger events
• Lightweight implementation with minimal dependencies

This library is especially useful for:

• Debugging Electron applications
• Interacting with Node.js processes programmatically
• Automating DevTools operations in testing environments

💻 Usage Examples

DevTool

The DevTool class provides a low-level interface for communicating with the Node debugger:

1import { DevTool } from '@wdio/cdp-bridge';
2
3// Initialize with default settings (localhost:9229)
4const devTool = new DevTool();
5
6// Or with custom settings
7// const devTool = new DevTool({ host: 'localhost', port: 9229 });
8
9// Get debugger version information
10const version = await devTool.version();
11console.log(version);
12// Output:
13// {
14//   "browser": "node.js/v20.18.1",
15//   "protocolVersion": "1.1"
16// }
17
18// List available debugging targets
19const list = await devTool.list();
20console.log(list);
21// Output:
22// [{
23//   "description": "node.js instance",
24//   // ...other properties
25//   "webSocketDebuggerUrl": "ws://localhost:9229/31ab611d-a1e7-4149-94ba-ba55f6092d92"
26// }]

CdpBridge

The CdpBridge class provides a higher-level interface with event handling and typed commands:

1import { CdpBridge } from '@wdio/cdp-bridge';
2
3async function example() {
4  // Initialize with default settings
5  const cdp = new CdpBridge();
6
7  // Connect to the debugger
8  await cdp.connect();
9
10  // Listen for specific CDP events
11  const events = [];
12  cdp.on('Runtime.executionContextCreated', (event) => {
13    console.log('New execution context created:', event);
14    events.push(event);
15  });
16
17  // Enable the Runtime domain to receive its events
18  await cdp.send('Runtime.enable');
19
20  // Execute JavaScript in the remote context
21  const result = await cdp.send('Runtime.evaluate', {
22    expression: '1 + 3',
23    returnByValue: true,
24  });
25
26  console.log('Evaluation result:', result.result.value); // 4
27
28  // Disable the Runtime domain when done
29  await cdp.send('Runtime.disable');
30
31  // Close the connection
32  await cdp.close();
33}
34
35example().catch(console.error);

📚 API Reference

DevTool

The DevTool class provides methods for basic CDP interactions.

Constructor Options

Option	Type	Default	Description
host	string	'localhost'	Hostname of the debugger
port	number	9229	Port number of the debugger
timeout	number	10000	Connection timeout in milliseconds

Methods

version()

Returns version metadata about the debugger.

1const versionInfo = await devTool.version();

Return value:

1{
2  "browser": "node.js/v20.18.1",
3  "protocolVersion": "1.1"
4}

list()

Returns a list of all available WebSocket debugging targets.

1const debugTargets = await devTool.list();

Return value:

1[
2  {
3    "description": "node.js instance",
4    "devtoolsFrontendUrl": "devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=localhost:9229/9b3ce98c-082f-4555-8c1b-e50d3fdddf42",
5    "devtoolsFrontendUrlCompat": "devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=localhost:9229/9b3ce98c-082f-4555-8c1b-e50d3fdddf42",
6    "faviconUrl": "https://nodejs.org/static/images/favicons/favicon.ico",
7    "id": "9b3ce98c-082f-4555-8c1b-e50d3fdddf42",
8    "title": "electron/js2c/browser_init",
9    "type": "node",
10    "url": "file://",
11    "webSocketDebuggerUrl": "ws://localhost:9229/9b3ce98c-082f-4555-8c1b-e50d3fdddf42"
12  }
13]

CdpBridge

The CdpBridge class provides a higher-level interface for CDP communication.

Constructor Options

Option	Type	Default	Description
host	string	'localhost'	Hostname of the debugger
port	number	9229	Port number of the debugger
timeout	number	10000	Request timeout in milliseconds
waitInterval	number	100	Retry interval in milliseconds
connectionRetryCount	number	3	Maximum number of connection retry attempts

Methods

connect()

Establishes a connection to the debugger. Automatically retries on failure based on the connectionRetryCount setting.

1await cdpBridge.connect();

on(event, listener)

Registers an event listener for CDP events.

Parameter	Type	Description
event	string	CDP event name (e.g., Runtime.executionContextCreated)
listener	(params: any) => void	Callback function that receives event parameters

1cdpBridge.on('Runtime.executionContextCreated', (context) => {
2  console.log('New context:', context);
3});

send(method, params?)

Sends a CDP command and returns the result. Fully typed with TypeScript when using appropriate type imports.

Parameter	Type	Description
method	string	CDP method name (e.g., Runtime.evaluate)
params	object	Optional parameters for the command (method-specific)

1const result = await cdpBridge.send('Runtime.evaluate', {
2  expression: 'document.title',
3  returnByValue: true,
4});

close()

Closes the WebSocket connection to the debugger.

1await cdpBridge.close();

state

Property that returns the current WebSocket connection state:

• undefined: Not connected
• 0 (WebSocket.CONNECTING): Connection in progress
• 1 (WebSocket.OPEN): Connection established
• 2 (WebSocket.CLOSING): Connection closing
• 3 (WebSocket.CLOSED): Connection closed

1const connectionState = cdpBridge.state;

🔧 Troubleshooting

Connection Issues

If you're having trouble connecting to the debugger:

1. Verify the debugger is running: Make sure your Node/Electron process is started with the --inspect or --inspect-brk flag.

2. Check port availability: The default port (9229) might be in use. Try specifying a different port.

3. Connection timeout: Increase the timeout value if you're experiencing timeouts.

   1const cdp = new CdpBridge({ timeout: 30000 }); // 30 seconds

4. Retry settings: Adjust the retry count and interval for unstable connections.

   1const cdp = new CdpBridge({
   2  connectionRetryCount: 5,
   3  waitInterval: 500, // 500ms between retries
   4});

Command Failures

If CDP commands are failing:

1. Check domain initialization: Some commands require their domain to be enabled first.

   1// Enable the domain before using its commands
   2await cdp.send('Runtime.enable');

2. Verify method name: Ensure you're using the correct method name and parameter structure.

3. Connection state: Make sure the connection is in the OPEN state before sending commands.

   1if (cdp.state === 1) {
   2  // WebSocket.OPEN
   3  await cdp.send('Runtime.evaluate', {
   4    /* params */
   5  });
   6}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📚 Further Reading

• Chrome DevTools Protocol Viewer - Official CDP documentation
• Node.js Debugging Guide - Guide to Node.js debugging
• WebdriverIO Documentation - WebdriverIO API documentation