Package Torello.Browser.JavaScriptAPI

Chrome DevTools Protocol – JavaScript & Runtime Domains

This package contains Java wrappers for CDP domains related to JavaScript execution and runtime behavior inside the browser. These domains include:


In real-world usage, the vast majority of this package boils down to one method:
RunTime.evaluate

This command executes arbitrary JavaScript code inside a live tab and returns the result. This method was the original impetus for writing even a single line of the Torello.Browser package and its sub-packages.

The author of this package does not claim to understand the full CDP specification. In fact, the Java bindings here were created primarily to support a single use case: triggering the execution of "Page Load" JavaScript on dynamic websites so that content could be extracted afterward. Static HTML scraping was no longer viable. In the world of Data Science & Web Scraping — collecting data from JavaScript-heavy web pages requires a real way to execute JavaScript inside a Java program, without manually opening a browser and using your hands to point, click, & download.


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 RunTime.callFunctionOn or Debugger.setBreakpointByUrl actually do — the best option is to 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!

Google's official DevTools documentation lacks clear examples, and few people in the Java ecosystem work with CDP directly. These wrappers were built to give structure to a protocol that otherwise resists understanding.

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