Implementation:SeleniumHQ Selenium DevTools CreateSession
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, DevTools, Session_Management |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Concrete tool for creating a CDP session attached to a specific browser target provided by the Selenium DevTools Java API.
Description
DevTools.createSession() and createSessionIfThereIsNotOne() attach the DevTools client to a browser tab target. The method queries available targets via Target.getTargets(), filters for "page" type targets, finds the one matching the provided window handle (or defaults to the first page target), and attaches to it using Target.attachToTarget(). The attachment is performed with a null parent session ID to create a child of the browser session (not a child of an existing page session), which avoids errors when later detaching.
After attaching, two parallel background operations are performed: Target.setAutoAttach() and Log.clear(). These complete within the configured timeout (default 30 seconds). The resulting SessionID is stored in a volatile field for routing all subsequent commands and events.
createSessionIfThereIsNotOne() adds idempotent behavior: if a session already exists targeting the same window handle, it is reused. If the window handle has changed, it disconnects the current session and re-attaches to the new target.
Usage
Call after obtaining a DevTools instance and before sending any CDP commands. Use createSessionIfThereIsNotOne() for idempotent session creation, or createSession() to force a new attachment (e.g., after tab switch).
Code Reference
Source Location
- Repository: Selenium
- File:
java/src/org/openqa/selenium/devtools/DevTools.java(L140-228)
Signature
public class DevTools implements Closeable {
public void createSession();
public void createSession(@Nullable String windowHandle);
public void createSessionIfThereIsNotOne();
public void createSessionIfThereIsNotOne(@Nullable String windowHandle);
public SessionID getCdpSession();
}
Import
import org.openqa.selenium.devtools.DevTools;
import org.openqa.selenium.devtools.idealized.target.model.SessionID;
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| windowHandle | String | No | Browser window handle (e.g., "CDwindow-24426957AC62D8BC83E58C184C38AF2D") to match against TargetID; null defaults to first page target |
Outputs
| Name | Type | Description |
|---|---|---|
| (void) | void | CDP session attached to target; SessionID stored internally in volatile field |
| getCdpSession() | SessionID | Returns the current CDP SessionID (null if no session) |
Exceptions
| Exception | Condition |
|---|---|
| DevToolsException | Unable to find a "page" type target matching the window handle |
| DevToolsException | Error during target attachment (wraps ExecutionException) |
| TimeoutException | Target attachment or parallel setup exceeds 30-second timeout |
| IllegalStateException | Thread interrupted during attachment |
Usage Examples
DevTools devTools = driver.getDevTools();
// Create session on current tab (first "page" target)
devTools.createSession();
// Or create session only if not already exists
devTools.createSessionIfThereIsNotOne();
// After switching tabs, create new session for the new tab
driver.switchTo().newWindow(WindowType.TAB);
devTools.createSession(driver.getWindowHandle());
// createSessionIfThereIsNotOne with window handle:
// - Reuses session if same handle
// - Disconnects and re-attaches if handle changed
devTools.createSessionIfThereIsNotOne(driver.getWindowHandle());