Principle:SeleniumHQ Selenium CDP Session Management
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, DevTools, Session_Management |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Mechanism for attaching a CDP client to a specific browser target (tab/page) to scope subsequent commands and events.
Description
The Chrome DevTools Protocol uses a target-based model where each browser tab, page, worker, and extension is a separate "target". Before sending CDP commands, the client must attach to a specific target to create a CDP session (distinct from the WebDriver session). DevTools.createSession() discovers available targets via Target.getTargets(), selects the matching page target, and attaches to it, obtaining a SessionID used for all subsequent commands.
The target selection algorithm filters for targets with type "page" and optionally matches against a WebDriver window handle. If a windowHandle is provided (e.g., "CDwindow-24426957AC62D8BC83E58C184C38AF2D"), it selects the target whose TargetID is a suffix of the handle. If no handle is specified, it selects the first available page target.
After attaching, the method also sends Target.setAutoAttach() and Log.clear() in parallel as background setup operations.
Usage
Call createSession() or createSessionIfThereIsNotOne() after obtaining the DevTools object. The session automatically targets the current page. When switching tabs, call createSession() again with the new window handle. Use createSessionIfThereIsNotOne() for idempotent session creation that avoids redundant re-attachment to the same target.
Theoretical Basis
# Pseudocode: CDP Session Creation
1. If WebSocket connection is closed, reopen it
2. Call Target.getTargets() to list all browser targets
3. Filter targets to type "page"
4. If windowHandle provided:
- Find target whose TargetID is a suffix of the windowHandle
Else:
- Select the first page target
5. Call Target.attachToTarget(targetId) with null parent session
(attaches as child of browser session, not child of existing page session)
6. Server returns SessionID, stored internally for command routing
7. In parallel: send Target.setAutoAttach() and Log.clear()
8. All subsequent send() calls include this SessionID