Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Browser

The Browser domain defines methods and events for browser managing.

- Types

- Commands

- Events

## Types

Generally, you do not need to instantiate CDP types yourself. Instead, the API creates objects for you as return values from commands, and then you can use those objects as arguments to other commands.

class BrowserContextID

class WindowID

class WindowState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  The state of the browser window.

  NORMAL = 'normal'
  MINIMIZED = 'minimized'
  MAXIMIZED = 'maximized'
  FULLSCREEN = 'fullscreen'

class Bounds(left=None, top=None, width=None, height=None, window_state=None)

  Browser window bounds information

  left: `Optional`[`int`] = None

    The offset from the left edge of the screen to the window in pixels.

  top: `Optional`[`int`] = None

    The offset from the top edge of the screen to the window in pixels.

  width: `Optional`[`int`] = None

    The window width in pixels.

  height: `Optional`[`int`] = None

    The window height in pixels.

  window_state: `Optional`[`WindowState`] = None

    The window state. Default to normal.

class PermissionType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
  AR = 'ar'
  AUDIO_CAPTURE = 'audioCapture'
  AUTOMATIC_FULLSCREEN = 'automaticFullscreen'
  BACKGROUND_FETCH = 'backgroundFetch'
  BACKGROUND_SYNC = 'backgroundSync'
  CAMERA_PAN_TILT_ZOOM = 'cameraPanTiltZoom'
  CAPTURED_SURFACE_CONTROL = 'capturedSurfaceControl'
  CLIPBOARD_READ_WRITE = 'clipboardReadWrite'
  CLIPBOARD_SANITIZED_WRITE = 'clipboardSanitizedWrite'
  DISPLAY_CAPTURE = 'displayCapture'
  DURABLE_STORAGE = 'durableStorage'
  GEOLOCATION = 'geolocation'
  HAND_TRACKING = 'handTracking'
  IDLE_DETECTION = 'idleDetection'
  KEYBOARD_LOCK = 'keyboardLock'
  LOCAL_FONTS = 'localFonts'
  LOCAL_NETWORK_ACCESS = 'localNetworkAccess'
  MIDI = 'midi'
  MIDI_SYSEX = 'midiSysex'
  NFC = 'nfc'
  NOTIFICATIONS = 'notifications'
  PAYMENT_HANDLER = 'paymentHandler'
  PERIODIC_BACKGROUND_SYNC = 'periodicBackgroundSync'
  POINTER_LOCK = 'pointerLock'
  PROTECTED_MEDIA_IDENTIFIER = 'protectedMediaIdentifier'
  SENSORS = 'sensors'
  SMART_CARD = 'smartCard'
  SPEAKER_SELECTION = 'speakerSelection'
  STORAGE_ACCESS = 'storageAccess'
  TOP_LEVEL_STORAGE_ACCESS = 'topLevelStorageAccess'
  VIDEO_CAPTURE = 'videoCapture'
  VR = 'vr'
  WAKE_LOCK_SCREEN = 'wakeLockScreen'
  WAKE_LOCK_SYSTEM = 'wakeLockSystem'
  WEB_APP_INSTALLATION = 'webAppInstallation'
  WEB_PRINTING = 'webPrinting'
  WINDOW_MANAGEMENT = 'windowManagement'

