# 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](https://docs.launchbrightly.com/product-screenshots-api/execute-actions#steps-reference) by capturing snapshots of the page. For the full list of accepted fields, see the [Screenshot API reference](https://docs.launchbrightly.com/product-screenshots-api/options), and review [Best practices](https://docs.launchbrightly.com/product-screenshots-api/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`

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

### Response:

```json
{
    "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`

```json
{
  "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:

```json
{
    "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/"
                    }
                ]
            }
        }
    ]
}
```