browsingContext.captureScreenshot command

Syntax

/* With required parameters */
{
  "method": "browsingContext.captureScreenshot",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f"
  }
}

/* With required and optional parameters */
{
  "method": "browsingContext.captureScreenshot",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "origin": "document",
    "format": {
      "type": "image/jpeg",
      "quality": 0.8
    },
    "clip": {
      "type": "box",
      "x": 10,
      "y": 10,
      "width": 200,
      "height": 100
    }
  }
}

Parameters

The params field contains:

clip Optional

An object that limits the capture to a rectangular area or to a single element. If clip is not specified, the entire origin area is captured. It contains the following fields:

type

A string that specifies whether the screenshot area is a rectangular region or a specific element. It can take one of the following values:

"box"

Captures a rectangular region. The area is specified using coordinates that are offsets from the top-left corner of origin. The clip object has the following fields for type: "box":

height

A number that specifies the height of the rectangle.

width

A number that specifies the width of the rectangle.

x

A number that specifies the horizontal offset of the rectangle from the top-left corner of origin.

y

A number that specifies the vertical offset of the rectangle from the top-left corner of origin.

"element"

Captures the bounding box of a specific element. The clip object also has the following field for type: "element":

element

An object containing the ID that uniquely identifies the DOM element to capture. The ID is returned by the browser when you locate the element using browsingContext.locateNodes, script.evaluate, or script.callFunction.

context

A string that contains the ID of the context to capture as a screenshot. Context IDs are returned by commands such as browsingContext.getTree.

format Optional

An object that specifies the image encoding to use. If not specified, the screenshot is encoded as "image/png". It contains the following fields:

quality Optional

A number between 0.0 and 1.0 that specifies the compression quality to use for lossy formats such as "image/jpeg". If not specified, the compression level used is browser-dependent.

type

A string that contains the image MIME type to encode the screenshot as, for example "image/png" or "image/jpeg".

origin Optional

A string that specifies the area for the screenshot. It can take one of the following values:

• "document": The area spans the entire scrollable document, including content outside the visible viewport.
• "viewport": The area is the visible viewport. This is the default.

Return value

The result object in the response contains the following fields:

data

A string that contains the Base64-encoded image data.

Errors

invalid argument

A required parameter is missing or has an invalid type.

no such element

The DOM element referenced by clip.element cannot be resolved or does not belong to the document of the context being captured.

no such frame

No context with the given context ID is found.

unable to capture screen

The requested clip region, after being intersected with the origin area, has zero width or height.

unsupported operation

The browser cannot capture a screenshot of the context.

Examples

Capturing an image of the visible viewport

With a WebDriver BiDi connection and an active session, send the following message to capture the current viewport as a PNG:

{
  "id": 1,
  "method": "browsingContext.captureScreenshot",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f"
  }
}

The browser responds with the Base64-encoded image data as follows:

{
  "id": 1,
  "type": "success",
  "result": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASU..."
  }
}

Capturing an image of the entire document as a JPEG

Using the same connection and session, send the following message to capture the full scrollable page as a compressed JPEG, including content outside the viewport:

{
  "id": 2,
  "method": "browsingContext.captureScreenshot",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "origin": "document",
    "format": {
      "type": "image/jpeg",
      "quality": 0.8
    }
  }
}

The browser responds with the Base64-encoded JPEG data as follows:

{
  "id": 2,
  "type": "success",
  "result": {
    "data": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAMDAwMDAwMDAwMEBAMEBQYFBQUFBgcGBgYGBwgICQkJCQgIC..."
  }
}

Capturing an image of a specific element

Using the same connection and session, suppose browsingContext.locateNodes returns a node with a shared ID.

With origin set to "document", send the following message to capture only that element's bounding box, even if it is currently scrolled out of view:

{
  "id": 3,
  "method": "browsingContext.captureScreenshot",
  "params": {
    "context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
    "origin": "document",
    "clip": {
      "type": "element",
      "element": {
        "sharedId": "f8f6a1f2-3d8a-4b8e-9f1a-6f6a2f6a2f6a"
      }
    }
  }
}

The browser responds with the Base64-encoded image data as follows:

{
  "id": 3,
  "type": "success",
  "result": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAQAAAAnOwc2AAAAEUlEQVR42mNk+M8ABYxAxAgAAcM..."
  }
}

Specifications

Browser compatibility

See also

• browsingContext.getTree command
• browsingContext.locateNodes command
• browsingContext.print command