Debugging

There might be situations where your screenshots are failing and the error messages returned by the API are not enough.

The screenshot API allows you to visually debug at different steps by capturing snapshots of the page. For the full list of accepted fields, see the Screenshot API reference, and review Best practices for guidance on reliable page-load waiting.

Enabling Debugging

Set the stepImages attribute to either onError or all to enable capturing snapshots.

Value	Description
onError	Capture snapshots only when screenshot capture fails.
all	Capture snapshots regardless if screenshot capture is successful or fails.

When the stepImages is not explicitly specified, no snapshots are captured.

Example 1 : Capturing snapshots when a step fails

Request:

POST /screenshot

{
  "stepImages": "all",
  "elementSelector": [
    "body"
  ],
  "steps": [
    {
      "type": "navigate",
      "url": "https://example.org"
    },
    {
      "selectors": [
        "#fake"
      ],
      "timeout": 10000,
      "type": "waitForElement"
    }
  ]
}

Response:

{
    "summary": {
        "total": 1,
        "success": 0,
        "pending": 0,
        "failed": 1
    },
    "screenshots": [
        {
            "id": "a94b479b-25ef-4dbb-99b6-9b8e0dcbd944",
            "jobId": "ba43120b-81d3-4f22-86f5-2cb33ce2f952",
            "status": "failed",
            "message": "The following selector(s) were either not found or timed out for step: 'waitForElement', selectors: #fake",
            "error": {
                "message": "The following selector(s) were either not found or timed out for step: 'waitForElement', selectors: #fake",
                "type": "ElementNotFound",
                "meta": {
                    "type": "waitForElement",
                    "selectors": [
                        "#fake"
                    ]
                }
            },
            "createdAt": "2025-01-11T01:24:34.484Z",
            "updatedAt": "2025-01-11T01:24:46.722Z",
            "retryCount": 1,
            "raw": {
                "filesize": null,
                "url": null,
                "hash": null
            },
            "styled": {
                "filesize": null,
                "url": null,
                "hash": null
            },
            "snapshots": {
                "steps": [
                    {
                        "description": "navigate",
                        "type": "navigate",
                        "data": "https://launchbrightlyf9ff5e67329842e1a3a8fc00d5a7569c145137-prod.s3.us-east-1.amazonaws.com/debug/2025-01-11/19659a5be63d54d93b09c0246b7b0b6974f15659eea11105f7972309db6e2ea7_navigate.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIASH5PNXSCN5O7E7U2%2F20250111%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250111T012447Z&X-Amz-Expires=86400&X-Amz-Signature=7d5d5f1fe4733db87c1b321dba6bfcc0896353e4a6dd6e732d1e26f5a1c53edf&X-Amz-SignedHeaders=host&x-id=GetObject",
                        "url": "https://example.org/"
                    },
                    {
                        "description": "waitForElement",
                        "type": "waitForElement",
                        "selectors": [
                            "#fake"
                        ],
                        "data": "https://launchbrightlyf9ff5e67329842e1a3a8fc00d5a7569c145137-prod.s3.us-east-1.amazonaws.com/debug/2025-01-11/19659a5be63d54d93b09c0246b7b0b6974f15659eea11105f7972309db6e2ea7_waitForElement.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIASH5PNXSCN5O7E7U2%2F20250111%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250111T012447Z&X-Amz-Expires=86400&X-Amz-Signature=d9740db8d9b627ecbf66c5b61f7d68e5cd8c19079c3c8bca0b84e97d29be3f73&X-Amz-SignedHeaders=host&x-id=GetObject",
                        "message": "The following selector(s) were either not found or timed out for step: 'waitForElement', selectors: #fake",
                        "url": "https://example.org/"
                    }
                ]
            }
        }
    ]
}

Example 2 : Capturing snapshots when an annotation fails

Request:

POST /screenshot

