Best headless browser for AI agents. Lite, Fast, High-Compatibility. Built in Rust
Rust ai-agentsai-toolsbrowserbrowser-automationcloud-browserheadlessheadless-browserkitesurfplaywrightpuppeteerrustservoweb-crawlerweb-crawlingweb-scraperweb-scraping
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::{Map, Value};
use std::{error::Error, fmt};
/// CDP response class for a command that could not enter the typed wire
/// envelope.
///
/// Syntax/EOF failures are JSON-RPC parse errors. A syntactically valid JSON
/// value whose known CDP fields have the wrong shape is an invalid request,
/// matching Chromium's `Dispatchable::DispatchError` split.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CdpCommandParseErrorKind {
ParseError,
InvalidRequest,
}
/// Failure to construct a typed [`ParsedCdpCommand`].
///
/// `command_id` is recovered only on the invalid path, after the normal
/// single-pass parse has failed. Valid commands therefore do not pay for a
/// second JSON parse, while a structurally invalid request can still receive
/// the response id Chromium would preserve.
#[derive(Debug)]
pub struct CdpCommandParseError {
kind: CdpCommandParseErrorKind,
command_id: Option<u64>,
source: serde_json::Error,
}
impl CdpCommandParseError {
fn from_str(json: &str, source: serde_json::Error) -> Self {
let kind = match source.classify() {
serde_json::error::Category::Data => CdpCommandParseErrorKind::InvalidRequest,
serde_json::error::Category::Io
| serde_json::error::Category::Syntax
| serde_json::error::Category::Eof => CdpCommandParseErrorKind::ParseError,
};
let command_id = if kind == CdpCommandParseErrorKind::InvalidRequest {
serde_json::from_str::<Value>(json)
.ok()
.as_ref()
.and_then(Value::as_object)
.and_then(|message| message.get("id"))
.and_then(Value::as_u64)
} else {
None
};
Self {
kind,
command_id,
source,
}
}
fn from_value(command_id: Option<u64>, source: serde_json::Error) -> Self {
let kind = match source.classify() {
serde_json::error::Category::Data => CdpCommandParseErrorKind::InvalidRequest,
serde_json::error::Category::Io
| serde_json::error::Category::Syntax
| serde_json::error::Category::Eof => CdpCommandParseErrorKind::ParseError,
};
Self {
kind,
command_id: if kind == CdpCommandParseErrorKind::InvalidRequest {
command_id
} else {
None
},
source,
}
}
pub const fn kind(&self) -> CdpCommandParseErrorKind {
self.kind
}
pub const fn command_id(&self) -> Option<u64> {
self.command_id
}
pub const fn response_code(&self) -> i32 {
match self.kind {
CdpCommandParseErrorKind::ParseError => -32700,
CdpCommandParseErrorKind::InvalidRequest => -32600,
}
}
pub const fn response_message(&self) -> &'static str {
match self.kind {
CdpCommandParseErrorKind::ParseError => "Parse error",
CdpCommandParseErrorKind::InvalidRequest => "Invalid Request",
}
}
}
impl fmt::Display for CdpCommandParseError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
self.source.fmt(formatter)
}
}
impl Error for CdpCommandParseError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
Some(&self.source)
}
}
/// Validated top-level fields of one inbound CDP command.
///
/// Known CDP fields remain strongly typed after validation. `extension_fields`
/// retains unknown top-level fields so frontend routing can rewrite `id` and
/// `sessionId` without discarding extensions from a newer CDP version.
#[derive(Debug, Deserialize, Serialize)]
#[serde(try_from = "IncomingCdpRequest")]
pub struct CdpRequest {
id: u64,
method: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
params: Option<Map<String, Value>>,
#[serde(rename = "sessionId", default, skip_serializing_if = "Option::is_none")]
session_id: Option<String>,
#[serde(flatten)]
extension_fields: Map<String, Value>,
}
#[derive(Deserialize)]
struct IncomingCdpRequest {
id: u64,
method: String,
#[serde(default)]
params: Option<Value>,
#[serde(
rename = "sessionId",
default,
deserialize_with = "deserialize_session_id"
)]
session_id: Option<String>,
#[serde(flatten)]
extension_fields: Map<String, Value>,
}
fn deserialize_session_id<'de, D>(deserializer: D) -> Result<Option<String>, D::Error>
where
D: Deserializer<'de>,
{
// Absent routing is allowed; an explicitly supplied route must be a string.
String::deserialize(deserializer).map(Some)
}
impl TryFrom<IncomingCdpRequest> for CdpRequest {
type Error = &'static str;
fn try_from(incoming: IncomingCdpRequest) -> Result<Self, Self::Error> {
// Chromium's parameterless Browser.close ignores its entire params
// value. Keep that rule in the canonical parser, including arrays and
// scalars, so transport control uses the same validated envelope.
let params = if incoming.method == "Browser.close" {
None
} else {
match incoming.params {
None => None,
Some(Value::Object(params)) => Some(params),
Some(_) => return Err("params must be an object"),
}
};
Ok(Self {
id: incoming.id,
method: incoming.method,
params,
session_id: incoming.session_id,
extension_fields: incoming.extension_fields,
})
}
}
impl CdpRequest {
pub fn id(&self) -> u64 {
self.id
}
pub fn method(&self) -> &str {
&self.method
}
pub fn params(&self) -> Option<&Map<String, Value>> {
self.params.as_ref()
}
pub fn session_id(&self) -> Option<&str> {
self.session_id.as_deref()
}
fn rewrite_frontend_route(
&mut self,
internal_command_id: u64,
dispatch_session_id: Option<&str>,
) {
self.id = internal_command_id;
self.session_id = dispatch_session_id.map(str::to_owned);
}
fn rewrite_target_session_reference(&mut self, session_id: &str) {
self.params
.get_or_insert_default()
.insert("sessionId".to_owned(), Value::String(session_id.to_owned()));
}
}
/// Renderer access required by one parsed CDP command.
///
/// Chromium physically separates renderer main-thread and IO
/// DevTools routes. Moli keeps one protocol actor, so the parsed command
/// carries the equivalent scheduling fact explicitly instead of asking later
/// layers to reinterpret the wire method string.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CdpRendererCommandAccess {
/// The command is handled outside the renderer attachment cutover.
OwnerIndependent,
/// The command must wait for a cross-document navigation to install its
/// replacement renderer attachment.
MainThread,
/// The command may address the suspended renderer in order to inspect,
/// interrupt, or release it while navigation is in flight.
Io,
}
/// V8 execution capability of a command delivered through a renderer
/// DevTools IO receiver.
///
/// This dimension is independent from the browser-side Main/IO transport
/// route. Chromium sends every Worker command over IO, then uses this catalog
/// to decide whether the task may interrupt active JavaScript.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CdpInspectorTaskMode {
Interrupt,
DontInterrupt,
}
impl CdpInspectorTaskMode {
/// Mirrors Blink's `ShouldInterruptForMethod` catalog.
pub fn for_method(method: &str) -> Self {
match method {
"Debugger.evaluateOnCallFrame"
| "Runtime.evaluate"
| "Runtime.callFunctionOn"
| "Runtime.getProperties"
| "Runtime.runScript" => Self::DontInterrupt,
_ => Self::Interrupt,
}
}
}
/// Fate of an in-flight renderer command when navigation replaces its
/// renderer attachment.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CdpRendererCommandReplacement {
/// Dispatch the command again against the replacement attachment.
Replay,
/// Complete the command as terminated because it was bound to the old
/// JavaScript context.
Terminate,
}
/// How a replayed command must enter the replacement Runtime agent.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CdpRendererCommandReplayDispatch {
/// Send the command directly to the replacement agent.
Direct,
/// Resolve the replacement Document's default Runtime context before
/// sending the command.
ResolveRuntimeContext,
}
/// Immutable renderer scheduling policy derived once from a validated CDP
/// method at command ingress.
///
/// Downstream dispatch and renderer-call registration copy this value instead
/// of rebuilding policy from serialized Inspector JSON.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct CdpRendererCommandPolicy {
renderer_access: CdpRendererCommandAccess,
inspector_task_mode: CdpInspectorTaskMode,
renderer_replacement: CdpRendererCommandReplacement,
renderer_replay_dispatch: CdpRendererCommandReplayDispatch,
executes_page_javascript: bool,
}
impl CdpRendererCommandPolicy {
pub const fn access(self) -> CdpRendererCommandAccess {
self.renderer_access
}
pub const fn inspector_task_mode(self) -> CdpInspectorTaskMode {
self.inspector_task_mode
}
pub const fn replacement(self) -> CdpRendererCommandReplacement {
self.renderer_replacement
}
pub const fn replay_dispatch(self) -> CdpRendererCommandReplayDispatch {
self.renderer_replay_dispatch
}
pub const fn executes_page_javascript(self) -> bool {
self.executes_page_javascript
}
}
/// Parsed inbound CDP command plus its downstream JSON representation.
///
/// Domain handlers still need serialized JSON for Runtime inspector
/// passthrough, while the scheduler and dispatch layer need cheap access to
/// method/session metadata. `parse_str` preserves the supplied JSON text;
/// `parse_value` and `from_serializable` produce a normalized representation
/// after an in-process command has been rewritten or constructed.
pub struct ParsedCdpCommand {
json: String,
request: CdpRequest,
renderer_policy: CdpRendererCommandPolicy,
}
impl ParsedCdpCommand {
/// Parse a command received as JSON text.
///
/// A successful value is always a structurally valid CDP request. Parse
/// failures remain at the wire boundary and cannot travel through the
/// scheduler disguised as a parsed command.
pub fn parse_str(json: impl Into<String>) -> Result<Self, CdpCommandParseError> {
let json = json.into();
let request = serde_json::from_str(&json)
.map_err(|source| CdpCommandParseError::from_str(&json, source))?;
Ok(Self::from_request(json, request))
}
/// Parse a command that is already represented as a JSON value.
///
/// In-process callers use this for values that have not crossed the text
/// wire. Frontend routing instead consumes an existing parsed command and
/// rewrites its validated envelope without entering this parser again.
pub fn parse_value(value: Value) -> Result<Self, CdpCommandParseError> {
let command_id = value
.as_object()
.and_then(|message| message.get("id"))
.and_then(Value::as_u64);
let request: CdpRequest = serde_json::from_value(value)
.map_err(|source| CdpCommandParseError::from_value(command_id, source))?;
let json = serde_json::to_string(&request)
.map_err(|source| CdpCommandParseError::from_value(Some(request.id()), source))?;
Ok(Self::from_request(json, request))
}
/// Build a command from an in-process serializable message.
///
/// This is intentionally distinct from `parse_str`: passing a Rust string
/// here serializes it as a JSON string rather than interpreting its
/// contents as CDP JSON.
pub fn from_serializable(message: impl Serialize) -> Result<Self, CdpCommandParseError> {
let value = serde_json::to_value(message)
.map_err(|source| CdpCommandParseError::from_value(None, source))?;
Self::parse_value(value)
}
fn from_request(json: String, request: CdpRequest) -> Self {
let renderer_policy = CdpRendererCommandPolicy::for_method(request.method());
Self {
json,
request,
renderer_policy,
}
}
/// JSON sent to the downstream command dispatcher or V8 Inspector.
pub fn json(&self) -> &str {
&self.json
}
pub fn request(&self) -> &CdpRequest {
&self.request
}
/// Consume this validated command and rewrite only the frontend routing
/// fields. Unknown top-level fields remain in the flattened extension map;
/// the validated method and params remain in their typed fields.
pub fn rewrite_frontend_route(
mut self,
internal_command_id: u64,
dispatch_session_id: Option<&str>,
) -> serde_json::Result<Self> {
self.request
.rewrite_frontend_route(internal_command_id, dispatch_session_id);
self.json = serde_json::to_string(&self.request)?;
Ok(self)
}
/// Resolve a legacy Target-domain `params.targetId` route to its concrete
/// session before dispatch.
///
/// Frontend adapters use this to preserve Chromium's per-client
/// `TargetHandler::FindSession` ownership boundary even though all socket
/// clients share one downstream protocol connection.
pub fn rewrite_target_session_reference(
mut self,
session_id: &str,
) -> serde_json::Result<Self> {
self.request.rewrite_target_session_reference(session_id);
self.json = serde_json::to_string(&self.request)?;
Ok(self)
}
pub fn method(&self) -> &str {
self.request.method()
}
pub fn session_id(&self) -> Option<&str> {
self.request.session_id()
}
/// Returns the exact session whose already-produced output may be
/// captured at this command's completion boundary.
pub fn command_output_session_id(&self) -> Option<&str> {
if self.request.method().contains('.') {
self.request.session_id()
} else {
None
}
}
pub fn runtime_command_executes_page_javascript(&self) -> bool {
self.renderer_policy.executes_page_javascript()
}
pub const fn renderer_policy(&self) -> CdpRendererCommandPolicy {
self.renderer_policy
}
pub fn renderer_access(&self) -> CdpRendererCommandAccess {
self.renderer_policy.access()
}
pub fn inspector_task_mode(&self) -> CdpInspectorTaskMode {
self.renderer_policy.inspector_task_mode()
}
pub fn renderer_replacement(&self) -> CdpRendererCommandReplacement {
self.renderer_policy.replacement()
}
pub fn renderer_replay_dispatch(&self) -> CdpRendererCommandReplayDispatch {
self.renderer_policy.replay_dispatch()
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum CdpMethodDomain {
Accessibility,
Console,
Css,
Debugger,
Dom,
DomSnapshot,
Emulation,
HeapProfiler,
Page,
Performance,
Profiler,
Runtime,
Other,
}
impl CdpMethodDomain {
fn parse(domain: &str) -> Self {
match domain {
"Accessibility" => Self::Accessibility,
"Console" => Self::Console,
"CSS" => Self::Css,
"Debugger" => Self::Debugger,
"DOM" => Self::Dom,
"DOMSnapshot" => Self::DomSnapshot,
"Emulation" => Self::Emulation,
"HeapProfiler" => Self::HeapProfiler,
"Page" => Self::Page,
"Performance" => Self::Performance,
"Profiler" => Self::Profiler,
"Runtime" => Self::Runtime,
_ => Self::Other,
}
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum RuntimeWireAction {
AddBinding,
AwaitPromise,
CallFunctionOn,
Evaluate,
RunScript,
TerminateExecution,
Other,
}
impl RuntimeWireAction {
fn parse(action: &str) -> Self {
match action {
"addBinding" => Self::AddBinding,
"awaitPromise" => Self::AwaitPromise,
"callFunctionOn" => Self::CallFunctionOn,
"evaluate" => Self::Evaluate,
"runScript" => Self::RunScript,
"terminateExecution" => Self::TerminateExecution,
_ => Self::Other,
}
}
fn executes_page_javascript(self) -> bool {
matches!(
self,
Self::AwaitPromise | Self::CallFunctionOn | Self::Evaluate | Self::RunScript
)
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum PageWireAction {
MainThread,
Crash,
Other,
}
impl PageWireAction {
fn parse(action: &str) -> Self {
match action {
"captureScreenshot"
| "captureSnapshot"
| "createIsolatedWorld"
| "getFrameTree"
| "getResourceTree"
| "searchInResource"
| "getLayoutMetrics"
| "printToPDF" => Self::MainThread,
"crash" => Self::Crash,
_ => Self::Other,
}
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum DebuggerWireAction {
Interruptible,
IoExecutionControl,
MainThreadExecutionControl,
Other,
}
impl DebuggerWireAction {
fn is_interruptible(self) -> bool {
matches!(self, Self::Interruptible | Self::IoExecutionControl)
}
fn executes_page_javascript(self) -> bool {
matches!(
self,
Self::IoExecutionControl | Self::MainThreadExecutionControl
)
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum PerformanceWireAction {
GetMetrics,
Other,
}
impl PerformanceWireAction {
fn parse(action: &str) -> Self {
match action {
"getMetrics" => Self::GetMetrics,
_ => Self::Other,
}
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum EmulationWireAction {
SetScriptExecutionDisabled,
Other,
}
impl EmulationWireAction {
fn parse(action: &str) -> Self {
match action {
"setScriptExecutionDisabled" => Self::SetScriptExecutionDisabled,
_ => Self::Other,
}
}
}
impl DebuggerWireAction {
fn parse(action: &str) -> Self {
match action {
"getPossibleBreakpoints"
| "getScriptSource"
| "getStackTrace"
| "pause"
| "removeBreakpoint"
| "setBreakpoint"
| "setBreakpointByUrl"
| "setBreakpointsActive" => Self::Interruptible,
"resume" => Self::IoExecutionControl,
"continueToLocation" | "restartFrame" | "stepInto" | "stepOut" | "stepOver" => {
Self::MainThreadExecutionControl
}
_ => Self::Other,
}
}
}
impl CdpRendererCommandPolicy {
fn for_method(method: &str) -> Self {
let Some((domain, action)) = method.split_once('.') else {
return Self {
renderer_access: CdpRendererCommandAccess::OwnerIndependent,
inspector_task_mode: CdpInspectorTaskMode::for_method(method),
renderer_replacement: CdpRendererCommandReplacement::Replay,
renderer_replay_dispatch: CdpRendererCommandReplayDispatch::Direct,
executes_page_javascript: false,
};
};
let domain = CdpMethodDomain::parse(domain);
let runtime_action =
(domain == CdpMethodDomain::Runtime).then(|| RuntimeWireAction::parse(action));
let debugger_action =
(domain == CdpMethodDomain::Debugger).then(|| DebuggerWireAction::parse(action));
let renderer_access = match domain {
CdpMethodDomain::Runtime => {
if runtime_action == Some(RuntimeWireAction::TerminateExecution) {
CdpRendererCommandAccess::Io
} else {
CdpRendererCommandAccess::MainThread
}
}
CdpMethodDomain::Debugger => {
if debugger_action.is_some_and(DebuggerWireAction::is_interruptible) {
CdpRendererCommandAccess::Io
} else {
CdpRendererCommandAccess::MainThread
}
}
CdpMethodDomain::Performance => {
if PerformanceWireAction::parse(action) == PerformanceWireAction::GetMetrics {
CdpRendererCommandAccess::Io
} else {
CdpRendererCommandAccess::MainThread
}
}
CdpMethodDomain::Emulation => {
if EmulationWireAction::parse(action)
== EmulationWireAction::SetScriptExecutionDisabled
{
CdpRendererCommandAccess::Io
} else {
CdpRendererCommandAccess::OwnerIndependent
}
}
CdpMethodDomain::Page => match PageWireAction::parse(action) {
PageWireAction::MainThread => CdpRendererCommandAccess::MainThread,
PageWireAction::Crash => CdpRendererCommandAccess::Io,
PageWireAction::Other => CdpRendererCommandAccess::OwnerIndependent,
},
CdpMethodDomain::Accessibility
| CdpMethodDomain::Console
| CdpMethodDomain::Css
| CdpMethodDomain::Dom
| CdpMethodDomain::DomSnapshot
| CdpMethodDomain::HeapProfiler
| CdpMethodDomain::Profiler => CdpRendererCommandAccess::MainThread,
CdpMethodDomain::Other => CdpRendererCommandAccess::OwnerIndependent,
};
Self {
renderer_access,
inspector_task_mode: CdpInspectorTaskMode::for_method(method),
renderer_replacement: if runtime_action.is_some_and(|action| {
matches!(
action,
RuntimeWireAction::AwaitPromise
| RuntimeWireAction::CallFunctionOn
| RuntimeWireAction::Evaluate
| RuntimeWireAction::RunScript
| RuntimeWireAction::TerminateExecution
)
}) {
CdpRendererCommandReplacement::Terminate
} else {
CdpRendererCommandReplacement::Replay
},
renderer_replay_dispatch: if runtime_action == Some(RuntimeWireAction::AddBinding) {
CdpRendererCommandReplayDispatch::ResolveRuntimeContext
} else {
CdpRendererCommandReplayDispatch::Direct
},
executes_page_javascript: runtime_action
.is_some_and(RuntimeWireAction::executes_page_javascript)
|| debugger_action.is_some_and(DebuggerWireAction::executes_page_javascript),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn parse(raw: impl Into<String>) -> ParsedCdpCommand {
ParsedCdpCommand::parse_str(raw).expect("test command must be valid CDP JSON")
}
#[test]
fn parsed_cdp_command_keeps_json_and_metadata() {
let command =
parse(r#"{"id":7,"method":"Runtime.evaluate","params":{"x":1},"sessionId":"s1"}"#);
assert!(command.json().contains("Runtime.evaluate"));
assert_eq!(command.method(), "Runtime.evaluate");
assert_eq!(command.session_id(), Some("s1"));
assert_eq!(command.command_output_session_id(), Some("s1"));
assert!(command.runtime_command_executes_page_javascript());
assert_eq!(
command.renderer_access(),
CdpRendererCommandAccess::MainThread
);
}
#[test]
fn parsed_cdp_command_keeps_navigation_control_commands_unblocked() {
let command = parse(
r#"{"id":9,"method":"Fetch.continueResponse","params":{"requestId":"r"},"sessionId":"s1"}"#,
);
assert_eq!(command.method(), "Fetch.continueResponse");
assert_eq!(command.session_id(), Some("s1"));
assert_eq!(
command.renderer_access(),
CdpRendererCommandAccess::OwnerIndependent
);
}
#[test]
fn renderer_inspector_control_commands_wait_for_navigation_resume() {
for method in [
"Runtime.getIsolateId",
"Console.clearMessages",
"Profiler.enable",
"HeapProfiler.enable",
] {
let command = parse(format!(r#"{{"id":11,"method":"{method}"}}"#));
assert!(
command.renderer_access() == CdpRendererCommandAccess::MainThread,
"{method} must not bind to the suspended attachment"
);
}
}
#[test]
fn renderer_navigation_suspension_matches_chromium_io_route_exceptions() {
for method in [
"Debugger.getPossibleBreakpoints",
"Debugger.getScriptSource",
"Debugger.getStackTrace",
"Debugger.pause",
"Debugger.removeBreakpoint",
"Debugger.resume",
"Debugger.setBreakpoint",
"Debugger.setBreakpointByUrl",
"Debugger.setBreakpointsActive",
"Emulation.setScriptExecutionDisabled",
"Page.crash",
"Performance.getMetrics",
"Runtime.terminateExecution",
] {
let command = parse(format!(r#"{{"id":12,"method":"{method}"}}"#));
assert!(
command.renderer_access() == CdpRendererCommandAccess::Io,
"{method} must remain dispatchable while the renderer attachment is suspended"
);
}
for method in [
"Debugger.continueToLocation",
"Debugger.enable",
"Debugger.restartFrame",
"Debugger.stepInto",
"Debugger.stepOut",
"Debugger.stepOver",
"Performance.enable",
"Runtime.getIsolateId",
] {
let command = parse(format!(r#"{{"id":13,"method":"{method}"}}"#));
assert!(
command.renderer_access() == CdpRendererCommandAccess::MainThread,
"{method} must bind to the replacement renderer attachment"
);
}
}
#[test]
fn inspector_execution_mode_matches_chromium_worker_catalog() {
for method in [
"Debugger.evaluateOnCallFrame",
"Runtime.evaluate",
"Runtime.callFunctionOn",
"Runtime.getProperties",
"Runtime.runScript",
] {
let command = parse(format!(r#"{{"id":12,"method":"{method}"}}"#));
assert_eq!(
command.inspector_task_mode(),
CdpInspectorTaskMode::DontInterrupt,
"{method} must wait for the ordinary isolate task runner"
);
}
for method in [
"Debugger.pause",
"Debugger.resume",
"Debugger.stepInto",
"Runtime.enable",
"Runtime.terminateExecution",
"Inspector.disable",
] {
let command = parse(format!(r#"{{"id":13,"method":"{method}"}}"#));
assert_eq!(
command.inspector_task_mode(),
CdpInspectorTaskMode::Interrupt,
"{method} must be allowed to interrupt active JavaScript"
);
}
}
#[test]
fn debugger_execution_controls_admit_exact_command_output_barriers() {
for method in [
"Debugger.continueToLocation",
"Debugger.restartFrame",
"Debugger.resume",
"Debugger.stepInto",
"Debugger.stepOut",
"Debugger.stepOver",
] {
let command = parse(format!(r#"{{"id":17,"method":"{method}"}}"#));
assert!(
command.runtime_command_executes_page_javascript(),
"{method} must hold its causal resumed/paused output until its response"
);
}
assert!(
!parse(r#"{"id":18,"method":"Debugger.pause"}"#)
.runtime_command_executes_page_javascript()
);
}
#[test]
fn renderer_replacement_traits_are_computed_at_the_wire_boundary() {
for method in [
"Runtime.awaitPromise",
"Runtime.callFunctionOn",
"Runtime.evaluate",
"Runtime.runScript",
"Runtime.terminateExecution",
] {
let command = parse(format!(r#"{{"id":14,"method":"{method}"}}"#));
assert_eq!(
command.renderer_replacement(),
CdpRendererCommandReplacement::Terminate,
"{method} must remain bound to the replaced JavaScript context"
);
}
for method in [
"Runtime.enable",
"Runtime.getProperties",
"Debugger.enable",
"Console.clearMessages",
"FutureDomain.futureControlCommand",
] {
let command = parse(format!(r#"{{"id":15,"method":"{method}"}}"#));
assert_eq!(
command.renderer_replacement(),
CdpRendererCommandReplacement::Replay,
"{method} must follow the replacement renderer attachment"
);
}
let add_binding = parse(r#"{"id":16,"method":"Runtime.addBinding"}"#);
assert_eq!(
add_binding.renderer_replay_dispatch(),
CdpRendererCommandReplayDispatch::ResolveRuntimeContext
);
}
#[test]
fn page_resource_search_waits_for_document_navigation() {
let command = parse(
r#"{"id":10,"method":"Page.searchInResource","params":{"frameId":"F","url":"https://example.test/","query":"needle"},"sessionId":"s1"}"#,
);
assert_eq!(
command.renderer_access(),
CdpRendererCommandAccess::MainThread
);
}
#[test]
fn parsed_command_rejects_invalid_json_instead_of_storing_parse_failure() {
let error = ParsedCdpCommand::parse_str("{")
.err()
.expect("malformed JSON must not produce a parsed command");
assert_eq!(error.kind(), CdpCommandParseErrorKind::ParseError);
assert_eq!(error.command_id(), None);
assert!(ParsedCdpCommand::parse_value(Value::Null).is_err());
}
#[test]
fn request_known_fields_are_typed_at_deserialization() {
for raw in [
r#"{"method":"Runtime.enable"}"#,
r#"{"id":"7","method":"Runtime.enable"}"#,
r#"{"id":null,"method":"Runtime.enable"}"#,
r#"{"id":7}"#,
r#"{"id":7,"method":7}"#,
r#"{"id":7,"method":"Runtime.enable","sessionId":7}"#,
r#"{"id":7,"method":"Runtime.enable","params":7}"#,
] {
assert!(
ParsedCdpCommand::parse_str(raw).is_err(),
"invalid known CDP field must be rejected: {raw}"
);
}
let error =
ParsedCdpCommand::parse_str(r#"{"id":7,"method":"Runtime.enable","params":[]}"#)
.err()
.expect("non-object params must fail typed command construction");
assert_eq!(error.kind(), CdpCommandParseErrorKind::InvalidRequest);
assert_eq!(error.command_id(), Some(7));
assert_eq!(error.response_code(), -32600);
}
#[test]
fn explicit_null_session_id_is_an_invalid_request() {
for method in ["Runtime.enable", "Browser.close"] {
let error = ParsedCdpCommand::parse_value(serde_json::json!({
"id": 14, "method": method, "sessionId": null,
}))
.err()
.expect("a present sessionId must be a string");
assert_eq!(error.kind(), CdpCommandParseErrorKind::InvalidRequest);
assert_eq!(error.command_id(), Some(14));
assert_eq!(error.response_code(), -32600);
}
}
#[test]
fn browser_close_ignores_params_without_loosening_the_wire_envelope() {
for params in [
serde_json::json!({"ignored": true}),
serde_json::json!([]),
serde_json::json!(true),
serde_json::json!("ignored"),
Value::Null,
] {
let command = ParsedCdpCommand::parse_value(serde_json::json!({
"id": 14, "method": "Browser.close", "params": params,
"sessionId": "owned-session",
}))
.expect("Browser.close ignores params");
assert!(command.request().params().is_none());
assert_eq!(command.session_id(), Some("owned-session"));
}
}
#[test]
fn parsed_command_from_value_recomputes_typed_command_traits() {
let command = ParsedCdpCommand::parse_value(serde_json::json!({
"id": 14,
"method": "Runtime.terminateExecution",
"sessionId": "s2",
}))
.expect("rewritten frontend command must remain valid");
assert_eq!(command.request().id(), 14);
assert_eq!(command.session_id(), Some("s2"));
assert_eq!(command.renderer_access(), CdpRendererCommandAccess::Io);
assert!(!command.runtime_command_executes_page_javascript());
}
#[test]
fn frontend_rewrite_preserves_params_and_unknown_top_level_fields() {
let command = parse(
r#"{"id":14,"method":"Runtime.getIsolateId","params":{"probe":true},"sessionId":"client-session","futureExtension":{"enabled":true}}"#,
)
.rewrite_frontend_route(91, Some("dispatch-session"))
.expect("frontend route rewrite must serialize");
assert_eq!(command.request().id(), 91);
assert_eq!(command.session_id(), Some("dispatch-session"));
assert_eq!(
serde_json::from_str::<Value>(command.json()).expect("rewritten dispatch JSON"),
serde_json::json!({
"id": 91,
"method": "Runtime.getIsolateId",
"params": {"probe": true},
"sessionId": "dispatch-session",
"futureExtension": {"enabled": true},
})
);
}
#[test]
fn target_session_reference_rewrite_preserves_other_command_fields() {
let command = parse(
r#"{"id":14,"method":"Target.detachFromTarget","params":{"targetId":"TID-1"},"futureExtension":true}"#,
)
.rewrite_target_session_reference("SID-owned")
.expect("target session reference rewrite must serialize")
.rewrite_frontend_route(91, Some("SID-browser"))
.expect("frontend route rewrite must serialize");
assert_eq!(
serde_json::from_str::<Value>(command.json()).expect("rewritten dispatch JSON"),
serde_json::json!({
"id": 91,
"method": "Target.detachFromTarget",
"params": {
"targetId": "TID-1",
"sessionId": "SID-owned",
},
"sessionId": "SID-browser",
"futureExtension": true,
})
);
}
#[test]
fn absent_and_null_params_share_chromium_empty_params_semantics() {
for raw in [
r#"{"id":14,"method":"Runtime.getIsolateId"}"#,
r#"{"id":14,"method":"Runtime.getIsolateId","params":null}"#,
] {
let command = parse(raw)
.rewrite_frontend_route(91, None)
.expect("frontend route rewrite must serialize");
assert!(command.request().params().is_none());
assert_eq!(
serde_json::from_str::<Value>(command.json()).expect("rewritten dispatch JSON"),
serde_json::json!({
"id": 91,
"method": "Runtime.getIsolateId",
})
);
}
}
#[test]
fn parsed_command_from_serializable_builds_valid_dispatch_json() {
let command = ParsedCdpCommand::from_serializable(serde_json::json!({
"id": 15,
"method": "Runtime.addBinding",
"params": { "name": "exposed" },
}))
.expect("serializable test command must produce valid CDP JSON");
assert_eq!(command.request().id(), 15);
assert_eq!(command.method(), "Runtime.addBinding");
assert_eq!(
serde_json::from_str::<Value>(command.json()).expect("dispatch JSON"),
serde_json::json!({
"id": 15,
"method": "Runtime.addBinding",
"params": { "name": "exposed" },
})
);
}
}