class PermissionSetting(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
  GRANTED = 'granted'
  DENIED = 'denied'
  PROMPT = 'prompt'

class PermissionDescriptor(name, sysex=None, user_visible_only=None, allow_without_sanitization=None, allow_without_gesture=None, pan_tilt_zoom=None)

  Definition of PermissionDescriptor defined in the Permissions API: https://w3c.github.io/permissions/#dom-permissiondescriptor.

  name: `str`

    Name of permission. See https://cs.chromium.org/chromium/src/third_party/blink/renderer/modules/permissions/permission_descriptor.idl for valid permission names.

  sysex: `Optional`[`bool`] = None

    For “midi” permission, may also specify sysex control.

  user_visible_only: `Optional`[`bool`] = None

    For “push” permission, may specify userVisibleOnly. Note that userVisibleOnly = true is the only currently supported type.

  allow_without_sanitization: `Optional`[`bool`] = None

    For “clipboard” permission, may specify allowWithoutSanitization.

  allow_without_gesture: `Optional`[`bool`] = None

    true.

    Type:

      For “fullscreen” permission, must specify allowWithoutGesture

  pan_tilt_zoom: `Optional`[`bool`] = None

    For “camera” permission, may specify panTiltZoom.

class BrowserCommandId(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  Browser command ids used by executeBrowserCommand.

  OPEN_TAB_SEARCH = 'openTabSearch'
  CLOSE_TAB_SEARCH = 'closeTabSearch'
  OPEN_GLIC = 'openGlic'

class Bucket(low, high, count)

  Chrome histogram bucket.

  low: `int`

    Minimum value (inclusive).

  high: `int`

    Maximum value (exclusive).

  count: `int`

    Number of samples.

class Histogram(name, sum_, count, buckets)

  Chrome histogram.

  name: `str`

    Name.

  sum_: `int`

    Sum of sample values.

  count: `int`

    Total number of samples.

  buckets: `List`[`Bucket`]

    Buckets.

class PrivacySandboxAPI(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
  BIDDING_AND_AUCTION_SERVICES = 'BiddingAndAuctionServices'
  TRUSTED_KEY_VALUE = 'TrustedKeyValue'

## Commands

Each command is a generator function. The return type `Generator[x, y, z]` indicates that the generator yields arguments of type `x`, it must be resumed with an argument of type `y`, and it returns type `z`. In this library, types `x` and `y` are the same for all commands, and `z` is the return type you should pay attention to. For more information, see Getting Started: Commands.

add_privacy_sandbox_coordinator_key_config(api, coordinator_origin, key_config, browser_context_id=None)

  Configures encryption keys used with a given privacy sandbox API to talk to a trusted coordinator. Since this is intended for test automation only, coordinatorOrigin must be a .test domain. No existing coordinator configuration for the origin may exist.

  Parameters:

    - api (`PrivacySandboxAPI`) –

    - coordinator_origin (`str`) –

    - key_config (`str`) –

    - browser_context_id (`Optional`[`BrowserContextID`]) – (Optional) BrowserContext to perform the action in. When omitted, default browser context is used.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

add_privacy_sandbox_enrollment_override(url)

  Allows a site to use privacy sandbox features that require enrollment without the site actually being enrolled. Only supported on page targets.

  Parameters:

    url (`str`) –

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

cancel_download(guid, browser_context_id=None)

  Cancel a download if in progress

  EXPERIMENTAL

  Parameters:

    - guid (`str`) – Global unique identifier of the download.

    - browser_context_id (`Optional`[`BrowserContextID`]) – (Optional) BrowserContext to perform the action in. When omitted, default browser context is used.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

close()

  Close browser gracefully.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

crash()

  Crashes browser on the main thread.

  EXPERIMENTAL

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

crash_gpu_process()

  Crashes GPU process.

  EXPERIMENTAL

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

execute_browser_command(command_id)

  Invoke custom browser commands used by telemetry.

  EXPERIMENTAL

  Parameters:

    command_id (`BrowserCommandId`) –

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

get_browser_command_line()

  Returns the command line switches for the browser process if, and only if –enable-automation is on the commandline.

  EXPERIMENTAL

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `List`[`str`]]

  Returns:

    Commandline parameters

get_histogram(name, delta=None)

  Get a Chrome histogram by name.

  EXPERIMENTAL

  Parameters:

    - name (`str`) – Requested histogram name.

    - delta (`Optional`[`bool`]) – (Optional) If true, retrieve delta since last delta call.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `Histogram`]

  Returns:

    Histogram.

get_histograms(query=None, delta=None)

  Get Chrome histograms.

  EXPERIMENTAL

  Parameters:

    - query (`Optional`[`str`]) – (Optional) Requested substring in name. Only histograms which have query as a substring in their name are extracted. An empty or absent query returns all histograms.

    - delta (`Optional`[`bool`]) – (Optional) If true, retrieve delta since last delta call.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `List`[`Histogram`]]

  Returns:

    Histograms.

get_version()

  Returns version information.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `Tuple`[`str`, `str`, `str`, `str`, `str`]]

  Returns:

    A tuple with the following items:

    0. protocolVersion - Protocol version.

    1. product - Product name.

    2. revision - Product revision.

    3. userAgent - User-Agent.

    4. jsVersion - V8 version.

get_window_bounds(window_id)

  Get position and size of the browser window.

  EXPERIMENTAL

  Parameters:

    window_id (`WindowID`) – Browser window id.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `Bounds`]

  Returns:

    Bounds information of the window. When window state is ‘minimized’, the restored window position and size are returned.

get_window_for_target(target_id=None)

  Get the browser window that contains the devtools target.

  EXPERIMENTAL

  Parameters:

    target_id (`Optional`[`TargetID`]) – (Optional) Devtools agent host id. If called as a part of the session, associated targetId is used.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `Tuple`[`WindowID`, `Bounds`]]

  Returns:

    A tuple with the following items:

    0. windowId - Browser window id.

    1. bounds - Bounds information of the window. When window state is ‘minimized’, the restored window position and size are returned.

