{
  "doc": {
    "id": "api/node-events/after-screenshot-api",
    "title": "After Screenshot Event | Cypress Node Events",
    "description": "The after:screenshot event fires after a screenshot is taken in Cypress.",
    "section": "api",
    "source_path": "/llm/markdown/api/node-events/after-screenshot-api.md",
    "version": "e6988a974973e9090ce70406c38cb2b9e0eac9fa",
    "updated_at": "2026-05-15T15:50:22.536Z",
    "headings": [
      {
        "id": "api/node-events/after-screenshot-api#after-screenshot-event",
        "text": "After Screenshot Event",
        "level": 1
      },
      {
        "id": "api/node-events/after-screenshot-api#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/node-events/after-screenshot-api#usage",
        "text": "Usage",
        "level": 2
      },
      {
        "id": "api/node-events/after-screenshot-api#modify-screenshot-details",
        "text": "Modify screenshot details",
        "level": 3
      },
      {
        "id": "api/node-events/after-screenshot-api#modify-screenshot-path",
        "text": "Modify screenshot path",
        "level": 4
      },
      {
        "id": "api/node-events/after-screenshot-api#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "After Screenshot Event"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "After a screenshot is taken, you can get details about the screenshot via the `after:screenshot` node event. This event is called when a screenshot is taken with "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/commands/screenshot.md",
            "children": [
              {
                "type": "text",
                "value": "`cy.screenshot()`"
              }
            ]
          },
          {
            "type": "text",
            "value": " or as a result of a test failure. The event is called after the screenshot image is written to disk."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "This allows you to record those details, manipulate the image as needed, and return the updated details about the image."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Syntax"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "⚠️ This code is part of the "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/plugins/plugins-guide.md#Using-a-plugin",
            "children": [
              {
                "type": "text",
                "value": "setupNodeEvents"
              }
            ]
          },
          {
            "type": "text",
            "value": " function and thus executes in the Node environment. You cannot call `Cypress` or `cy` commands in this function, but you do have the direct access to the file system and the rest of the operating system."
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "cypress.config.js"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "cypress.config.ts"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const { defineConfig } = require('cypress')module.exports = defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      on('after:screenshot', (details) => {        /* ... */      })    },  },})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'export default defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      on('after:screenshot', (details) => {        /* ... */      })    },  },})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "details (object)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "An object describing the screenshot that was taken, with the following properties:"
          }
        ]
      },
      {
        "type": "table",
        "align": [
          null,
          null,
          null
        ],
        "children": [
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Property"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Type"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Description"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`size`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`number`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "The size of the image file (in bytes)."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`takenAt`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`string`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "The date and time the screenshot was taken. ISO 8601 format in UTC (example: `'2020-03-09T07:30:37.686Z'`)"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`duration`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`number`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Duration taking and saving the screenshot (in milliseconds)."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`dimensions`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`object`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "The width and height of the image in pixels (example: `{ width: 100, height: 50 }`)"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`multipart`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`boolean`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Whether the screenshot was stitched together from multiple screenshot images."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`pixelRatio`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`number`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "(Optional) The ratio of screenshot pixels to the browser's displayed pixels."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`name`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`string`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "(Optional) The `fileName` argument passed in via "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/screenshot.md#Arguments",
                    "children": [
                      {
                        "type": "text",
                        "value": "cy.screenshot()"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`specName`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`string`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "The name of the specfile where the screenshot was taken."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`path`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`string`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "The absolute path to the image."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`scaled`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`boolean`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Whether the application under test was scaled to fit into the browser viewport. May be `scale` argument passed in via "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/screenshot.md#Arguments",
                    "children": [
                      {
                        "type": "text",
                        "value": "cy.screenshot()"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`blackout`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`array`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "The `blackout` argument passed in via "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/screenshot.md#Arguments",
                    "children": [
                      {
                        "type": "text",
                        "value": "cy.screenshot()"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Usage"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Modify screenshot details"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Using "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/plugins/plugins-guide.md#Using-a-plugin",
            "children": [
              {
                "type": "text",
                "value": "setupNodeEvents"
              }
            ]
          },
          {
            "type": "text",
            "value": " you can tap into the `after:screenshot` event."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If you change the `path`, `size` or `dimensions` of the image, you'll want to update the new values so that the details are correctly reported in the test results. Any other properties besides `path`, `size`, and `dimensions` will be ignored."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can return an object or a promise that resolves to an object from the callback function. Any type of returned value other than an object will be ignored. The object can contain the following properties:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "path: The absolute path to the current location of the image"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "size: The size of the current image file (in bytes)"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "dimensions: The width and height of the current image in pixels (as an object with the shape `{ width: 100, height: 50 }`)"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The properties will be merged into the screenshot details and passed to the `onAfterScreenshot` callback (if defined with "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/cypress-api/screenshot-api.md",
            "children": [
              {
                "type": "text",
                "value": "Cypress.Screenshot.defaults()"
              }
            ]
          },
          {
            "type": "text",
            "value": " and/or "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/commands/screenshot.md",
            "children": [
              {
                "type": "text",
                "value": "cy.screenshot()"
              }
            ]
          },
          {
            "type": "text",
            "value": ")."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Modify screenshot path"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If you move the location of the screenshot image, you'll want to specify the new `path` of the image."
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "cypress.config.js"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "cypress.config.ts"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const { defineConfig } = require('cypress')const fs = require('fs')module.exports = defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      on('after:screenshot', (details) => {        console.log(details) // print all details to terminal        const newPath = '/new/path/to/screenshot.png'        return new Promise((resolve, reject) => {          // fs.rename moves the file to the existing directory 'new/path/to'          // and renames the image to 'screenshot.png'          fs.rename(details.path, newPath, (err) => {            if (err) return reject(err)            // because we renamed and moved the image, resolve with the new path            // so it is accurate in the test results            resolve({ path: newPath })          })        })      })    },  },})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "import { defineConfig } from 'cypress'import fs from 'fs'export default defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      on('after:screenshot', (details) => {        console.log(details) // print all details to terminal        const newPath = '/new/path/to/screenshot.png'        return new Promise((resolve, reject) => {          // fs.rename moves the file to the existing directory 'new/path/to'          // and renames the image to 'screenshot.png'          fs.rename(details.path, newPath, (err) => {            if (err) return reject(err)            // because we renamed and moved the image, resolve with the new path            // so it is accurate in the test results            resolve({ path: newPath })          })        })      })    },  },})"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "See also"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/screenshot.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "cy.screenshot()"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/get-started/introduction.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Cypress Cloud"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/guides/screenshots-and-videos.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Screenshots and Videos"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/tooling/visual-testing.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Visual Testing"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/plugins/plugins-guide.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "How to use Plugins"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/node-events/overview.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Node Events Overview"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 1120
}