Protocol Commands
This section documents the Chrome DevTools Protocol command implementations used by Pydoll.
Page Commands
This class encapsulates the page commands of the Chrome DevTools Protocol (CDP).
CDP's Page domain allows for interacting with browser pages, including navigation, content manipulation, and page state monitoring. These commands provide powerful capabilities for web automation, testing, and debugging.
The commands defined in this class provide functionality for: - Navigating to URLs and managing page history - Capturing screenshots and generating PDFs - Handling JavaScript dialogs - Enabling and controlling page events - Managing download behavior - Manipulating page content and state
staticmethod
add_script_to_evaluate_on_new_document(source, world_name=None, include_command_line_api=None, run_immediately=None)
Creates a command to add a script that will be evaluated when a new document is created.
| PARAMETER | DESCRIPTION |
|---|---|
source
|
Script source to be evaluated when a new document is created.
TYPE:
|
world_name
|
If specified, creates an isolated world with the given name.
TYPE:
|
include_command_line_api
|
Whether to include command line API.
TYPE:
|
run_immediately
|
Whether to run the script immediately on existing contexts.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[AddScriptToEvaluateOnNewDocumentResponse]
|
Command[AddScriptToEvaluateOnNewDocumentResponse]: Command object with the identifier of the added script. |
staticmethod
capture_screenshot(format=None, quality=None, clip=None, from_surface=None, capture_beyond_viewport=None, optimize_for_speed=None)
Creates a command to capture a screenshot of the current page.
| PARAMETER | DESCRIPTION |
|---|---|
format
|
Image compression format (jpeg, png, or webp).
TYPE:
|
quality
|
Compression quality from 0-100 (jpeg only).
TYPE:
|
clip
|
Region of the page to capture.
TYPE:
|
from_surface
|
Capture from the surface, not the view.
TYPE:
|
capture_beyond_viewport
|
Capture beyond the viewport.
TYPE:
|
optimize_for_speed
|
Optimize for speed, not for size.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[CaptureScreenshotResponse]
|
Command[CaptureScreenshotResponse]: Command object with base64-encoded image data. |
staticmethod
Creates a command to close the current page.
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to close the page. |
staticmethod
Creates a command to create an isolated world for the given frame.
| PARAMETER | DESCRIPTION |
|---|---|
frame_id
|
ID of the frame in which to create the isolated world.
TYPE:
|
world_name
|
Name to be reported in the Execution Context.
TYPE:
|
grant_universal_access
|
Whether to grant universal access.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[CreateIsolatedWorldResponse]
|
Command[CreateIsolatedWorldResponse]: Command object with the execution context ID. |
staticmethod
Creates a command to disable page domain notifications.
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to disable the Page domain. |
staticmethod
Creates a command to enable page domain notifications.
| PARAMETER | DESCRIPTION |
|---|---|
enable_file_chooser_opened_event
|
Whether to emit Page.fileChooserOpened event.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to enable the Page domain. |
staticmethod
Creates a command to get the manifest for the current document.
| RETURNS | DESCRIPTION |
|---|---|
Command[GetAppManifestResponse]
|
Command[GetAppManifestResponse]: Command object with manifest information. |
staticmethod
Creates a command to get the frame tree for the current page.
| RETURNS | DESCRIPTION |
|---|---|
Command[GetFrameTreeResponse]
|
Command[GetFrameTreeResponse]: Command object with frame tree information. |
staticmethod
Creates a command to get layout metrics for the page.
| RETURNS | DESCRIPTION |
|---|---|
Command[GetLayoutMetricsResponse]
|
Command[GetLayoutMetricsResponse]: Command object with layout metrics. |
staticmethod
Creates a command to get the navigation history for the current page.
| RETURNS | DESCRIPTION |
|---|---|
Command[GetNavigationHistoryResponse]
|
Command[GetNavigationHistoryResponse]: Command object with navigation history. |
staticmethod
Creates a command to handle a JavaScript dialog.
| PARAMETER | DESCRIPTION |
|---|---|
accept
|
Whether to accept or dismiss the dialog.
TYPE:
|
prompt_text
|
Text to enter in prompt dialogs.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to handle a JavaScript dialog. |
staticmethod
Creates a command to navigate to a specific URL.
| PARAMETER | DESCRIPTION |
|---|---|
url
|
URL to navigate to.
TYPE:
|
referrer
|
Referrer URL.
TYPE:
|
transition_type
|
Intended transition type.
TYPE:
|
frame_id
|
Frame ID to navigate.
TYPE:
|
referrer_policy
|
Referrer policy.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[NavigateResponse]
|
Command[NavigateResponse]: Command object to navigate to a URL. |
staticmethod
Creates a command to navigate to a specific history entry.
| PARAMETER | DESCRIPTION |
|---|---|
entry_id
|
ID of the history entry to navigate to.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to navigate to a history entry. |
staticmethod
print_to_pdf(landscape=None, display_header_footer=None, print_background=None, scale=None, paper_width=None, paper_height=None, margin_top=None, margin_bottom=None, margin_left=None, margin_right=None, page_ranges=None, header_template=None, footer_template=None, prefer_css_page_size=None, transfer_mode=None, generate_tagged_pdf=None, generate_document_outline=None)
Creates a command to print the current page to PDF.
| PARAMETER | DESCRIPTION |
|---|---|
landscape
|
Paper orientation.
TYPE:
|
display_header_footer
|
Display header and footer.
TYPE:
|
print_background
|
Print background graphics.
TYPE:
|
scale
|
Scale of the webpage rendering.
TYPE:
|
paper_width
|
Paper width in inches.
TYPE:
|
paper_height
|
Paper height in inches.
TYPE:
|
margin_top
|
Top margin in inches.
TYPE:
|
margin_bottom
|
Bottom margin in inches.
TYPE:
|
margin_left
|
Left margin in inches.
TYPE:
|
margin_right
|
Right margin in inches.
TYPE:
|
page_ranges
|
Paper ranges to print, e.g., '1-5, 8, 11-13'.
TYPE:
|
header_template
|
HTML template for the print header.
TYPE:
|
footer_template
|
HTML template for the print footer.
TYPE:
|
prefer_css_page_size
|
Whether to prefer page size as defined by CSS.
TYPE:
|
transfer_mode
|
Transfer mode.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[PrintToPDFResponse]
|
Command[PrintToPDFResponse]: Command object to print the page to PDF. |
staticmethod
Creates a command to reload the current page.
| PARAMETER | DESCRIPTION |
|---|---|
ignore_cache
|
If true, browser cache is ignored.
TYPE:
|
script_to_evaluate_on_load
|
Script to be injected into the page on load.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to reload the page. |
staticmethod
Creates a command to reset the navigation history.
staticmethod
Creates a command to remove a script that was added to be evaluated on new documents.
| PARAMETER | DESCRIPTION |
|---|---|
identifier
|
Identifier of the script to remove.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to remove a script. |
staticmethod
Creates a command to toggle bypassing page CSP.
| PARAMETER | DESCRIPTION |
|---|---|
enabled
|
Whether to bypass page CSP.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to toggle bypassing page CSP. |
staticmethod
Creates a command to set the document content of a frame.
| PARAMETER | DESCRIPTION |
|---|---|
frame_id
|
Frame ID to set the document content for.
TYPE:
|
html
|
HTML content to set.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to set the document content. |
staticmethod
Creates a command to set whether to intercept file chooser dialogs.
| PARAMETER | DESCRIPTION |
|---|---|
enabled
|
Whether to intercept file chooser dialogs.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to set file chooser dialog interception. |
staticmethod
Creates a command to enable/disable lifecycle events.
| PARAMETER | DESCRIPTION |
|---|---|
enabled
|
Whether to enable lifecycle events.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to enable/disable lifecycle events. |
staticmethod
Creates a command to stop loading the page.
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to stop loading the page. |
staticmethod
Creates a command to add a compilation cache entry.
Experimental: This method is experimental and may be subject to change.
| PARAMETER | DESCRIPTION |
|---|---|
url
|
URL for which to add the compilation cache entry.
TYPE:
|
data
|
Base64-encoded data.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to add a compilation cache entry. |
staticmethod
Creates a command to capture a snapshot of the page.
Experimental: This method is experimental and may be subject to change.
| PARAMETER | DESCRIPTION |
|---|---|
format
|
Format of the snapshot (only 'mhtml' is supported).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[CaptureSnapshotResponse]
|
Command[CaptureSnapshotResponse]: Command object to capture a snapshot. |
staticmethod
Creates a command to clear the compilation cache.
staticmethod
Creates a command to generate a test report.
Experimental: This method is experimental and may be subject to change.
| PARAMETER | DESCRIPTION |
|---|---|
message
|
Message to be displayed in the report.
TYPE:
|
group
|
Group label for the report.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to generate a test report. |
staticmethod
Creates a command to get the ad script ancestry IDs for a given frame.
Experimental: This method is experimental and may be subject to change.
| PARAMETER | DESCRIPTION |
|---|---|
frame_id
|
ID of the frame to get ad script ancestry IDs for.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[GetAdScriptAncestryIdsResponse]
|
Command[GetAdScriptAncestryIdsResponse]: Command object to get ad script ancestry IDs. |
staticmethod
Creates a command to get the app ID.
Experimental: This method is experimental and may be subject to change.
| PARAMETER | DESCRIPTION |
|---|---|
app_id
|
App ID for verification.
TYPE:
|
recommended_id
|
Recommended app ID.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[GetAppIdResponse]
|
Command[GetAppIdResponse]: Command object to get the app ID. |
staticmethod
Creates a command to get the installability errors.
staticmethod
Creates a command to get origin trials for a given origin.
Experimental: This method is experimental and may be subject to change.
| PARAMETER | DESCRIPTION |
|---|---|
frame_id
|
Frame ID to get trials for.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[GetOriginTrialsResponse]
|
Command[GetOriginTrialsResponse]: Command object to get origin trials. |
staticmethod
Creates a command to get the permissions policy state.
staticmethod
Creates a command to get the resource content.
staticmethod
Creates a command to produce a compilation cache entry.
staticmethod
Creates a command to acknowledge a screencast frame.
staticmethod
Creates a command to search for a string in a resource.
staticmethod
Creates a command to set ad blocking enabled.
staticmethod
Creates a command to set font families.
staticmethod
Creates a command to set prerendering allowed.
staticmethod
Creates a command to set the RPH registration mode.
staticmethod
Creates a command to set the SPC transaction mode.
staticmethod
Creates a command to set the web lifecycle state.
staticmethod
Creates a command to start a screencast.
Runtime Commands
A class for interacting with the JavaScript runtime using Chrome DevTools Protocol.
This class provides methods to create commands for evaluating JavaScript expressions, calling functions on JavaScript objects, and retrieving object properties through CDP.
| ATTRIBUTE | DESCRIPTION |
|---|---|
EVALUATE_TEMPLATE |
Template for the Runtime.evaluate command.
TYPE:
|
CALL_FUNCTION_ON_TEMPLATE |
Template for the Runtime.callFunctionOn command.
TYPE:
|
GET_PROPERTIES |
Template for the Runtime.getProperties command.
TYPE:
|
staticmethod
Creates a command to add a JavaScript binding.
| PARAMETER | DESCRIPTION |
|---|---|
name
|
Name of the binding to add.
TYPE:
|
execution_context_name
|
Name of the execution context to bind to.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to add a JavaScript binding. |
staticmethod
Creates a command to await a JavaScript promise and return its result.
| PARAMETER | DESCRIPTION |
|---|---|
promise_object_id
|
ID of the promise to await.
TYPE:
|
return_by_value
|
Whether to return the result by value instead of reference.
TYPE:
|
generate_preview
|
Whether to generate a preview for the result.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[AwaitPromiseResponse]
|
Command[AwaitPromiseResponse]: Command object to await a promise. |
staticmethod
call_function_on(function_declaration, object_id=None, arguments=None, silent=None, return_by_value=None, generate_preview=None, user_gesture=None, await_promise=None, execution_context_id=None, object_group=None, throw_on_side_effect=None, unique_context_id=None, serialization_options=None)
Creates a command to call a function with a given declaration on a specific object.
| PARAMETER | DESCRIPTION |
|---|---|
function_declaration
|
Declaration of the function to call.
TYPE:
|
object_id
|
ID of the object to call the function on.
TYPE:
|
arguments
|
Arguments to pass to the function.
TYPE:
|
silent
|
Whether to silence exceptions.
TYPE:
|
return_by_value
|
Whether to return the result by value instead of reference.
TYPE:
|
generate_preview
|
Whether to generate a preview for the result.
TYPE:
|
user_gesture
|
Whether to treat the call as initiated by user gesture.
TYPE:
|
await_promise
|
Whether to await promise result.
TYPE:
|
execution_context_id
|
ID of the execution context to call the function in.
TYPE:
|
object_group
|
Symbolic group name for the result.
TYPE:
|
throw_on_side_effect
|
Whether to throw if side effect cannot be ruled out.
TYPE:
|
unique_context_id
|
Unique context ID for the function call.
TYPE:
|
serialization_options
|
Serialization options for the result.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[CallFunctionOnResponse]
|
Command[CallFunctionOnResponse]: Command object to call a function on an object. |
staticmethod
Creates a command to compile a JavaScript expression.
| PARAMETER | DESCRIPTION |
|---|---|
expression
|
JavaScript expression to compile.
TYPE:
|
source_url
|
URL of the source file for the script.
TYPE:
|
persist_script
|
Whether to persist the compiled script.
TYPE:
|
execution_context_id
|
ID of the execution context to compile the script in.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[CompileScriptResponse]
|
Command[CompileScriptResponse]: Command object to compile a script. |
staticmethod
Disables the runtime domain.
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to disable the runtime domain. |
staticmethod
Enables the runtime domain.
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to enable the runtime domain. |
staticmethod
evaluate(expression, object_group=None, include_command_line_api=None, silent=None, context_id=None, return_by_value=None, generate_preview=None, user_gesture=None, await_promise=None, throw_on_side_effect=None, timeout=None, disable_breaks=None, repl_mode=None, allow_unsafe_eval_blocked_by_csp=None, unique_context_id=None, serialization_options=None)
Creates a command to evaluate a JavaScript expression in the global context.
| PARAMETER | DESCRIPTION |
|---|---|
expression
|
JavaScript expression to evaluate.
TYPE:
|
object_group
|
Symbolic group name for the result.
TYPE:
|
include_command_line_api
|
Whether to include command line API.
TYPE:
|
silent
|
Whether to silence exceptions.
TYPE:
|
context_id
|
ID of the execution context to evaluate in.
TYPE:
|
return_by_value
|
Whether to return the result by value instead of reference.
TYPE:
|
generate_preview
|
Whether to generate a preview for the result.
TYPE:
|
user_gesture
|
Whether to treat evaluation as initiated by user gesture.
TYPE:
|
await_promise
|
Whether to await promise result.
TYPE:
|
throw_on_side_effect
|
Whether to throw if side effect cannot be ruled out.
TYPE:
|
timeout
|
Timeout in milliseconds.
TYPE:
|
disable_breaks
|
Whether to disable breakpoints during evaluation.
TYPE:
|
repl_mode
|
Whether to execute in REPL mode.
TYPE:
|
allow_unsafe_eval_blocked_by_csp
|
Allow unsafe evaluation.
TYPE:
|
unique_context_id
|
Unique context ID for evaluation.
TYPE:
|
serialization_options
|
Serialization for the result.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[EvaluateResponse]
|
Command[EvaluateResponse]: Command object to evaluate JavaScript. |
staticmethod
get_properties(object_id, own_properties=None, accessor_properties_only=None, generate_preview=None, non_indexed_properties_only=None)
Creates a command to get properties of a JavaScript object.
| PARAMETER | DESCRIPTION |
|---|---|
object_id
|
ID of the object to get properties for.
TYPE:
|
own_properties
|
Whether to return only own properties.
TYPE:
|
accessor_properties_only
|
Whether to return only accessor properties.
TYPE:
|
generate_preview
|
Whether to generate previews for property values.
TYPE:
|
non_indexed_properties_only
|
Whether to return only non-indexed properties.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[GetPropertiesResponse]
|
Command[GetPropertiesResponse]: Command object to get object properties. |
staticmethod
Creates a command to retrieve names of variables from global lexical scope.
| PARAMETER | DESCRIPTION |
|---|---|
execution_context_id
|
ID of the execution context to get scope names from.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[GlobalLexicalScopeNamesResponse]
|
Command[GlobalLexicalScopeNamesResponse]: Command object to get global lexical scope names. |
staticmethod
Creates a command to query objects with a given prototype.
| PARAMETER | DESCRIPTION |
|---|---|
prototype_object_id
|
ID of the prototype object.
TYPE:
|
object_group
|
Symbolic group name for the results.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[QueryObjectsResponse]
|
Command[QueryObjectsResponse]: Command object to query objects. |
staticmethod
Creates a command to release a JavaScript object.
| PARAMETER | DESCRIPTION |
|---|---|
object_id
|
ID of the object to release.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to release an object. |
staticmethod
Creates a command to release all objects in a group.
| PARAMETER | DESCRIPTION |
|---|---|
object_group
|
Name of the object group to release.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to release an object group. |
staticmethod
Creates a command to remove a JavaScript binding.
| PARAMETER | DESCRIPTION |
|---|---|
name
|
Name of the binding to remove.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to remove a JavaScript binding. |
staticmethod
run_script(script_id, execution_context_id=None, object_group=None, silent=None, include_command_line_api=None, return_by_value=None, generate_preview=None, await_promise=None)
Creates a command to run a compiled script.
| PARAMETER | DESCRIPTION |
|---|---|
script_id
|
ID of the compiled script to run.
TYPE:
|
execution_context_id
|
ID of the execution context to run the script in.
TYPE:
|
object_group
|
Symbolic group name for the result.
TYPE:
|
silent
|
Whether to silence exceptions.
TYPE:
|
include_command_line_api
|
Whether to include command line API.
TYPE:
|
return_by_value
|
Whether to return the result by value instead of reference.
TYPE:
|
generate_preview
|
Whether to generate a preview for the result.
TYPE:
|
await_promise
|
Whether to await promise result.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[RunScriptResponse]
|
Command[RunScriptResponse]: Command object to run a script. |
staticmethod
Creates a command to set the async call stack depth.
| PARAMETER | DESCRIPTION |
|---|---|
max_depth
|
Maximum depth of async call stacks.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to set async call stack depth. |
staticmethod
Creates a command to enable or disable custom object formatters.
| PARAMETER | DESCRIPTION |
|---|---|
enabled
|
Whether to enable custom object formatters.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to enable/disable custom object formatters. |
staticmethod
Creates a command to set the maximum call stack size to capture.
| PARAMETER | DESCRIPTION |
|---|---|
size
|
Maximum call stack size to capture.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: Command object to set max call stack size. |
DOM Commands
Implementation of Chrome DevTools Protocol for the DOM domain.
This class provides commands for interacting with the Document Object Model (DOM) in the browser, enabling access and manipulation of the element structure in a web page. The DOM domain in Chrome DevTools Protocol exposes operations for reading and writing to the DOM, which is fundamental for browser automation, testing, and debugging.
Each DOM element is represented by a mirror object with a unique ID. This ID can be used to gather additional information about the node, resolve it into JavaScript object wrappers, manipulate attributes, and perform various other operations on the DOM structure.
staticmethod
Describes a DOM node identified by its ID without requiring domain to be enabled.
The describe_node command is particularly useful in scenarios where you need to quickly gather information about a specific element without subscribing to DOM change events, making it more lightweight for isolated element inspection operations.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Identifier of the node known to the client.
TYPE:
|
backend_node_id
|
Identifier of the backend node used internally by the browser.
TYPE:
|
object_id
|
JavaScript object id of the node wrapper.
TYPE:
|
depth
|
Maximum depth at which children should be retrieved (default is 1). Use -1 for the entire subtree or provide an integer greater than 0.
TYPE:
|
pierce
|
Whether iframes and shadow roots should be traversed when returning the subtree (default is false).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns detailed information about the requested node.
TYPE:
|
staticmethod
Disables DOM agent for the current page.
Disabling the DOM domain stops the CDP from sending DOM-related events and prevents further DOM manipulation operations until the domain is enabled again. This can be important for optimizing performance when you're done with DOM operations and want to minimize background processing.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to disable the DOM domain.
TYPE:
|
staticmethod
Enables DOM agent for the current page.
Enabling the DOM domain is a prerequisite for receiving DOM events and using most DOM manipulation methods. The DOM events include changes to the DOM tree structure, attribute modifications, and many others. Without enabling this domain first, many DOM operations would fail or provide incomplete information.
| PARAMETER | DESCRIPTION |
|---|---|
include_whitespace
|
Whether to include whitespace-only text nodes in the children array of returned Nodes. Allowed values: "none", "all".
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to enable the DOM domain.
TYPE:
|
staticmethod
Focuses the given element.
The focus command is crucial for simulating realistic user interactions, as many events (like keyboard input) require that an element has focus first. It's also important for testing proper tab order and keyboard accessibility of web pages.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Identifier of the node to focus.
TYPE:
|
backend_node_id
|
Identifier of the backend node to focus.
TYPE:
|
object_id
|
JavaScript object id of the node wrapper.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to focus on the specified element.
TYPE:
|
staticmethod
Returns attributes for the specified node.
Attribute information is essential in web testing and automation because attributes often contain crucial information about element state, behavior, and metadata. This command provides an efficient way to access all attributes of an element without parsing HTML or using JavaScript evaluation.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to retrieve attributes for.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns an interleaved array of node attribute names and values [name1, value1, name2, value2, ...].
TYPE:
|
staticmethod
Returns box model information for the specified node.
The box model is a fundamental concept in CSS that describes how elements are rendered with content, padding, borders, and margins. This command provides detailed information about these dimensions and coordinates, which is invaluable for spatial analysis and precision interactions with elements on the page.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Identifier of the node.
TYPE:
|
backend_node_id
|
Identifier of the backend node.
TYPE:
|
object_id
|
JavaScript object id of the node wrapper.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the box model for the node, including coordinates for content, padding, border, and margin boxes.
TYPE:
|
staticmethod
Returns the root DOM node (and optionally the subtree) to the caller.
This is typically the first command called when interacting with the DOM, as it provides access to the document's root node. From this root, you can traverse to any other element on the page. This command implicitly enables DOM domain events for the current target, making it a good starting point for DOM interaction.
| PARAMETER | DESCRIPTION |
|---|---|
depth
|
Maximum depth at which children should be retrieved (default is 1). Use -1 for the entire subtree or provide an integer greater than 0.
TYPE:
|
pierce
|
Whether iframes and shadow roots should be traversed when returning the subtree (default is false).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the root DOM node.
TYPE:
|
staticmethod
Returns node id at given location on the page.
This command is particularly useful for bridging the gap between visual/pixel-based information and the DOM structure. It allows you to convert screen coordinates to actual DOM elements, which is essential for creating inspection tools or for testing spatially-oriented interactions.
| PARAMETER | DESCRIPTION |
|---|---|
x
|
X coordinate relative to the main frame's viewport.
TYPE:
|
y
|
Y coordinate relative to the main frame's viewport.
TYPE:
|
include_user_agent_shadow_dom
|
Whether to include nodes in user agent shadow roots.
TYPE:
|
ignore_pointer_events_none
|
Whether to ignore pointer-events:none and test elements underneath them.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the node at the given location, including frame information when available.
TYPE:
|
staticmethod
Returns node's HTML markup, including the node itself and all its children.
This command provides a way to access the complete HTML representation of an element, making it valuable for when you need to extract, analyze, or verify HTML content. It's more comprehensive than just getting text content as it preserves the full markup structure including tags, attributes, and child elements.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Identifier of the node.
TYPE:
|
backend_node_id
|
Identifier of the backend node.
TYPE:
|
object_id
|
JavaScript object id of the node wrapper.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the outer HTML markup of the node.
TYPE:
|
staticmethod
Hides any DOM element highlight.
This command is particularly useful in automation workflows where multiple elements are highlighted in sequence, and you need to clear previous highlights before proceeding to the next element to avoid visual clutter or interference.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to hide DOM element highlights.
TYPE:
|
staticmethod
Highlights DOM node.
Highlighting nodes is especially valuable during development and debugging sessions to visually confirm which elements are being selected by selectors or coordinates.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to highlight a DOM node.
TYPE:
|
staticmethod
Highlights given rectangle.
Unlike node highlighting, rectangle highlighting allows highlighting arbitrary regions of the page, which is useful for highlighting computed areas or regions that don't correspond directly to DOM elements.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to highlight a rectangular area.
TYPE:
|
staticmethod
Moves node into the new container, placing it before the given anchor.
This command allows for more complex DOM restructuring than simple attribute or content changes. It's particularly useful when testing applications that involve rearranging elements, such as sortable lists, kanban boards, or drag-and-drop interfaces.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to move.
TYPE:
|
target_node_id
|
Id of the element to drop the moved node into.
TYPE:
|
insert_before_node_id
|
Drop node before this one (if absent, the moved node becomes the last child of target_node_id).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to move a node, returning the new id of the moved node.
TYPE:
|
staticmethod
Executes querySelector on a given node.
This method is one of the most fundamental tools for element location, allowing the use of standard CSS selectors to find elements in the DOM. Unlike JavaScript's querySelector, this can be executed on any node (not just document), enabling scoped searches within specific sections of the page.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to query upon.
TYPE:
|
selector
|
CSS selector string.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the first element matching the selector.
TYPE:
|
staticmethod
Executes querySelectorAll on a given node.
This method extends querySelector by returning all matching elements rather than just the first one. This is essential for operations that need to process multiple elements, such as extracting data from tables, lists, or grids, or verifying that the correct number of elements are present.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to query upon.
TYPE:
|
selector
|
CSS selector string.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns all elements matching the selector.
TYPE:
|
staticmethod
Removes attribute with given name from an element with given id.
This command allows direct manipulation of element attributes without using JavaScript in the page context. It's useful for testing how elements behave when specific attributes are removed or for preparing elements for specific test conditions.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the element to remove attribute from.
TYPE:
|
name
|
Name of the attribute to remove.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to remove the specified attribute.
TYPE:
|
staticmethod
Removes node with given id.
This command allows direct removal of DOM elements, which can be useful when testing how an application responds to missing elements or when simplifying a page for focused testing scenarios.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to remove.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to remove the specified node.
TYPE:
|
staticmethod
Requests that children of the node with given id are returned to the caller.
This method is particularly useful when dealing with large DOM trees, as it allows for more efficient exploration by loading children on demand rather than loading the entire tree at once. Child nodes are returned as setChildNodes events.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to get children for.
TYPE:
|
depth
|
The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the entire subtree.
TYPE:
|
pierce
|
Whether or not iframes and shadow roots should be traversed.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to request child nodes.
TYPE:
|
staticmethod
Requests that the node is sent to the caller given the JavaScript node object reference.
This method bridges the gap between JavaScript objects in the page context and the CDP's node representation system, allowing automation to work with elements that might only be available as JavaScript references (e.g., from event handlers).
| PARAMETER | DESCRIPTION |
|---|---|
object_id
|
JavaScript object id to convert into a Node.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the Node id for the given object.
TYPE:
|
staticmethod
Resolves the JavaScript node object for a given NodeId or BackendNodeId.
This method provides the opposite functionality of requestNode - instead of getting a CDP node from a JavaScript object, it gets a JavaScript object from a CDP node. This enables executing JavaScript operations on nodes identified through CDP.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to resolve.
TYPE:
|
backend_node_id
|
Backend id of the node to resolve.
TYPE:
|
object_group
|
Symbolic group name that can be used to release multiple objects.
TYPE:
|
execution_context_id
|
Execution context in which to resolve the node.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns a JavaScript object wrapper for the node.
TYPE:
|
staticmethod
Scrolls the specified node into view if not already visible.
This command is crucial for reliable web automation, as it ensures elements are actually visible in the viewport before attempting interactions. Modern websites often use lazy loading and have long scrollable areas, making this command essential for working with elements that may not be initially visible.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Identifier of the node.
TYPE:
|
backend_node_id
|
Identifier of the backend node.
TYPE:
|
object_id
|
JavaScript object id of the node wrapper.
TYPE:
|
rect
|
Optional rect to scroll into view, relative to the node bounds.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to scroll the element into view.
TYPE:
|
staticmethod
Sets attribute for an element with given id, using text representation.
This command allows for more complex attribute manipulation than set_attribute_value, as it accepts a text representation that can potentially define multiple attributes or include special formatting. It's particularly useful when trying to replicate exactly how attributes would be defined in HTML source code.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the element to set attribute for.
TYPE:
|
text
|
Text with a new attribute value.
TYPE:
|
name
|
Attribute name to replace with new text value.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to set an attribute as text.
TYPE:
|
staticmethod
Sets attribute for element with given id.
This command provides direct control over element attributes without using JavaScript, which is essential for testing how applications respond to attribute changes or for setting up specific test conditions by controlling element attributes directly.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the element to set attribute for.
TYPE:
|
name
|
Attribute name.
TYPE:
|
value
|
Attribute value.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to set an attribute value.
TYPE:
|
staticmethod
Sets files for the given file input element.
This command solves one of the most challenging automation problems: working with file inputs. It bypasses the OS-level file dialog that normally appears when clicking a file input, allowing automated tests to provide files programmatically.
| PARAMETER | DESCRIPTION |
|---|---|
files
|
list of file paths to set.
TYPE:
|
node_id
|
Identifier of the node.
TYPE:
|
backend_node_id
|
Identifier of the backend node.
TYPE:
|
object_id
|
JavaScript object id of the node wrapper.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to set files for a file input element.
TYPE:
|
staticmethod
Sets node name for a node with given id.
This command allows changing the actual tag name of an element, which can be useful for testing how applications handle different types of elements or for testing the impact of semantic HTML choices on accessibility and behavior.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to set name for.
TYPE:
|
name
|
New node name.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the new node id after the name change.
TYPE:
|
staticmethod
Sets node value for a node with given id.
This command is particularly useful for updating the content of text nodes and comments, allowing direct manipulation of text content without changing the surrounding HTML structure.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to set value for.
TYPE:
|
value
|
New node value.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to set a node's value.
TYPE:
|
staticmethod
Sets node HTML markup, replacing existing one.
This is one of the most powerful DOM manipulation commands, as it allows completely replacing an element and all its children with new HTML. This is useful for making major structural changes to the page or for testing how applications handle dynamically inserted content.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to set outer HTML for.
TYPE:
|
outer_html
|
HTML markup to set.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to set the outer HTML of a node.
TYPE:
|
staticmethod
Collects class names for the node with given id and all of its children.
This method is valuable for understanding the styling landscape of a page, especially in complex applications where multiple CSS frameworks might be in use or where classes are dynamically applied.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to collect class names for.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns a list of all unique class names in the subtree.
TYPE:
|
staticmethod
Creates a deep copy of the specified node and places it into the target container.
Unlike move_to, this command creates a copy of the node, leaving the original intact. This is useful when you want to duplicate content rather than move it, such as when testing how multiple instances of the same component behave.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to copy.
TYPE:
|
target_node_id
|
Id of the element to drop the copy into.
TYPE:
|
insert_before_node_id
|
Drop the copy before this node (if absent, the copy becomes the last child of target_node_id).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the id of the new copy.
TYPE:
|
staticmethod
Discards search results from the session with the given id.
This method helps manage resources when performing multiple searches during a session, allowing explicit cleanup of search results that are no longer needed.
| PARAMETER | DESCRIPTION |
|---|---|
search_id
|
Unique search session identifier.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to discard search results.
TYPE:
|
staticmethod
Finds the closest ancestor node that is an anchor element for the given node.
This method is useful when working with content inside links or when you need to find the enclosing link element for text or other elements. This helps in cases where you might locate text but need to find the actual link around it.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to search for an anchor around.
TYPE:
|
anchor_specifier
|
Optional specifier for anchor tag properties.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the anchor element node information.
TYPE:
|
staticmethod
get_container_for_node(node_id, container_name=None, physical_axes=None, logical_axes=None, queries_scroll_state=None)
Finds a containing element for the given node based on specified parameters.
This method helps in understanding the structural and layout context of elements, particularly in complex layouts using CSS features like flexbox, grid, or when dealing with scrollable containers.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to find the container for.
TYPE:
|
container_name
|
Name of the container to look for (e.g., 'scrollable', 'flex').
TYPE:
|
physical_axes
|
Physical axes to consider (Horizontal, Vertical, Both).
TYPE:
|
logical_axes
|
Logical axes to consider (Inline, Block, Both).
TYPE:
|
queries_scroll_state
|
Whether to query scroll state or not.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns information about the containing element.
TYPE:
|
staticmethod
Returns quads that describe node position on the page.
This method provides detailed geometric information about an element's position on the page, accounting for any transformations, rotations, or other CSS effects. This is more precise than getBoxModel for complex layouts.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Identifier of the node.
TYPE:
|
backend_node_id
|
Identifier of the backend node.
TYPE:
|
object_id
|
JavaScript object id of the node wrapper.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the quads describing the node position.
TYPE:
|
staticmethod
Returns information about detached DOM tree elements.
This method is primarily useful for debugging memory issues related to the DOM, as detached DOM nodes (nodes no longer in the document but still referenced in JavaScript) are a common cause of memory leaks in web applications.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns information about detached DOM nodes.
TYPE:
|
staticmethod
Retrieves an element related to the given one in a specified way.
This method provides a way to find elements based on their relationships to other elements, such as finding the next focusable element after a given one. This is useful for simulating keyboard navigation or for analyzing element relationships.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the reference node.
TYPE:
|
relation
|
Type of relationship (e.g., nextSibling, previousSibling, firstChild).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the related element node.
TYPE:
|
staticmethod
Returns file information for the given File object.
This method is useful when working with file inputs and the File API, providing access to file metadata like name, size, and MIME type for files selected in file input elements or created programmatically.
| PARAMETER | DESCRIPTION |
|---|---|
object_id
|
JavaScript object id of the File object to get info for.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns file information.
TYPE:
|
staticmethod
Returns iframe element that owns the given frame.
This method is essential when working with pages that contain iframes, as it allows mapping between frame IDs (used in CDP) and the actual iframe elements in the parent document.
| PARAMETER | DESCRIPTION |
|---|---|
frame_id
|
Id of the frame to get the owner element for.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the frame owner element.
TYPE:
|
staticmethod
Finds nodes with a given computed style in a subtree.
This method allows finding elements based on their computed styles rather than just structure or attributes. This is powerful for testing visual aspects of a page or for finding elements that match specific visual criteria.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Node to start the search from.
TYPE:
|
computed_styles
|
list of computed style properties to match against.
TYPE:
|
pierce
|
Whether or not iframes and shadow roots should be traversed.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns nodes matching the specified styles.
TYPE:
|
staticmethod
Gets stack traces associated with a specific node.
This method is powerful for debugging, as it reveals the JavaScript execution paths that led to the creation of specific DOM elements, helping developers understand the relationship between their code and the resulting DOM structure.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to get stack traces for.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns stack traces related to the node.
TYPE:
|
staticmethod
Returns the querying descendants for container.
This method is particularly useful for working with CSS Container Queries, helping to identify which descendant elements are affected by or querying a particular container element.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the container node to find querying descendants for.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns querying descendant information.
TYPE:
|
staticmethod
Returns the root of the relayout boundary for the given node.
This method helps in understanding layout performance by identifying the boundary of layout recalculations when a particular element changes. This is valuable for optimizing rendering performance.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
Id of the node to find relayout boundary for.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the relayout boundary node.
TYPE:
|
staticmethod
Returns search results from given fromIndex to given toIndex from a search.
This method is used in conjunction with performSearch to retrieve search results in batches, which is essential when dealing with large result sets that might be inefficient to transfer all at once.
| PARAMETER | DESCRIPTION |
|---|---|
search_id
|
Unique search session identifier from performSearch.
TYPE:
|
from_index
|
Start index to retrieve results from.
TYPE:
|
to_index
|
End index to retrieve results to (exclusive).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the requested search results.
TYPE:
|
staticmethod
Returns all top layer elements in the document.
This method is valuable for working with modern web UIs that make extensive use of overlays, modals, dropdowns, and other elements that need to appear above the normal document flow.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the top layer element information.
TYPE:
|
staticmethod
Marks last undoable state.
This method helps in managing DOM manipulation state, allowing the creation of savepoints that can be reverted to with the undo command. This is useful for complex sequences of DOM operations that should be treated as a unit.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to mark the current state as undoable.
TYPE:
|
staticmethod
Searches for a given string in the DOM tree.
This method initiates a search across the DOM tree, supporting plain text, CSS selectors, or XPath expressions. It's a powerful way to find elements or content across the entire document without knowing the exact structure.
| PARAMETER | DESCRIPTION |
|---|---|
query
|
Plain text or query selector or XPath search query.
TYPE:
|
include_user_agent_shadow_dom
|
True to include user agent shadow DOM in the search.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns search results identifier and count.
TYPE:
|
staticmethod
Requests that the node is sent to the caller given its path.
This method provides an alternative way to reference nodes when node IDs aren't available, using path expressions instead. This can be useful when integrating with systems that identify elements by path rather than by ID.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
Path to node in the proprietary format.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns the node id for the node.
TYPE:
|
staticmethod
Requests that a batch of nodes is sent to the caller given their backend node ids.
This method allows for efficient batch processing when you have multiple backend node IDs and need to convert them to frontend node IDs for further operations.
| PARAMETER | DESCRIPTION |
|---|---|
backend_node_ids
|
The array of backend node ids.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns an array of node ids.
TYPE:
|
staticmethod
Re-does the last undone action.
This method works in conjunction with undo and markUndoableState to provide a transactional approach to DOM manipulations, allowing for stepping back and forth through a sequence of changes.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to redo the last undone action.
TYPE:
|
staticmethod
Enables console to refer to the node with given id via $x command line API.
This method creates a bridge between automated testing/scripting and manual console interaction, making it easy to reference specific nodes in the console for debugging or experimentation.
| PARAMETER | DESCRIPTION |
|---|---|
node_id
|
DOM node id to be accessible by means of $x command line API.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to set the inspected node.
TYPE:
|
staticmethod
Sets if stack traces should be captured for Nodes.
This method enables or disables the collection of stack traces when DOM nodes are created, which can be extremely valuable for debugging complex applications to understand where and why specific DOM elements are being created.
| PARAMETER | DESCRIPTION |
|---|---|
enable
|
Enable or disable stack trace collection.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to enable or disable node stack traces.
TYPE:
|
staticmethod
Undoes the last performed action.
This method works in conjunction with redo and markUndoableState to provide transactional control over DOM manipulations, allowing for reverting changes when needed.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to undo the last performed action.
TYPE:
|
Network Commands
Implementation of Chrome DevTools Protocol for the Network domain.
This class provides commands for monitoring and manipulating network activities, enabling detailed inspection and control over HTTP requests and responses. The Network domain exposes comprehensive network-related information including: - Request/response headers and bodies - Resource timing and caching behavior - Cookie management and security details - Network conditions emulation - Traffic interception and modification
The commands allow developers to analyze performance, debug network issues, and test application behavior under various network conditions.
staticmethod
Clears browser cache storage.
This command is essential for testing cache behavior and ensuring fresh resource loading. It affects all cached resources including: - CSS/JavaScript files - Images and media assets - API response caching
Use cases: - Testing cache invalidation strategies - Reproducing issues with stale content - Performance benchmarking without cache influence
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to clear the entire browser cache
TYPE:
|
staticmethod
Command to clear all cookies stored in the browser.
This can be beneficial for testing scenarios where you need to simulate a fresh user session without any previously stored cookies that might affect the application's behavior.
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: A command to clear all cookies in the browser. |
staticmethod
Deletes browser cookies with matching criteria.
Provides granular control over cookie removal through multiple parameters: - Delete by name only (affects all matching cookies) - Scope deletion using URL, domain, or path - Handle partitioned cookies for privacy-aware applications
| PARAMETER | DESCRIPTION |
|---|---|
name
|
Name of the cookies to remove (required)
TYPE:
|
url
|
Delete cookies for specific URL (domain/path must match)
TYPE:
|
domain
|
Exact domain for cookie deletion
TYPE:
|
path
|
Exact path for cookie deletion
TYPE:
|
partition_key
|
Partition key attributes for cookie isolation
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to execute selective cookie deletion
TYPE:
|
staticmethod
Stops network monitoring and event reporting.
Preserves network state but stops: - Request/response events - WebSocket message tracking - Loading progress notifications
Use when: - Reducing overhead during non-network operations - Pausing monitoring temporarily - Finalizing network-related tests
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to disable network monitoring
TYPE:
|
staticmethod
Enables network monitoring with configurable buffers.
| PARAMETER | DESCRIPTION |
|---|---|
max_total_buffer_size
|
Total memory buffer for network data (bytes)
TYPE:
|
max_resource_buffer_size
|
Per-resource buffer limit (bytes)
TYPE:
|
max_post_data_size
|
Maximum POST payload to capture (bytes)
TYPE:
|
Recommended settings: - Increase buffers for long-running sessions - Adjust post size for API testing - Monitor memory usage with large buffers
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to enable network monitoring
TYPE:
|
staticmethod
Retrieves cookies matching specified URLs.
| PARAMETER | DESCRIPTION |
|---|---|
urls
|
list of URLs to scope cookie retrieval
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command returning cookie details including: - Name, value, and attributes - Security and scope parameters - Expiration and size information
TYPE:
|
Usage notes: - Empty URL list returns all cookies - Includes HTTP-only and secure cookies - Shows partitioned cookie status
staticmethod
Retrieves POST data from a specific network request.
Essential for: - Form submission analysis - API request debugging - File upload monitoring - Security testing
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
Unique identifier for the network request
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns: - Raw POST data content - Multipart form data (excluding file contents) - Content encoding information
TYPE:
|
Note: Large POST bodies may be truncated based on buffer settings
staticmethod
Retrieves the full content of a network response.
Supports various content types: - Text-based resources (HTML, CSS, JSON) - Base64-encoded binary content (images, media) - Gzip/deflate compressed responses
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
Unique network request identifier
TYPE:
|
Important considerations: - Response must be available in browser memory - Large responses may require streaming approaches - Sensitive data should be handled securely
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command returning response body and encoding details
TYPE:
|
staticmethod
Controls browser's cache mechanism.
Use cases: - Testing resource update behavior - Forcing fresh content loading - Performance impact analysis - Cache-busting scenarios
| PARAMETER | DESCRIPTION |
|---|---|
cache_disabled
|
True to disable caching, False to enable
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to modify cache behavior
TYPE:
|
Note: Affects all requests until re-enabled
staticmethod
set_cookie(name, value, url=None, domain=None, path=None, secure=None, http_only=None, same_site=None, expires=None, priority=None, same_party=None, source_scheme=None, source_port=None, partition_key=None)
Creates or updates a cookie with specified attributes.
Comprehensive cookie control supporting: - Session and persistent cookies - Security attributes (Secure, HttpOnly) - SameSite policies - Cookie partitioning - Priority levels
| PARAMETER | DESCRIPTION |
|---|---|
name
|
Cookie name
TYPE:
|
value
|
Cookie value
TYPE:
|
url
|
Target URL for the cookie
TYPE:
|
domain
|
Cookie domain scope
TYPE:
|
path
|
Cookie path scope
TYPE:
|
secure
|
Require HTTPS
TYPE:
|
http_only
|
Prevent JavaScript access
TYPE:
|
same_site
|
Cross-site access policy
TYPE:
|
expires
|
Expiration timestamp
TYPE:
|
priority
|
Cookie priority level
TYPE:
|
same_party
|
First-Party Sets flag
TYPE:
|
source_scheme
|
Cookie source context
TYPE:
|
source_port
|
Source port restriction
TYPE:
|
partition_key
|
Storage partition key
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command that returns success status
TYPE:
|
Security considerations: - Use secure flag for sensitive data - Consider SameSite policies - Be aware of cross-site implications
staticmethod
Sets multiple cookies in a single operation.
Efficient for: - Batch cookie operations - Session state restoration - Testing multiple authentication states - Cross-domain cookie setup
| PARAMETER | DESCRIPTION |
|---|---|
cookies
|
list of cookie parameters including name, value, and attributes
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command for bulk cookie setting
TYPE:
|
Performance note: - More efficient than multiple set_cookie calls - Consider memory impact with large batches
staticmethod
Applies custom HTTP headers to all subsequent requests.
Enables advanced scenarios: - A/B testing with custom headers - Authentication bypass for testing - Content negotiation simulations - Security header validation
| PARAMETER | DESCRIPTION |
|---|---|
headers
|
list of key-value header pairs
TYPE:
|
Security notes: - Headers are applied browser-wide - Sensitive headers (e.g., Authorization) persist until cleared - Use with caution in shared environments
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to set global HTTP headers
TYPE:
|
staticmethod
Overrides the browser's User-Agent string.
Use cases: - Device/browser simulation - Compatibility testing - Content negotiation - Bot detection bypass
| PARAMETER | DESCRIPTION |
|---|---|
user_agent
|
Complete User-Agent string
TYPE:
|
accept_language
|
Language preference header
TYPE:
|
platform
|
Platform identifier
TYPE:
|
user_agent_metadata
|
Detailed UA metadata
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to override user agent
TYPE:
|
Testing considerations: - Affects all subsequent requests - May impact server-side behavior - Consider mobile/desktop differences
staticmethod
Restores default content encoding acceptance.
Effects: - Resets compression preferences - Restores default Accept-Encoding header - Allows server-chosen encoding
Use when: - Testing encoding fallbacks - Debugging compression issues - Resetting after encoding tests
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to clear encoding overrides
TYPE:
|
staticmethod
Controls the Reporting API functionality.
Features: - Network error reporting - Deprecation notices - CSP violation reports - CORS issues
| PARAMETER | DESCRIPTION |
|---|---|
enabled
|
True to enable, False to disable
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to configure Reporting API
TYPE:
|
Note: Requires browser support for Reporting API
staticmethod
Searches for content within response bodies.
Powerful for: - Content verification - Security scanning - Data extraction - Response validation
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
Target response identifier
TYPE:
|
query
|
Search string or pattern
TYPE:
|
case_sensitive
|
Match case sensitivity
TYPE:
|
is_regex
|
Use regular expression matching
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command returning match results
TYPE:
|
Performance tip: - Use specific queries for large responses - Consider regex complexity
staticmethod
Blocks specified URLs from loading.
Key features: - Pattern-based URL blocking - Resource type filtering - Network request prevention - Error simulation
| PARAMETER | DESCRIPTION |
|---|---|
urls
|
list of URL patterns to block Supports wildcards and pattern matching
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to set URL blocking rules
TYPE:
|
Common applications: - Ad/tracker blocking simulation - Resource loading control - Error handling testing - Network isolation testing
staticmethod
Controls Service Worker interception of network requests.
Use cases: - Testing direct network behavior - Bypassing offline functionality - Debug caching issues - Performance comparison
| PARAMETER | DESCRIPTION |
|---|---|
bypass
|
True to skip Service Worker, False to allow
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to configure Service Worker behavior
TYPE:
|
Impact: - Affects offline capabilities - Changes caching behavior - Modifies push notifications
staticmethod
Retrieves SSL/TLS certificate information for a domain.
Provides: - Certificate chain details - Validation status - Expiration information - Issuer details
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
Target domain for certificate inspection
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command returning certificate data
TYPE:
|
Security applications: - Certificate validation - SSL/TLS verification - Security assessment - Chain of trust verification
staticmethod
Retrieves response body from an intercepted request.
Essential for: - Response modification - Content inspection - Security testing - API response validation
| PARAMETER | DESCRIPTION |
|---|---|
interception_id
|
Identifier for intercepted request
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command providing intercepted response content
TYPE:
|
Note: - Must be used with interception enabled - Supports streaming responses - Handles various content types
staticmethod
Specifies accepted content encodings for requests.
Controls: - Compression algorithms - Transfer encoding - Content optimization
| PARAMETER | DESCRIPTION |
|---|---|
encodings
|
list of accepted encoding methods (gzip, deflate, br, etc.)
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to set encoding preferences
TYPE:
|
Performance implications: - Affects bandwidth usage - Impacts response time - Changes server behavior
staticmethod
Enables/disables debug stack attachment to requests.
Debug features: - Stack trace collection - Request origin tracking - Initialization context - Call site identification
| PARAMETER | DESCRIPTION |
|---|---|
enabled
|
True to attach debug info, False to disable
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to configure debug stack attachment
TYPE:
|
Performance note: - May impact performance when enabled - Useful for development/debugging - Consider memory usage
staticmethod
set_cookie_controls(enable_third_party_cookie_restriction, disable_third_party_cookie_metadata=None, disable_third_party_cookie_heuristics=None)
Configures third-party cookie handling policies.
Privacy features: - Cookie access control - Third-party restrictions - Tracking prevention - Privacy policy enforcement
| PARAMETER | DESCRIPTION |
|---|---|
enable_third_party_cookie_restriction
|
Enable restrictions
TYPE:
|
disable_third_party_cookie_metadata
|
Skip metadata checks
TYPE:
|
disable_third_party_cookie_heuristics
|
Disable detection logic
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to set cookie control policies
TYPE:
|
Security implications: - Affects cross-site tracking - Changes authentication behavior - Impacts embedded content
staticmethod
Enables streaming of response content.
Useful for: - Large file downloads - Progressive loading - Memory optimization - Real-time processing
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
Target request identifier
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to initiate content streaming
TYPE:
|
Best practices: - Monitor memory usage - Handle stream chunks efficiently - Consider error recovery
staticmethod
Creates a stream for intercepted response body.
Applications: - Large response handling - Content modification - Bandwidth optimization - Progressive processing
| PARAMETER | DESCRIPTION |
|---|---|
interception_id
|
Intercepted response identifier
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command returning stream handle
TYPE:
|
Stream handling: - Supports chunked transfer - Manages memory efficiently - Enables real-time processing
staticmethod
emulate_network_conditions(offline, latency, download_throughput, upload_throughput, connection_type=None, packet_loss=None, packet_queue_length=None, packet_reordering=None)
Emulates custom network conditions for realistic testing scenarios.
Simulates various network profiles including: - Offline mode - High-latency connections - Bandwidth throttling - Unreliable network characteristics
| PARAMETER | DESCRIPTION |
|---|---|
offline
|
Simulate complete network disconnection
TYPE:
|
latency
|
Minimum latency in milliseconds (round-trip time)
TYPE:
|
download_throughput
|
Max download speed (bytes/sec, -1 to disable)
TYPE:
|
upload_throughput
|
Max upload speed (bytes/sec, -1 to disable)
TYPE:
|
connection_type
|
Network connection type (cellular, wifi, etc.)
TYPE:
|
packet_loss
|
Simulated packet loss percentage (0-100)
TYPE:
|
packet_queue_length
|
Network buffer size simulation
TYPE:
|
packet_reordering
|
Enable packet order randomization
TYPE:
|
Typical use cases: - Testing progressive loading states - Validating offline-first functionality - Performance optimization under constrained networks
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to activate network emulation
TYPE:
|
staticmethod
Retrieves security isolation information.
Provides: - CORS status - Cross-origin isolation - Security context - Frame isolation
| PARAMETER | DESCRIPTION |
|---|---|
frame_id
|
Optional frame to check
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command returning isolation status
TYPE:
|
Security aspects: - Cross-origin policies - Iframe security - Site isolation - Content protection
staticmethod
Loads a network resource with specific options.
Features: - Custom request configuration - Resource loading control - Frame-specific loading - Error handling
| PARAMETER | DESCRIPTION |
|---|---|
url
|
Resource URL to load
TYPE:
|
options
|
Loading configuration
TYPE:
|
frame_id
|
Target frame context
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to load resource
TYPE:
|
Usage considerations: - Respects CORS policies - Handles authentication - Manages redirects - Supports streaming
staticmethod
Replays an XHR request.
Applications: - Request debugging - Response testing - Race condition analysis - API verification
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
XHR request to replay
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
CDP command to replay XHR
TYPE:
|
Note: - Maintains original headers - Preserves request body - Updates timestamps - Creates new request ID
Input Commands
A class for simulating user input events using Chrome DevTools Protocol.
The Input domain provides methods for simulating user input, including: - Keyboard events (key presses, releases) - Mouse events (clicks, movements, wheel) - Touch events (taps, multi-touch gestures) - Drag and drop events - Synthetic gestures (pinch, scroll, tap)
These methods allow for programmatic control of input events without requiring actual user interaction, making it useful for testing and automation.
staticmethod
Generates a command to cancel any active dragging in the page.
This is useful when you need to interrupt an ongoing drag operation that might have been started with dispatchDragEvent or by other means.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to cancel dragging.
TYPE:
|
staticmethod
dispatch_key_event(type, modifiers=None, timestamp=None, text=None, unmodified_text=None, key_identifier=None, code=None, key=None, windows_virtual_key_code=None, native_virtual_key_code=None, auto_repeat=None, is_keypad=None, is_system_key=None, location=None, commands=None)
Generates a command to dispatch a key event to the page.
This method can simulate various types of keyboard events such as key presses, key releases, and character inputs.
| PARAMETER | DESCRIPTION |
|---|---|
type
|
Type of the key event. Allowed values: keyDown, keyUp, rawKeyDown, char. - keyDown: Corresponds to a user pressing a key - keyUp: Corresponds to a user releasing a key - rawKeyDown: A physical key press, without the text processing - char: Generates a character without explicit key events
TYPE:
|
modifiers
|
Bit field representing pressed modifier keys. Values: Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0). For example, to simulate Ctrl+Shift, use 10.
TYPE:
|
timestamp
|
Time at which the event occurred, in seconds since epoch.
TYPE:
|
text
|
Text as generated by processing a virtual key code with a keyboard layout. Not needed for 'keyUp' and 'rawKeyDown' events (default: "").
TYPE:
|
unmodified_text
|
Text that would have been generated by the keyboard without modifiers (except for shift). Useful for shortcut key handling (default: "").
TYPE:
|
key_identifier
|
Unique key identifier (e.g., 'U+0041') (default: "").
TYPE:
|
code
|
Unique DOM defined string value for each physical key (e.g., 'KeyA') (default: "").
TYPE:
|
key
|
Unique DOM defined string value describing the meaning of the key in the context of active modifiers, keyboard layout, etc. (e.g., 'AltGr') (default: "").
TYPE:
|
windows_virtual_key_code
|
Windows virtual key code (default: 0).
TYPE:
|
native_virtual_key_code
|
Native virtual key code (default: 0).
TYPE:
|
auto_repeat
|
Whether the event was generated from auto repeat (default: false).
TYPE:
|
is_keypad
|
Whether the event was generated from the keypad (default: false).
TYPE:
|
is_system_key
|
Whether the event was a system key event (default: false).
TYPE:
|
location
|
Whether the event was from the left or right side of the keyboard: 0=Default, 1=Left, 2=Right (default: 0).
TYPE:
|
commands
|
Editing commands to send with the key event (e.g., 'selectAll')
(default: []). These are related to but not equal to the command names
used in
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to dispatch the key event.
TYPE:
|
staticmethod
dispatch_mouse_event(type, x, y, modifiers=None, timestamp=None, button=None, click_count=None, force=None, tangential_pressure=None, tilt_x=None, tilt_y=None, twist=None, delta_x=None, delta_y=None, pointer_type=None)
Generates a command to dispatch a mouse event to the page.
This method allows simulating various mouse interactions such as clicks, movements, and wheel scrolling.
| PARAMETER | DESCRIPTION |
|---|---|
type
|
Type of the mouse event. Allowed values: - mousePressed: Mouse button pressed - mouseReleased: Mouse button released - mouseMoved: Mouse moved - mouseWheel: Mouse wheel rotated
TYPE:
|
x
|
X coordinate of the event relative to the main frame's viewport in CSS pixels.
TYPE:
|
y
|
Y coordinate of the event relative to the main frame's viewport in CSS pixels. 0 refers to the top of the viewport, and Y increases going down.
TYPE:
|
modifiers
|
Bit field representing pressed modifier keys. Values: Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0).
TYPE:
|
timestamp
|
Time at which the event occurred, in seconds since epoch.
TYPE:
|
button
|
Mouse button being pressed/released. Default is "none". Allowed values: "none", "left", "middle", "right", "back", "forward".
TYPE:
|
click_count
|
Number of times the mouse button was clicked (default: 0). For example, 2 for a double-click.
TYPE:
|
force
|
The normalized pressure, which has a range of [0,1] (default: 0). Used primarily for pressure-sensitive inputs.
TYPE:
|
tangential_pressure
|
The normalized tangential pressure, which has a range of [-1,1] (default: 0). Used for stylus input.
TYPE:
|
tilt_x
|
The plane angle between the Y-Z plane and the plane containing both the stylus axis and the Y axis, in degrees of the range [-90,90]. A positive tiltX is to the right (default: 0).
TYPE:
|
tilt_y
|
The plane angle between the X-Z plane and the plane containing both the stylus axis and the X axis, in degrees of the range [-90,90]. A positive tiltY is towards the user (default: 0).
TYPE:
|
twist
|
The clockwise rotation of a pen stylus around its own major axis, in degrees in the range [0,359] (default: 0).
TYPE:
|
delta_x
|
X delta in CSS pixels for mouse wheel event (default: 0). Positive values scroll right.
TYPE:
|
delta_y
|
Y delta in CSS pixels for mouse wheel event (default: 0). Positive values scroll up.
TYPE:
|
pointer_type
|
Pointer type (default: "mouse"). Allowed values: "mouse", "pen".
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to dispatch the mouse event.
TYPE:
|
staticmethod
Generates a command to dispatch a touch event to the page.
This method allows simulating touch interactions on touch-enabled devices or emulated touch environments.
| PARAMETER | DESCRIPTION |
|---|---|
type
|
Type of the touch event. Allowed values: - touchStart: Touch started - at least one point must be specified - touchEnd: Touch ended - points that are no longer pressed should be removed - touchMove: Touch moved - active points should be updated - touchCancel: Touch canceled - clears all touch points Touch end and cancel events must not contain any touch points, while touch start and move must contain at least one.
TYPE:
|
touch_points
|
list of active touch points. One event per any changed point (compared to previous event) is generated, emulating pressing/moving/releasing points one by one. Each point includes coordinates and other properties.
TYPE:
|
modifiers
|
Bit field representing pressed modifier keys. Values: Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0).
TYPE:
|
timestamp
|
Time at which the event occurred, in seconds since epoch.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to dispatch the touch event.
TYPE:
|
staticmethod
Generates a command to ignore input events (useful while auditing page).
When enabled, all input events will be ignored, which can be useful during automated tests or when you want to prevent user interaction while performing certain operations.
| PARAMETER | DESCRIPTION |
|---|---|
enabled
|
If true, input events processing will be ignored.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set ignore input events.
TYPE:
|
staticmethod
Generates a command to dispatch a drag event into the page.
This experimental method allows simulating drag and drop operations by dispatching drag events at specific coordinates.
| PARAMETER | DESCRIPTION |
|---|---|
type
|
Type of the drag event. Allowed values: - dragEnter: Fired when a dragged item enters a valid drop target - dragOver: Fired when a dragged item is being dragged over a valid drop target - drop: Fired when an item is dropped on a valid drop target - dragCancel: Fired when a drag operation is being canceled
TYPE:
|
x
|
X coordinate of the event relative to the main frame's viewport in CSS pixels.
TYPE:
|
y
|
Y coordinate of the event relative to the main frame's viewport in CSS pixels. 0 refers to the top of the viewport, and Y increases going down.
TYPE:
|
data
|
Drag data containing items being dragged, their MIME types, and other information.
TYPE:
|
modifiers
|
Bit field representing pressed modifier keys. Values: Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to dispatch the drag event.
TYPE:
|
staticmethod
emulate_touch_from_mouse_event(type, x, y, button, timestamp=None, delta_x=None, delta_y=None, modifiers=None, click_count=None)
Generates a command to emulate touch event from the mouse event parameters.
This experimental method allows converting mouse events into touch events, useful for testing touch interactions in environments where touch is not available.
| PARAMETER | DESCRIPTION |
|---|---|
type
|
Type of the mouse event to convert. Allowed values: - mousePressed: Converted to touchStart - mouseReleased: Converted to touchEnd - mouseMoved: Converted to touchMove - mouseWheel: May trigger scrolling
TYPE:
|
x
|
X coordinate of the mouse pointer in device-independent pixels (DIP).
TYPE:
|
y
|
Y coordinate of the mouse pointer in DIP.
TYPE:
|
button
|
Mouse button. Only "none", "left", "right" are supported.
TYPE:
|
timestamp
|
Time at which the event occurred, in seconds since epoch. Default is current time.
TYPE:
|
delta_x
|
X delta in DIP for mouse wheel event (default: 0). Used for scrolling.
TYPE:
|
delta_y
|
Y delta in DIP for mouse wheel event (default: 0). Used for scrolling.
TYPE:
|
modifiers
|
Bit field representing pressed modifier keys. Values: Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0).
TYPE:
|
click_count
|
Number of times the mouse button was clicked (default: 0). For example, 2 for a double-click.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to emulate touch from mouse event.
TYPE:
|
staticmethod
ime_set_composition(text, selection_start, selection_end, replacement_start=None, replacement_end=None)
Generates a command to set the current candidate text for IME.
This experimental method sets the text for Input Method Editors (IME), which are used for entering characters in languages that require more keystrokes than the number of characters (like Chinese, Japanese, Korean).
Use imeCommitComposition to commit the final text. Use imeSetComposition with empty string as text to cancel composition.
| PARAMETER | DESCRIPTION |
|---|---|
text
|
The text to insert as the IME composition.
TYPE:
|
selection_start
|
Start position of the selection within the composition text.
TYPE:
|
selection_end
|
End position of the selection within the composition text.
TYPE:
|
replacement_start
|
Start position of the text to be replaced (default: same as selection_start).
TYPE:
|
replacement_end
|
End position of the text to be replaced (default: same as selection_end).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set IME composition.
TYPE:
|
staticmethod
Generates a command to emulate inserting text that doesn't come from a key press.
This experimental method is useful for inserting text that would normally come from sources other than keyboard, such as emoji pickers, IMEs, or clipboard pastes.
| PARAMETER | DESCRIPTION |
|---|---|
text
|
The text to insert.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to insert text.
TYPE:
|
staticmethod
Generates a command to control interception of drag and drop events.
This experimental method prevents default drag and drop behavior and instead emits Input.dragIntercepted events. Drag and drop behavior can then be directly controlled via Input.dispatchDragEvent.
This is useful for implementing custom drag and drop logic or for testing drag and drop behavior in automated tests.
| PARAMETER | DESCRIPTION |
|---|---|
enabled
|
If true, drag events will be intercepted and reported as dragIntercepted events, preventing the default behavior.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set drag interception.
TYPE:
|
staticmethod
Generates a command to synthesize a pinch gesture over a time period.
This experimental method creates a synthetic pinch gesture (zoom in/out) by issuing appropriate touch events over time. This is useful for testing pinch-to-zoom functionality in web applications.
| PARAMETER | DESCRIPTION |
|---|---|
x
|
X coordinate of the start of the gesture in CSS pixels.
TYPE:
|
y
|
Y coordinate of the start of the gesture in CSS pixels.
TYPE:
|
scale_factor
|
Relative scale factor after zooming: - >1.0 zooms in (fingers moving apart) - <1.0 zooms out (fingers moving together)
TYPE:
|
relative_speed
|
Relative pointer speed in pixels per second (default: 800). Controls how fast the gesture happens.
TYPE:
|
gesture_source_type
|
Which type of input events to be generated: - 'default': Platform's preferred input type - 'touch': Touch input - 'mouse': Mouse input
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to synthesize a pinch gesture.
TYPE:
|
staticmethod
synthesize_scroll_gesture(x, y, x_distance=None, y_distance=None, x_overscroll=None, y_overscroll=None, prevent_fling=None, speed=None, gesture_source_type=None, repeat_count=None, repeat_delay_ms=None, interaction_marker_name=None)
Generates a command to synthesize a scroll gesture over a time period.
This experimental method creates a synthetic scroll gesture by issuing appropriate touch events over time. This is useful for testing scrolling behavior in web applications.
| PARAMETER | DESCRIPTION |
|---|---|
x
|
X coordinate of the start of the gesture in CSS pixels.
TYPE:
|
y
|
Y coordinate of the start of the gesture in CSS pixels.
TYPE:
|
x_distance
|
The distance to scroll along the X axis (positive to scroll left).
TYPE:
|
y_distance
|
The distance to scroll along the Y axis (positive to scroll up).
TYPE:
|
x_overscroll
|
The number of additional pixels to scroll back along the X axis, in addition to the given distance. This creates an overscroll effect (rubber-banding).
TYPE:
|
y_overscroll
|
The number of additional pixels to scroll back along the Y axis, in addition to the given distance. This creates an overscroll effect (rubber-banding).
TYPE:
|
prevent_fling
|
Prevent fling (default: true). If false, a fling animation might continue after the gesture.
TYPE:
|
speed
|
Swipe speed in pixels per second (default: 800).
TYPE:
|
gesture_source_type
|
Which type of input events to be generated: - 'default': Platform's preferred input type - 'touch': Touch input - 'mouse': Mouse input
TYPE:
|
repeat_count
|
The number of times to repeat the gesture (default: 0).
TYPE:
|
repeat_delay_ms
|
The number of milliseconds delay between each repeat (default: 250).
TYPE:
|
interaction_marker_name
|
The name of the interaction markers to generate, if not empty. Used for tracking gesture timing in performance measurements.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to synthesize a scroll gesture.
TYPE:
|
staticmethod
Generates a command to synthesize a tap gesture over a time period.
This experimental method creates a synthetic tap gesture by issuing appropriate touch events over time. This is useful for testing touch interaction in web applications.
| PARAMETER | DESCRIPTION |
|---|---|
x
|
X coordinate of the start of the gesture in CSS pixels.
TYPE:
|
y
|
Y coordinate of the start of the gesture in CSS pixels.
TYPE:
|
duration
|
Duration between touchdown and touchup events in milliseconds (default: 50). Controls how long the tap gesture takes.
TYPE:
|
tap_count
|
Number of times to perform the tap (e.g., 2 for a double tap, default: 1).
TYPE:
|
gesture_source_type
|
Which type of input events to be generated: - 'default': Platform's preferred input type - 'touch': Touch input - 'mouse': Mouse input
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to synthesize a tap gesture.
TYPE:
|
Fetch Commands
This class encapsulates the fetch commands of the Chrome DevTools Protocol (CDP).
CDP's Fetch domain allows interception and modification of network requests at the application layer. This enables developers to examine, modify, and control network traffic, which is particularly useful for testing, debugging, and advanced automation scenarios.
The commands defined in this class provide functionality for: - Enabling and disabling fetch request interception - Continuing, fulfilling, or failing intercepted requests - Handling authentication challenges - Retrieving and modifying response bodies - Processing response data as streams
staticmethod
continue_request(request_id, url=None, method=None, post_data=None, headers=None, intercept_response=None)
Creates a command to continue a paused fetch request.
This command allows the browser to resume a fetch operation that has been intercepted. You can modify the fetch request URL, method, headers, and body before continuing.
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
The ID of the fetch request to continue.
TYPE:
|
url
|
The new URL for the fetch request. Defaults to None.
TYPE:
|
method
|
The HTTP method to use (e.g., 'GET', 'POST'). Defaults to None.
TYPE:
|
post_data
|
The body data to send with the fetch request. Defaults to None.
TYPE:
|
headers
|
A list of HTTP headers to include in the fetch request. Defaults to None.
TYPE:
|
intercept_response
|
Indicates if the response should be intercepted. Defaults to None.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: A command for continuing the fetch request. |
staticmethod
continue_request_with_auth(request_id, auth_challenge_response, proxy_username=None, proxy_password=None)
Creates a command to continue a paused fetch request with authentication.
This command is used when the fetch operation requires authentication. It provides the necessary credentials to continue the request.
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
The ID of the fetch request to continue.
TYPE:
|
auth_challenge_response
|
The authentication challenge response type. |
proxy_username
|
The username for proxy authentication. Defaults to None.
TYPE:
|
proxy_password
|
The password for proxy authentication. Defaults to None.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: A command for continuing the fetch request with authentication. |
staticmethod
Creates a command to disable fetch interception.
This command stops the browser from intercepting fetch requests.
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: A command for disabling fetch interception. |
staticmethod
Creates a command to enable fetch interception.
This command allows the browser to start intercepting fetch requests. You can specify whether to handle authentication challenges and the types of resources to intercept.
| PARAMETER | DESCRIPTION |
|---|---|
handle_auth_requests
|
Indicates if authentication requests should be handled.
TYPE:
|
url_pattern
|
Pattern to match URLs for interception. Defaults to '*'.
TYPE:
|
resource_type
|
The type of resource to intercept. Defaults to None.
TYPE:
|
request_stage
|
The stage of the request to intercept. Defaults to None.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: A command for enabling fetch interception. |
staticmethod
Creates a command to simulate a failure in a fetch request.
This command allows you to simulate a failure for a specific fetch operation, providing a reason for the failure.
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
The ID of the fetch request to fail.
TYPE:
|
error_reason
|
The reason for the failure.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: A command for failing the fetch request. |
staticmethod
Creates a command to fulfill a fetch request with a custom response.
This command allows you to provide a custom response for a fetch operation, including the HTTP status code, headers, and body content.
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
The ID of the fetch request to fulfill.
TYPE:
|
response_code
|
The HTTP status code to return.
TYPE:
|
response_headers
|
A list of response headers. Defaults to None.
TYPE:
|
body
|
The body content of the response. Defaults to None.
TYPE:
|
response_phrase
|
The response phrase (e.g., 'OK', 'Not Found'). Defaults to None.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: A command for fulfilling the fetch request. |
staticmethod
Creates a command to retrieve the response body of a fetch request.
This command allows you to access the body of a completed fetch operation, which can be useful for analyzing the response data.
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
The ID of the fetch request to retrieve the body from.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[GetResponseBodyResponse]
|
Command[GetResponseBodyResponse]: A command for getting the response body. |
staticmethod
Creates a command to continue a fetch response for an intercepted request.
This command allows the browser to continue the response flow for a specific fetch request, including customizing the HTTP status code, headers, and response phrase.
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
The ID of the fetch request to continue the response for.
TYPE:
|
response_code
|
The HTTP status code to send. Defaults to None.
TYPE:
|
response_headers
|
A list of response headers. Defaults to None.
TYPE:
|
response_phrase
|
The response phrase (e.g., 'OK'). Defaults to None.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: A command for continuing the fetch response. |
staticmethod
Creates a command to take the response body as a stream.
This command allows you to receive the response body as a stream which can be useful for handling large responses.
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
The ID of the fetch request to take the response body stream from.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[TakeResponseBodyAsStreamResponse]
|
Command[TakeResponseBodyAsStreamResponse]: A command for taking the response body as a stream. |
Browser Commands
BrowserCommands class provides a set of commands to interact with the browser's main functionality based on CDP. These commands allow for managing browser windows, such as closing windows, retrieving window IDs, and adjusting window bounds (size and state).
The commands defined in this class provide functionality for: - Managing browser windows and targets. - Setting permissions and download behavior. - Controlling browser windows (size, state). - Retrieving browser information and versioning.
staticmethod
Generates a command to get browser version information.
| RETURNS | DESCRIPTION |
|---|---|
Command[GetVersionResponse]
|
Command[GetVersionResponse]: The CDP command that returns browser version details including protocol version, product name, revision, and user agent. |
staticmethod
Generates a command to reset all permissions.
| PARAMETER | DESCRIPTION |
|---|---|
browser_context_id
|
The browser context to reset permissions for. If not specified, resets permissions for the default context.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: The CDP command that returns a basic success response. |
staticmethod
Generates a command to cancel a download.
| PARAMETER | DESCRIPTION |
|---|---|
guid
|
Global unique identifier of the download.
TYPE:
|
browser_context_id
|
The browser context the download belongs to. If not specified, uses the default context.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: The CDP command that returns a basic success response. |
staticmethod
Generates a command to crash the browser main process.
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: The CDP command that returns a basic success response before crashing the browser. |
staticmethod
Generates a command to crash the browser GPU process.
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: The CDP command that returns a basic success response before crashing the GPU process. |
staticmethod
Generates a command to set the download behavior for the browser.
| PARAMETER | DESCRIPTION |
|---|---|
behavior
|
The behavior to set for downloads.
TYPE:
|
download_path
|
The path to set for downloads.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: The CDP command that returns a basic success response after setting the download path. |
staticmethod
Generates a command to close the browser.
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: The CDP command that returns a basic success response before closing the browser. |
staticmethod
Generates a command to get the window for a given target ID.
| PARAMETER | DESCRIPTION |
|---|---|
target_id
|
The target_id to get the window for.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[GetWindowForTargetResponse]
|
Command[GetWindowForTargetResponse]: The CDP command that returns window information including windowId and bounds. |
staticmethod
Generates a command to set the bounds of a window.
| PARAMETER | DESCRIPTION |
|---|---|
window_id
|
The ID of the window to set the bounds for.
TYPE:
|
bounds
|
The bounds to set for the window, which should include windowState and optionally width, height, x, and y coordinates.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: The CDP command that returns a basic success response after setting the window bounds. |
staticmethod
Generates a command to maximize a window.
| PARAMETER | DESCRIPTION |
|---|---|
window_id
|
The ID of the window to maximize.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: The CDP command that returns a basic success response after maximizing the window. |
staticmethod
Generates a command to minimize a window.
| PARAMETER | DESCRIPTION |
|---|---|
window_id
|
The ID of the window to minimize.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: The CDP command that returns a basic success response after minimizing the window. |
staticmethod
Generates a command to grant specific permissions to the given origin.
| PARAMETER | DESCRIPTION |
|---|---|
permissions
|
list of permissions to grant. See PermissionType enum for available permissions.
TYPE:
|
origin
|
The origin to grant permissions to. If not specified, grants for all origins.
TYPE:
|
browser_context_id
|
The browser context to grant permissions in. If not specified, uses the default context.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command[Response]
|
Command[Response]: The CDP command that returns a basic success response after granting the specified permissions. |
Target Commands
A class for managing browser targets using Chrome DevTools Protocol.
The Target domain of CDP supports additional targets discovery and allows to attach to them. Targets can represent browser tabs, windows, frames, web workers, service workers, etc. The domain provides methods to create, discover, and control these targets.
This class provides methods to create commands for interacting with browser targets, including creating, activating, attaching to, and closing targets through CDP commands.
staticmethod
Generates a command to activate (focus) a target.
| PARAMETER | DESCRIPTION |
|---|---|
target_id
|
ID of the target to activate.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to activate the target.
TYPE:
|
staticmethod
Generates a command to attach to a target with the given ID.
When attached to a target, you can send commands to it and receive events from it. This is essential for controlling and automating targets like browser tabs.
| PARAMETER | DESCRIPTION |
|---|---|
target_id
|
ID of the target to attach to.
TYPE:
|
flatten
|
If true, enables "flat" access to the session via specifying sessionId attribute in the commands. This is recommended as the non-flattened mode is being deprecated. See https://crbug.com/991325
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to attach to the target, which will return a sessionId.
TYPE:
|
staticmethod
Generates a command to close a target.
If the target is a page or a tab, it will be closed. This is equivalent to clicking the close button on a browser tab.
| PARAMETER | DESCRIPTION |
|---|---|
target_id
|
ID of the target to close.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to close the target, which will return a success flag.
TYPE:
|
staticmethod
create_browser_context(dispose_on_detach=None, proxy_server=None, proxy_bypass_list=None, origins_with_universal_network_access=None)
Generates a command to create a new empty browser context.
A browser context is similar to an incognito profile but you can have more than one. Each context has its own set of cookies, local storage, and other browser data. This is useful for testing multiple users or isolating sessions.
| PARAMETER | DESCRIPTION |
|---|---|
dispose_on_detach
|
If specified, the context will be disposed when the debugging session disconnects.
TYPE:
|
proxy_server
|
Proxy server string, similar to the one passed to --proxy-server command line argument (e.g., "socks5://192.168.1.100:1080").
TYPE:
|
proxy_bypass_list
|
Proxy bypass list, similar to the one passed to --proxy-bypass-list command line argument (e.g., "*.example.com,localhost").
TYPE:
|
origins_with_universal_network_access
|
An optional list of origins to grant unlimited cross-origin access to. Parts of the URL other than those constituting origin are ignored.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to create a browser context, which will return the ID of the created context.
TYPE:
|
staticmethod
create_target(url, left=None, top=None, width=None, height=None, window_state=None, browser_context_id=None, enable_begin_frame_control=None, new_window=None, background=None, for_tab=None, hidden=None)
Generates a command to create a new page (target).
This is one of the primary methods to open a new tab or window with specific properties such as position, size, and browser context.
| PARAMETER | DESCRIPTION |
|---|---|
url
|
The initial URL the page will navigate to. An empty string indicates about:blank.
TYPE:
|
left
|
Frame left position in device-independent pixels (DIP). Requires newWindow to be true or in headless mode.
TYPE:
|
top
|
Frame top position in DIP. Requires newWindow to be true or in headless mode.
TYPE:
|
width
|
Frame width in DIP.
TYPE:
|
height
|
Frame height in DIP.
TYPE:
|
window_state
|
Frame window state: normal, minimized, maximized, or fullscreen. Default is normal.
TYPE:
|
browser_context_id
|
The browser context to create the page in. If not specified, the default browser context is used.
TYPE:
|
enable_begin_frame_control
|
Whether BeginFrames for this target will be controlled via DevTools (headless shell only, not supported on MacOS yet, false by default).
TYPE:
|
new_window
|
Whether to create a new window or tab (false by default, not supported by headless shell).
TYPE:
|
background
|
Whether to create the target in background or foreground (false by default, not supported by headless shell).
TYPE:
|
for_tab
|
Whether to create the target of type "tab".
TYPE:
|
hidden
|
Whether to create a hidden target. The hidden target is observable via protocol, but not present in the tab UI strip. Cannot be created with forTab:true, newWindow:true or background:false. The life-time of the tab is limited to the life-time of the session.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to create a target, which will return the ID of the created target.
TYPE:
|
staticmethod
Generates a command to detach a session from its target.
After detaching, you will no longer receive events from the target and cannot send commands to it.
| PARAMETER | DESCRIPTION |
|---|---|
session_id
|
Session ID to detach. If not specified, detaches all sessions.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to detach from the target.
TYPE:
|
staticmethod
Generates a command to delete a browser context.
All pages belonging to the browser context will be closed without calling their beforeunload hooks. This is similar to closing an incognito profile.
| PARAMETER | DESCRIPTION |
|---|---|
browser_context_id
|
The ID of the browser context to dispose.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to dispose the browser context.
TYPE:
|
staticmethod
Generates a command to get all browser contexts created with createBrowserContext.
This is useful for obtaining a list of all available contexts for managing multiple isolated browser sessions.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to get all browser contexts, which will return an array of browser context IDs.
TYPE:
|
staticmethod
Generates a command to retrieve a list of available targets.
Targets include tabs, extensions, web workers, and other attachable entities in the browser. This is useful for discovering what targets exist before attaching to them.
| PARAMETER | DESCRIPTION |
|---|---|
filter
|
Only targets matching the filter will be reported. If filter is not specified and target discovery is currently enabled, a filter used for target discovery is used for consistency.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to get targets, which will return a list of TargetInfo objects with details about each target.
TYPE:
|
staticmethod
Generates a command to control whether to automatically attach to new targets.
This method controls whether to automatically attach to new targets which are considered to be directly related to the current one (for example, iframes or workers). When turned on, it also attaches to all existing related targets. When turned off, it automatically detaches from all currently attached targets.
| PARAMETER | DESCRIPTION |
|---|---|
auto_attach
|
Whether to auto-attach to related targets.
TYPE:
|
wait_for_debugger_on_start
|
Whether to pause new targets when attaching to them. Use Runtime.runIfWaitingForDebugger to run paused targets.
TYPE:
|
flatten
|
Enables "flat" access to the session via specifying sessionId attribute in the commands. This mode is being preferred, and non-flattened mode is being deprecated (see crbug.com/991325).
TYPE:
|
filter
|
Only targets matching filter will be attached.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set auto-attach behavior.
TYPE:
|
staticmethod
Generates a command to control target discovery.
This method controls whether to discover available targets and notify via targetCreated/targetInfoChanged/targetDestroyed events. Target discovery is useful for monitoring when new tabs, workers, or other targets are created or destroyed.
| PARAMETER | DESCRIPTION |
|---|---|
discover
|
Whether to discover available targets.
TYPE:
|
filter
|
Only targets matching filter will be discovered. If discover is false, filter must be omitted or empty.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set target discovery.
TYPE:
|
staticmethod
Generates a command to attach to the browser target.
This is an experimental method that attaches to the browser target, only using flat sessionId mode. The browser target is a special target that represents the browser itself rather than a page or other content.
| PARAMETER | DESCRIPTION |
|---|---|
session_id
|
ID of the session to attach to the browser target.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to attach to the browser target, which will return a new session ID.
TYPE:
|
staticmethod
Generates a command to get information about a specific target.
This experimental method returns detailed information about a target, such as its type, URL, title, and other properties.
| PARAMETER | DESCRIPTION |
|---|---|
target_id
|
ID of the target to get information about.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to get target information, which will return a TargetInfo object with details about the target.
TYPE:
|
staticmethod
Generates a command to enable target discovery for specified remote locations.
This experimental method enables target discovery for remote locations when setDiscoverTargets was set to true. This is useful for discovering targets on remote devices or in different browser instances.
| PARAMETER | DESCRIPTION |
|---|---|
locations
|
list of remote locations, each containing a host and port.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set remote locations for target discovery.
TYPE:
|
Storage Commands
A class for interacting with browser storage using Chrome DevTools Protocol (CDP).
The Storage domain of CDP allows managing various types of browser storage, including: - Cookies - Cache Storage - IndexedDB - Web Storage (localStorage/sessionStorage) - Shared Storage - Storage Buckets - Trust Tokens - Interest Groups - Attribution Reporting
This class provides static methods that generate CDP commands to manage these types of storage without the need for traditional webdrivers.
staticmethod
Generates a command to clear all browser cookies.
| PARAMETER | DESCRIPTION |
|---|---|
browser_context_id
|
Browser context ID (optional). Useful when working with multiple contexts (e.g., multiple windows or tabs).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to clear all cookies.
TYPE:
|
staticmethod
Generates a command to clear storage data for a specific origin.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The security origin (e.g., "https://example.com").
TYPE:
|
storage_types
|
Comma-separated list of storage types to clear. Possible values include: "cookies", "local_storage", "indexeddb", "cache_storage", etc. Use "all" to clear all types.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to clear data for the specified origin.
TYPE:
|
staticmethod
Generates a command to clear data for a specific storage key.
| PARAMETER | DESCRIPTION |
|---|---|
storage_key
|
The storage key for which to clear data. Unlike origin, a storage key is a more specific identifier that may include partition isolation.
TYPE:
|
storage_types
|
Comma-separated list of storage types to clear. Possible values include: "cookies", "local_storage", "indexeddb", "cache_storage", etc. Use "all" to clear all types.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to clear data for the specified storage key.
TYPE:
|
staticmethod
Generates a command to get all browser cookies.
| PARAMETER | DESCRIPTION |
|---|---|
browser_context_id
|
Browser context ID (optional). Useful when working with multiple contexts (e.g., multiple windows or tabs).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to get all cookies, which will return an array of Cookie objects.
TYPE:
|
staticmethod
Generates a command to get the storage key for a specific frame.
Storage keys are used to isolate data between different origins or partitions in the browser.
| PARAMETER | DESCRIPTION |
|---|---|
frame_id
|
The ID of the frame for which to get the storage key.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to get the storage key for the specified frame.
TYPE:
|
staticmethod
Generates a command to get storage usage and quota information for an origin.
Useful for monitoring or debugging storage consumption of a site.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The security origin (e.g., "https://example.com") for which to get information.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command that will return: - usage: Storage usage in bytes - quota: Storage quota in bytes - usageBreakdown: Breakdown of usage by storage type - overrideActive: Whether there is an active quota override
TYPE:
|
staticmethod
Generates a command to set browser cookies.
| PARAMETER | DESCRIPTION |
|---|---|
cookies
|
list of Cookie objects to set.
TYPE:
|
browser_context_id
|
Browser context ID (optional). Useful when working with multiple contexts (e.g., multiple windows or tabs).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set the specified cookies.
TYPE:
|
staticmethod
Generates a command to set K-anonymity for protected audience.
This command is used to configure anonymity in privacy-preserving advertising systems (part of Google's Privacy Sandbox).
| PARAMETER | DESCRIPTION |
|---|---|
owner
|
Owner of the K-anonymity configuration.
TYPE:
|
name
|
Name of the K-anonymity configuration.
TYPE:
|
hashes
|
list of hashes for the configuration.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set protected audience K-anonymity.
TYPE:
|
staticmethod
Generates a command to register an origin to receive notifications about changes to its Cache Storage.
Cache Storage is primarily used by Service Workers to store resources for offline use.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The security origin (e.g., "https://example.com") to monitor.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to register monitoring of the origin's Cache Storage.
TYPE:
|
staticmethod
Generates a command to register a storage key to receive notifications about changes to its Cache Storage.
Similar to track_cache_storage_for_origin, but uses the storage key for more precise isolation.
| PARAMETER | DESCRIPTION |
|---|---|
storage_key
|
The storage key to monitor.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to register monitoring of the key's Cache Storage.
TYPE:
|
staticmethod
Generates a command to register an origin to receive notifications about changes to its IndexedDB.
IndexedDB is a NoSQL database system in the browser for storing large amounts of structured data.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The security origin (e.g., "https://example.com") to monitor.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to register monitoring of the origin's IndexedDB.
TYPE:
|
staticmethod
Generates a command to register a storage key to receive notifications about changes to its IndexedDB.
Similar to track_indexed_db_for_origin, but uses the storage key for more precise isolation.
| PARAMETER | DESCRIPTION |
|---|---|
storage_key
|
The storage key to monitor.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to register monitoring of the key's IndexedDB.
TYPE:
|
staticmethod
Generates a command to unregister an origin from receiving notifications about changes to its Cache Storage.
Use this method to stop monitoring Cache Storage after using track_cache_storage_for_origin.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The security origin (e.g., "https://example.com") to stop monitoring.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to cancel monitoring of the origin's Cache Storage.
TYPE:
|
staticmethod
Generates a command to unregister a storage key from receiving notifications about changes to its Cache Storage.
Use this method to stop monitoring Cache Storage after using track_cache_storage_for_storage_key.
| PARAMETER | DESCRIPTION |
|---|---|
storage_key
|
The storage key to stop monitoring.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to cancel monitoring of the key's Cache Storage.
TYPE:
|
staticmethod
Generates a command to unregister an origin from receiving notifications about changes to its IndexedDB.
Use this method to stop monitoring IndexedDB after using track_indexed_db_for_origin.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The security origin (e.g., "https://example.com") to stop monitoring.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to cancel monitoring of the origin's IndexedDB.
TYPE:
|
staticmethod
Generates a command to unregister a storage key from receiving notifications about changes to its IndexedDB.
Use this method to stop monitoring IndexedDB after using track_indexed_db_for_storage_key.
| PARAMETER | DESCRIPTION |
|---|---|
storage_key
|
The storage key to stop monitoring.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to cancel monitoring of the key's IndexedDB.
TYPE:
|
staticmethod
Generates a command to clear all Shared Storage entries for a specific origin.
Shared Storage is an experimental API that allows cross-origin shared storage with privacy protections.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the Shared Storage to clear.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to clear the Shared Storage entries.
TYPE:
|
staticmethod
Generates a command to remove all Trust Tokens issued by the specified origin.
Trust Tokens are an experimental API for combating fraud while preserving user privacy. This command keeps other stored data, including the issuer's redemption records, intact.
| PARAMETER | DESCRIPTION |
|---|---|
issuer_origin
|
The issuer origin of the tokens to remove.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to clear Trust Tokens, which will return: - didDeleteTokens: True if any tokens were deleted, False otherwise.
TYPE:
|
staticmethod
Generates a command to delete a specific Shared Storage entry.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the Shared Storage.
TYPE:
|
key
|
The key of the entry to delete.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to delete the Shared Storage entry.
TYPE:
|
staticmethod
Generates a command to delete a Storage Bucket with the specified key and name.
Storage Buckets are an experimental API for managing storage data with greater granularity and expiration control.
| PARAMETER | DESCRIPTION |
|---|---|
bucket
|
A StorageBucket object containing the storageKey and name of the bucket to delete.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to delete the Storage Bucket.
TYPE:
|
staticmethod
Generates a command to get the list of URLs from a page and its embedded resources that match existing grace period URL pattern rules.
This command is useful for monitoring which URLs would be affected by the Privacy Sandbox's third-party cookie policies.
| PARAMETER | DESCRIPTION |
|---|---|
first_party_url
|
The URL of the page being visited (first-party).
TYPE:
|
third_party_urls
|
Optional list of embedded third-party resource URLs.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to get URLs affected by third-party cookie metadata.
TYPE:
|
staticmethod
Generates a command to get details of a specific interest group.
Interest Groups are part of the FLEDGE/Protected Audience API for privacy-preserving advertising, enabling in-browser ad auctions.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the interest group.
TYPE:
|
name
|
The name of the interest group.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to get interest group details.
TYPE:
|
staticmethod
Generates a command to get related website sets.
Related Website Sets are an API that allows sites under the same entity to share some data, despite third-party cookie restrictions.
| PARAMETER | DESCRIPTION |
|---|---|
sets
|
list of RelatedWebsiteSet objects.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to get related website sets.
TYPE:
|
staticmethod
Generates a command to get all Shared Storage entries for an origin.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the Shared Storage.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to get the Shared Storage entries.
TYPE:
|
staticmethod
Generates a command to get Shared Storage metadata for an origin.
Metadata includes information such as usage, budget, and creation time.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the Shared Storage.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to get Shared Storage metadata.
TYPE:
|
staticmethod
Generates a command to get all available Trust Tokens.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to get Trust Tokens, which will return pairs of issuer origin and count of available tokens.
TYPE:
|
staticmethod
Generates a command to override the storage quota for a specific origin.
This command is useful for storage exhaustion testing or simulating different storage conditions.
| PARAMETER | DESCRIPTION |
|---|---|
origin
|
The origin for which to override the quota.
TYPE:
|
quota_size
|
The size of the new quota in bytes (optional). If not specified, any existing override will be removed.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to override the origin's quota.
TYPE:
|
staticmethod
Generates a command to reset the Shared Storage budget for an origin.
Shared Storage uses a budget system to limit the amount of operations or specific operations to preserve user privacy.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the Shared Storage.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to reset the Shared Storage budget.
TYPE:
|
staticmethod
Generates a command to run bounce tracking mitigations.
Bounce tracking is a tracking technique that involves redirecting users through intermediate URLs to establish tracking cookies. This command activates protections against this technique.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to run bounce tracking mitigations.
TYPE:
|
staticmethod
Generates a command to send pending attribution reports.
Attribution Reporting is an API that allows measuring conversions while preserving user privacy. This command forces sending reports that are waiting to be sent.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to send pending attribution reports.
TYPE:
|
staticmethod
Generates a command to enable or disable local testing mode for Attribution Reporting.
Testing mode makes it easier to develop and test the Attribution Reporting API by removing restrictions like delays and rate limits that would normally apply.
| PARAMETER | DESCRIPTION |
|---|---|
enable
|
True to enable local testing mode, False to disable it.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set Attribution Reporting local testing mode.
TYPE:
|
staticmethod
Generates a command to enable or disable Attribution Reporting tracking.
| PARAMETER | DESCRIPTION |
|---|---|
enable
|
True to enable tracking, False to disable it.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set Attribution Reporting tracking.
TYPE:
|
staticmethod
Generates a command to enable or disable interest group auction tracking.
Interest group auctions are part of the FLEDGE/Protected Audience API and allow for in-browser ad auctions in a privacy-preserving way.
| PARAMETER | DESCRIPTION |
|---|---|
enable
|
True to enable tracking, False to disable it.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set interest group auction tracking.
TYPE:
|
staticmethod
Generates a command to enable or disable interest group tracking.
| PARAMETER | DESCRIPTION |
|---|---|
enable
|
True to enable tracking, False to disable it.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set interest group tracking.
TYPE:
|
staticmethod
Generates a command to set an entry in Shared Storage.
| PARAMETER | DESCRIPTION |
|---|---|
owner_origin
|
The owner origin of the Shared Storage.
TYPE:
|
key
|
The key of the entry to set.
TYPE:
|
value
|
The value of the entry to set.
TYPE:
|
ignore_if_present
|
If True, won't replace an existing entry with the same key.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set a Shared Storage entry.
TYPE:
|
staticmethod
Generates a command to enable or disable Shared Storage tracking.
When enabled, events related to Shared Storage usage will be emitted.
| PARAMETER | DESCRIPTION |
|---|---|
enable
|
True to enable tracking, False to disable it.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set Shared Storage tracking.
TYPE:
|
staticmethod
Generates a command to enable or disable Storage Bucket tracking.
When enabled, events related to changes in storage buckets will be emitted.
| PARAMETER | DESCRIPTION |
|---|---|
storage_key
|
The storage key for which to set tracking.
TYPE:
|
enable
|
True to enable tracking, False to disable it.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set Storage Bucket tracking.
TYPE:
|