grant_permissions(permissions, origin=None, browser_context_id=None)

  Grant specific permissions to the given origin and reject all others.

  EXPERIMENTAL

  Parameters:

    - permissions (`List`[`PermissionType`]) –

    - origin (`Optional`[`str`]) – (Optional) Origin the permission applies to, all origins if not specified.

    - browser_context_id (`Optional`[`BrowserContextID`]) – (Optional) BrowserContext to override permissions. When omitted, default browser context is used.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

reset_permissions(browser_context_id=None)

  Reset all permission management for all origins.

  Parameters:

    browser_context_id (`Optional`[`BrowserContextID`]) – (Optional) BrowserContext to reset permissions. When omitted, default browser context is used.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

set_contents_size(window_id, width=None, height=None)

  Set size of the browser contents resizing browser window as necessary.

  EXPERIMENTAL

  Parameters:

    - window_id (`WindowID`) – Browser window id.

    - width (`Optional`[`int`]) – (Optional) The window contents width in DIP. Assumes current width if omitted. Must be specified if ‘height’ is omitted.

    - height (`Optional`[`int`]) – (Optional) The window contents height in DIP. Assumes current height if omitted. Must be specified if ‘width’ is omitted.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

set_dock_tile(badge_label=None, image=None)

  Set dock tile details, platform-specific.

  EXPERIMENTAL

  Parameters:

    - badge_label (`Optional`[`str`]) – (Optional)

    - image (`Optional`[`str`]) – (Optional) Png encoded image. (Encoded as a base64 string when passed over JSON)

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

set_download_behavior(behavior, browser_context_id=None, download_path=None, events_enabled=None)

  Set the behavior when downloading a file.

  EXPERIMENTAL

  Parameters:

    - behavior (`str`) – Whether to allow all or deny all download requests, or use default Chrome behavior if available (otherwise deny). `allowAndName` allows download and names files according to their download guids.

    - browser_context_id (`Optional`[`BrowserContextID`]) – (Optional) BrowserContext to set download behavior. When omitted, default browser context is used.

    - download_path (`Optional`[`str`]) – (Optional) The default path to save downloaded files to. This is required if behavior is set to ‘allow’ or ‘allowAndName’.

    - events_enabled (`Optional`[`bool`]) – (Optional) Whether to emit download events (defaults to false).

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

set_permission(permission, setting, origin=None, embedding_origin=None, browser_context_id=None)

  Set permission settings for given requesting and embedding origins.

  EXPERIMENTAL

  Parameters:

    - permission (`PermissionDescriptor`) – Descriptor of permission to override.

    - setting (`PermissionSetting`) – Setting of the permission.

    - origin (`Optional`[`str`]) – (Optional) Requesting origin the permission applies to, all origins if not specified.

    - embedding_origin (`Optional`[`str`]) – (Optional) Embedding origin the permission applies to. It is ignored unless the requesting origin is present and valid. If the requesting origin is provided but the embedding origin isn’t, the requesting origin is used as the embedding origin.

    - browser_context_id (`Optional`[`BrowserContextID`]) – (Optional) Context to override. When omitted, default browser context is used.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

set_window_bounds(window_id, bounds)

  Set position and/or size of the browser window.

  EXPERIMENTAL

  Parameters:

    - window_id (`WindowID`) – Browser window id.

    - bounds (`Bounds`) – New window bounds. The ‘minimized’, ‘maximized’ and ‘fullscreen’ states cannot be combined with ‘left’, ‘top’, ‘width’ or ‘height’. Leaves unspecified fields unchanged.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

## Events

Generally, you do not need to instantiate CDP events yourself. Instead, the API creates events for you and then you use the event’s attributes.

class DownloadWillBegin(frame_id, guid, url, suggested_filename)

  EXPERIMENTAL

  Fired when page is about to start a download.

  frame_id: `FrameId`

    Id of the frame that caused the download to begin.

  guid: `str`

    Global unique identifier of the download.

  url: `str`

    URL of the resource being downloaded.

  suggested_filename: `str`

    Suggested file name of the resource (the actual name of the file saved on disk may differ).

class DownloadProgress(guid, total_bytes, received_bytes, state, file_path)

  EXPERIMENTAL

  Fired when download makes progress. Last call has `done` == true.

  guid: `str`

    Global unique identifier of the download.

  total_bytes: `float`

    Total expected bytes to download.

  received_bytes: `float`

    Total bytes received.

  state: `str`

    Download status.

  file_path: `Optional`[`str`]

    If download is “completed”, provides the path of the downloaded file. Depending on the platform, it is not guaranteed to be set, nor the file is guaranteed to exist.