{
  "stepImages": "onError",
  "deviceScaleFactor": 1,
  "elementSelector": [
    "body"
  ],
  "steps": [
    {
      "type": "navigate",
      "url": "https://example.org"
    },
    {
      "value": 3000,
      "type": "waitFor"
    }
  ],
  "annotate": [
    {
      "type": "modifyText",
      "selectors": [
        ".fake",
        "xpath/html/body/div/fake"
      ],
      "value": "Hello World!!"
    }
  ]
}

Response:

{
    "summary": {
        "total": 1,
        "success": 0,
        "pending": 0,
        "failed": 1
    },
    "screenshots": [
        {
            "id": "fd270d32-209b-4ebc-a67d-6abc1c12d073",
            "jobId": "adffdaa0-adf3-4713-a4c1-5fb19d95408e",
            "status": "failed",
            "message": "The following selector(s) were either not found or timed out for annotate: 'modifyText', selectors: .fake,xpath/html/body/div/fake",
            "error": {
                "message": "The following selector(s) were either not found or timed out for annotate: 'modifyText', selectors: .fake,xpath/html/body/div/fake",
                "type": "ElementNotFound",
                "meta": {
                    "type": "modifyText",
                    "selectors": [
                        ".fake",
                        "xpath/html/body/div/fake"
                    ]
                }
            },
            "createdAt": "2025-01-11T01:25:44.685Z",
            "updatedAt": "2025-01-11T01:25:49.044Z",
            "retryCount": 1,
            "raw": {
                "filesize": null,
                "url": null,
                "hash": null
            },
            "styled": {
                "filesize": null,
                "url": null,
                "hash": null
            },
            "snapshots": {
                "steps": [
                    {
                        "description": "navigate",
                        "type": "navigate",
                        "data": "https://launchbrightlyf9ff5e67329842e1a3a8fc00d5a7569c145137-prod.s3.us-east-1.amazonaws.com/debug/2025-01-11/c05163e45e9f3a5c7305f19d3baf613ecfc5c917687b0ab835f90bbcfad4dd14_navigate.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIASH5PNXSCN5O7E7U2%2F20250111%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250111T012551Z&X-Amz-Expires=86400&X-Amz-Signature=e2471f7a32b2a690285d9605233a67da07ae72f199d4dd812e04fe71653124e5&X-Amz-SignedHeaders=host&x-id=GetObject",
                        "url": "https://example.org/"
                    },
                    {
                        "description": "waitForExpression",
                        "type": "waitFor",
                        "data": "https://launchbrightlyf9ff5e67329842e1a3a8fc00d5a7569c145137-prod.s3.us-east-1.amazonaws.com/debug/2025-01-11/c05163e45e9f3a5c7305f19d3baf613ecfc5c917687b0ab835f90bbcfad4dd14_waitFor.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIASH5PNXSCN5O7E7U2%2F20250111%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250111T012551Z&X-Amz-Expires=86400&X-Amz-Signature=7c76ed53e14325ec12480e068cb0e92c0f9ea1dbca3f7af0aec821f628d32304&X-Amz-SignedHeaders=host&x-id=GetObject",
                        "url": "https://example.org/"
                    }
                ],
                "annotate": [
                    {
                        "description": "modifyText",
                        "type": "modifyText",
                        "selectors": [
                            ".fake",
                            "xpath/html/body/div/fake"
                        ],
                        "data": "https://launchbrightlyf9ff5e67329842e1a3a8fc00d5a7569c145137-prod.s3.us-east-1.amazonaws.com/debug/2025-01-11/c05163e45e9f3a5c7305f19d3baf613ecfc5c917687b0ab835f90bbcfad4dd14_modifyText.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIASH5PNXSCN5O7E7U2%2F20250111%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250111T012551Z&X-Amz-Expires=86400&X-Amz-Signature=43d72f695d6f0bf497790a98c9f46166485b44a07fe9b5949622337d3ad5373c&X-Amz-SignedHeaders=host&x-id=GetObject",
                        "message": "The following selector(s) were either not found or timed out for annotate: 'modifyText', selectors: .fake,xpath/html/body/div/fake",
                        "url": "https://example.org/"
                    }
                ]
            }
        }
    ]
}