Implementation:SeleniumHQ Selenium CdpClientGenerator

Knowledge Sources	SeleniumHQ_Selenium
Domains	WebDriver, Code_Generation, DevTools_Protocol
Last Updated	2026-02-12 00:00 GMT

Overview

CdpClientGenerator reads Chrome DevTools Protocol (CDP) JSON schema files and generates type-safe Java client code for each CDP domain, packaging the output into a versioned JAR.

Description

The CdpClientGenerator is a build-time code generator that transforms CDP protocol JSON definitions (the browser protocol and the JavaScript protocol) into fully typed Java classes. It performs the following steps:

1. Reads two CDP protocol JSON files (browser protocol and JS protocol) and parses them using Selenium's Json utility.
2. Constructs an internal Model that holds a list of Domain objects, each containing types, commands, and events parsed from the JSON.
3. For each domain, generates Java source files using the JavaParser AST library:
   • A main domain class (e.g., Network.java) containing static methods for each command and event.
   • Model classes for complex types, placed in a model/ subdirectory.
   • Enum classes for enumerated string types.
4. Commands generate methods that return Command<T> objects with parameter validation, JSON serialization, and response deserialization via fromJson methods.
5. Events generate methods that return Event<T> objects with appropriate converter functions.
6. Type mappings handle: primitives (boolean, integer, number, string, any), enums, arrays, objects, and cross-domain $ref references.
7. All generated source files are packaged into a JAR under the path org/openqa/selenium/devtools/{version}/.

The generator supports the @Beta and @Deprecated annotations for experimental and deprecated protocol elements, and sanitizes Javadoc descriptions to prevent premature comment closure.

Usage

This tool is invoked by the Bazel build system to generate CDP client code for each supported CDP version (e.g., v85, v125). It is not meant for direct end-user invocation. Each Chrome/Edge major version corresponds to a generated CDP package version.

Code Reference

Source Location

• Repository: SeleniumHQ_Selenium
• File: java/src/org/openqa/selenium/devtools/CdpClientGenerator.java

Signature

public class CdpClientGenerator {

    public static void main(String[] args) throws IOException

    // Internal model hierarchy:
    private static class Model {
        public Model(String basePackage)
        public void parse(Map<String, Object> json)
        public void dumpTo(Path target)
    }

    private static class Domain extends BaseSpec {
        public void parse(Map<String, Object> json)
        public void dumpTo(Path target)
    }

    private static class CommandSpec extends TypedSpec {
        public MethodDeclaration toMethodDeclaration()
    }

    private static class EventSpec extends TypedSpec {
        public BodyDeclaration<?> toMethodDeclaration()
    }

    private static class TypeSpec extends TypedSpec {
        public void dumpTo(Path target)
    }

    // Type system interfaces and implementations:
    private interface IType {
        String getName();
        String getTypeToken();
        String getJavaType();
        String getJavaDefaultValue();
        TypeDeclaration<?> toTypeDeclaration();
        String getMapper();
    }
}

Import

import org.openqa.selenium.devtools.CdpClientGenerator;

I/O Contract

Inputs (Command-Line Arguments)

Argument	Position	Type	Description
Browser Protocol JSON	0	Path	Path to the CDP browser_protocol.json file
JS Protocol JSON	1	Path	Path to the CDP js_protocol.json file
Version	2	String	CDP version identifier (e.g., v125)
Output JAR	3	Path	Path for the output JAR containing generated Java sources

Output

Artifact	Description
Output JAR	A JAR containing generated Java source files organized as org/openqa/selenium/devtools/{version}/{domain}/ with domain classes and model subdirectories

CDP JSON to Java Type Mapping

CDP Type	Java Type
boolean	java.lang.Boolean
integer	java.lang.Integer
number	java.lang.Number
string	java.lang.String
any	java.lang.Object
object	java.util.Map<String, Object>
enum	Generated enum class with fromString() and toJson()
array	java.util.List<T>
$ref	Fully-qualified reference to generated type class

Usage Examples

# Typical Bazel-invoked generation (conceptual):
java -cp <classpath> org.openqa.selenium.devtools.CdpClientGenerator \
  browser_protocol.json \
  js_protocol.json \
  v125 \
  output/cdp-v125-sources.jar

// Example of generated code usage (consumer side):
import org.openqa.selenium.devtools.v125.network.Network;
import org.openqa.selenium.devtools.v125.network.model.RequestId;

// Enable network tracking via a generated command:
devTools.send(Network.enable(
    Optional.empty(),  // maxTotalBufferSize
    Optional.empty(),  // maxResourceBufferSize
    Optional.empty()   // maxPostDataSize
));

// Listen for a generated event:
devTools.addListener(Network.requestWillBeSent(), event -> {
    System.out.println("Request URL: " + event.getRequest().getUrl());
});

Related Pages

• SeleniumHQ_Selenium_DevTools_Send - DevTools send command API
• SeleniumHQ_Selenium_DevTools_CreateSession - DevTools session creation
• SeleniumHQ_Selenium_DevTools_AddListener - DevTools event listener API
• SeleniumHQ_Selenium_HasDevTools_GetDevTools - HasDevTools interface
• SeleniumHQ_Selenium_ModuleGenerator - Companion JPMS module generator
• SeleniumHQ_Selenium_Python_CDP_Generator - Python equivalent CDP code generator