Package Torello.Browser.BrowserAPI

Chrome DevTools Protocol – Browser Control & Infrastructure Domains

This package contains Java wrappers for CDP domains that manage the browser itself — creating tabs, navigating pages, adjusting emulation settings, managing downloads, capturing screenshots, and more. These domains include:

These classes each expose static methods which return Script objects — Java wrappers representing individual CDP command invocations. To actually run any of them, pass the Script to a WebSocketSender instance, typically obtained from BrowserConn.createSender or PageConn.createSender.

Author’s Disclaimer: The author of this package does not claim to understand what most of these CDP methods actually do. The code was generated by parsing Chrome’s browser_protocol.json and wrapping each command into a strongly-typed Java method — without any documentation from Google to explain what these commands mean or return.

The original purpose of this package was to support dynamic website scraping: enabling RunTime.evaluate calls inside real browser tabs by first launching Chrome, creating a new tab, and establishing a WebSocket session. All of that required the underlying control features offered by this package.


Mere JSON-Wrappers:
The classes found in Torello.Browser.BrowserAPI and Torello.Browser.JavaScriptAPI perform **no browser processing** of any kind — zero. They are nothing more than structural glue that converts between Java and JSON. These classes are purely data transformers: they take Java-Typed Method-Arguments, which have been supplied by the user, marshal them into Chrome-Compatible JSON-Payloads, and return Script objects that have the capability to send this JSON-Request over a WebSocket. This is is executed by invoking the Script.exec(...) method. This method returns a Promise object.

When the browser replies, the Promise instance that was just returned by exec() will perform the specified JSON-Response processing. That promise receives the JSON-Response and un-marshals it — i.e., extracts typed Java values from the JSON structure — returning them as usable Java-Types back to the caller. That's it. That’s the whole process.

Important: These classes do **not** implement any control logic, flow logic, decision trees, emulation, validation, or browser-side semantics. There is no intelligence or conditionality in these files — not even simple logic like error checks or null guards. Their one and only job is listed here, below.
  • Generate JSON from typed Java parameters
  • Return a Script object that contains & encapsulates BOTH the JSON-Request AND a response handler, within
  • Parse JSON-Responses from Chrome and extract typed Java results
Because they are so completely mechanical in nature — just Java-to-JSON and JSON-to-Java — these classes are **100% machine-generated**. Not a single line of code in either of these two packages was hand-written. There is no reason for them to be — the logic is deterministic, repetitive, and exhaustively derived from the Chrome DevTools Protocol definitions.


Asking for Help:
Best Practice: If you're trying to figure out what a method like Target.createTarget or Page.captureScreenshot actually does — the best thing you can do is ask Chat-GPT. That is, quite literally, how most of this package's documentation has been written; and more importantly, the only real way to get to know Google's Auto-Generated CDP API (unless you are already familiar with Google's CDP Project!). See Also: Chrome DevTools Protcol on GitHub.

Chat-GPT, in particular, has been the LLM that has demonstrated an expert level of knowledge in the use of Google's Chrome-Browser Exported API. Moreover, explaining to this particular LLM that the Torello.Browser package is simply auto-generating JSON-Wrappers to connect Java (over WebSockets) to the browser has been extremely simple and refreshing — Chat-GPT seemed to understand exactly what I was doing. It practically knew better than I, what I was doing! It was, perspicaciously, explaining to me how my own utility / tool works!

This documentation page was written with the assistance of Chat-GPT. The official CDP documentation from Google is extremely sparse, and the Chrome DevTools Protocol is rarely used directly by Java developers. These Java wrappers were created to provide a bridge — not an explanation.

Page originally drafted by ChatGPT on 2025-08-02.
Edited and formatted for use in Chrome DevTools Protocol Documentation.