{ "doc": { "id": "api/cypress-api/screenshot-api", "title": "Cypress.Screenshot | Cypress Documentation", "description": "Set defaults for how screenshots are captured during .screenshot(` and automatic screenshots taken during test failures in Cypress", "section": "api", "source_path": "/llm/markdown/api/cypress-api/screenshot-api.md", "version": "ce02913654e2655ee63448bdc92bb92c7b46a619", "updated_at": "2026-04-22T19:37:51.587Z", "headings": [ { "id": "api/cypress-api/screenshot-api#cypress-screenshot", "text": "Cypress.Screenshot", "level": 1 }, { "id": "api/cypress-api/screenshot-api#syntax", "text": "Syntax", "level": 2 }, { "id": "api/cypress-api/screenshot-api#arguments", "text": "Arguments", "level": 3 }, { "id": "api/cypress-api/screenshot-api#examples", "text": "Examples", "level": 2 }, { "id": "api/cypress-api/screenshot-api#blackout-elements-before-screenshot", "text": "Blackout elements before screenshot", "level": 3 }, { "id": "api/cypress-api/screenshot-api#take-a-screenshot-of-the-entire-cypress-browser-window", "text": "Take a screenshot of the entire Cypress browser window", "level": 3 }, { "id": "api/cypress-api/screenshot-api#allow-timers-and-animations-to-keep-running", "text": "Allow timers and animations to keep running", "level": 3 }, { "id": "api/cypress-api/screenshot-api#disable-screenshots-on-run-failures", "text": "Disable screenshots on run failures", "level": 3 }, { "id": "api/cypress-api/screenshot-api#overwrite-existing-screenshots", "text": "Overwrite existing screenshots", "level": 3 }, { "id": "api/cypress-api/screenshot-api#scale-viewport-and-fullpage-captures", "text": "Scale viewport and fullPage captures", "level": 3 }, { "id": "api/cypress-api/screenshot-api#change-the-dom-using-onbeforescreenshot-and-onafterscreenshot", "text": "Change the DOM using onBeforeScreenshot and onAfterScreenshot", "level": 3 }, { "id": "api/cypress-api/screenshot-api#get-properties-from-the-onafterscreenshot-callback", "text": "Get properties from the onAfterScreenshot callback", "level": 3 }, { "id": "api/cypress-api/screenshot-api#notes", "text": "Notes", "level": 2 }, { "id": "api/cypress-api/screenshot-api#where-to-put-screenshot-configuration", "text": "Where to put screenshot configuration", "level": 3 }, { "id": "api/cypress-api/screenshot-api#history", "text": "History", "level": 2 }, { "id": "api/cypress-api/screenshot-api#see-also", "text": "See also", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Cypress.Screenshot" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The Screenshot API allows you set defaults for how screenshots are captured\nduring " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/screenshot.md", "children": [ { "type": "text", "value": ".screenshot" } ] }, { "type": "text", "value": " and automatic screenshots taken\nduring test failures. You can set defaults for the following:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Which parts of the screen to capture." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Whether to scale your application under test in the screenshot." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Whether to disable JavaScript timers and CSS animations when taking the\nscreenshot." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Whether to automatically take screenshots when there are run failures." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Which, if any, elements to black out when taking the screenshot." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Whether to wait for the Command Log to synchronize before taking the\nscreenshot." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Syntax" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "Cypress.Screenshot.defaults(options)" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Arguments" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "options (Object)" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "An object containing one or more of the following:" } ] }, { "type": "table", "align": [ null, null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Option" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Default" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Description" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`blackout`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`[]`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Array of string selectors used to match elements that should be blacked out when the screenshot is taken. Does not apply to `runner` captures." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`capture`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`'fullPage'`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Which parts of the Cypress Test Runner to capture. This value is ignored for element screenshot captures. Valid values are `viewport`, `fullPage`, or `runner`. When `viewport`, your application under test is captured in the current viewport. When `fullPage`, your application under test is captured in its entirety from top to bottom. When `runner`, the entire browser viewport, including the Cypress Command Log, is captured. For screenshots automatically taken on test failure, capture is always coerced to `runner`. When " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/test-replay.md", "children": [ { "type": "text", "value": "Test Replay" } ] }, { "type": "text", "value": " is enabled and the Runner UI is hidden, a `runner` screenshot will not include the Runner UI and will instead capture the application under test only in the current viewport." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`disableTimersAndAnimations`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`true`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "When true, prevents JavaScript timers (`setTimeout`, `setInterval`, etc) and CSS animations from running while the screenshot is taken." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`scale`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`false`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Whether to scale the app to fit into the browser viewport. This is always coerced to `true` for `runner` captures." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`screenshotOnRunFailure`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`true`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "When true, automatically takes a screenshot when there is a failure during `cypress run`." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`overwrite`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`false`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Whether to overwrite duplicate screenshot files with the same file name when saving." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`onBeforeScreenshot`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`null`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "A callback before a (non-failure) screenshot is taken. For an element capture, the argument is the element being captured. For other screenshots, the argument is the `$el`." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`onAfterScreenshot`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`null`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "A callback after a (non-failure) screenshot is taken. For an element capture, the first argument is the element being captured. For other screenshots, the first argument is the `$el`. The second argument is properties concerning the screenshot, including the path it was saved to and the dimensions of the saved screenshot." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Examples" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Blackout elements before screenshot" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Elements that match the specified selectors will be blacked out from the\nscreenshot, but only when the `capture` option is `viewport`. `blackout` is\nignored if `capture` option is `runner`." } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "Cypress.Screenshot.defaults({\n blackout: ['.secret-info', '[data-hide=true]'],\n})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Take a screenshot of the entire Cypress browser window" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "By default, " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/screenshot.md", "children": [ { "type": "text", "value": "`cy.screenshot()`" } ] }, { "type": "text", "value": " only captures your\napplication under test. You may want it to capture the entire Cypress browser\nfor debugging purposes." } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "Cypress.Screenshot.defaults({\n capture: 'runner',\n})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Allow timers and animations to keep running" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "By default, JavaScript timers and CSS animations are disabled to try to prevent\nchanges to your application under test while the screenshot is taken, but you\ncan turn off this behavior." } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "Cypress.Screenshot.defaults({\n disableTimersAndAnimations: false,\n})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Disable screenshots on run failures" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "By default, Cypress automatically takes a screenshot when there is a failure\nwhen running `cypress run`, but you can disable this." } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "Cypress.Screenshot.defaults({\n screenshotOnRunFailure: false,\n})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Overwrite existing screenshots" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "By default, Cypress saves unique screenshot files for every screenshot that is\ntaken within the same test. You can choose to overwrite existing screenshots\nwith the same file name using the `overwrite` option." } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "Cypress.Screenshot.defaults({\n overwrite: true,\n})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Scale viewport and fullPage captures" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "By default, scaling the application under test is turned off during when the\n`capture` option is `viewport` to prevent differences between screenshots on\nscreens with different resolutions. You can turn scaling on and have your app\nscaled like it is during normal use of Cypress. This is always coerced to `true`\nif the `capture` option is `runner`." } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "Cypress.Screenshot.defaults({\n scale: true,\n})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Change the DOM using onBeforeScreenshot and onAfterScreenshot" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `onBeforeScreenshot` and `onAfterScreenshot` callbacks provide an\nopportunity to synchronously change the DOM to create a more consistent state\nfor the screenshot." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "In this example, imagine there is a clock in your app showing the current time.\nThis can cause screenshots to be non-deterministic, which could create false\nnegatives when screenshot diffing. You can use `onBeforeScreenshot` to hide the\nclock and then show it again with `onAfterScreenshot`." } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "Cypress.Screenshot.defaults({\n onBeforeScreenshot($el) {\n const $clock = $el.find('.clock')\n\n if ($clock) {\n $clock.hide()\n }\n },\n\n onAfterScreenshot($el, props) {\n const $clock = $el.find('.clock')\n\n if ($clock) {\n $clock.show()\n }\n },\n})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Get properties from the onAfterScreenshot callback" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "Cypress.Screenshot.defaults({\n onAfterScreenshot($el, props) {\n // props has information about the screenshot,\n // including but not limited to the following:\n // {\n // path: '/Users/janelane/project/screenshots/my-screenshot.png',\n // size: '15 kb',\n // dimensions: {\n // width: 1000,\n // height: 660,\n // },\n // scaled: true,\n // blackout: ['.foo'],\n // duration: 2300,\n // }\n },\n})" }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Notes" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Where to put screenshot configuration" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A great place to put this configuration is in the\n" }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Support-file", "children": [ { "type": "text", "value": "supportFile" } ] }, { "type": "text", "value": ",\nsince it is loaded before any test files are evaluated." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "History" } ] }, { "type": "table", "align": [ null, null ], "children": [ { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "Version" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Changes" } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/app/references/changelog.md#8-7-0", "children": [ { "type": "text", "value": "8.7.0" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Added `overwrite` configuration option." } ] } ] } ] }, { "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" } ] } ] } ] } ] } ] }, "token_estimate": 1275 }