{ "doc": { "id": "api/commands/screenshot", "title": "screenshot | Cypress Documentation", "description": "Take a screenshot of the application under test and, optionally, the Cypress Command Log.", "section": "api", "source_path": "/llm/markdown/api/commands/screenshot.md", "version": "ce02913654e2655ee63448bdc92bb92c7b46a619", "updated_at": "2026-04-22T19:37:51.587Z", "headings": [ { "id": "api/commands/screenshot#screenshot", "text": "screenshot", "level": 1 }, { "id": "api/commands/screenshot#syntax", "text": "Syntax", "level": 2 }, { "id": "api/commands/screenshot#usage", "text": "Usage", "level": 3 }, { "id": "api/commands/screenshot#arguments", "text": "Arguments", "level": 3 }, { "id": "api/commands/screenshot#yields-learn-about-subject-management", "text": "Yields Learn about subject management", "level": 3 }, { "id": "api/commands/screenshot#examples", "text": "Examples", "level": 2 }, { "id": "api/commands/screenshot#no-args", "text": "No Args", "level": 3 }, { "id": "api/commands/screenshot#take-a-screenshot", "text": "Take a screenshot", "level": 4 }, { "id": "api/commands/screenshot#filename", "text": "Filename", "level": 3 }, { "id": "api/commands/screenshot#take-a-screenshot-and-save-as-a-specific-filename", "text": "Take a screenshot and save as a specific filename", "level": 4 }, { "id": "api/commands/screenshot#take-a-screenshot-and-save-in-a-specific-directory", "text": "Take a screenshot and save in a specific directory", "level": 4 }, { "id": "api/commands/screenshot#clip", "text": "Clip", "level": 3 }, { "id": "api/commands/screenshot#crop-a-screenshot-to-a-specific-position-and-size", "text": "Crop a screenshot to a specific position and size", "level": 4 }, { "id": "api/commands/screenshot#screenshot-an-element", "text": "Screenshot an element", "level": 3 }, { "id": "api/commands/screenshot#take-a-screenshot-of-the-first-post-element", "text": "Take a screenshot of the first .post element", "level": 4 }, { "id": "api/commands/screenshot#take-a-screenshot-of-the-first-post-element-with-10px-of-padding-around-it", "text": "Take a screenshot of the first .post element with 10px of padding around it", "level": 4 }, { "id": "api/commands/screenshot#chain-off-the-screenshot-to-click-the-element-captured", "text": "Chain off the screenshot to click the element captured", "level": 4 }, { "id": "api/commands/screenshot#get-screenshot-info-from-the-onafterscreenshot-callback", "text": "Get screenshot info from the onAfterScreenshot callback", "level": 3 }, { "id": "api/commands/screenshot#notes", "text": "Notes", "level": 2 }, { "id": "api/commands/screenshot#naming-conventions", "text": "Naming conventions", "level": 3 }, { "id": "api/commands/screenshot#after-screenshot-plugin-event", "text": "after:screenshot plugin event", "level": 3 }, { "id": "api/commands/screenshot#test-failures", "text": "Test Failures", "level": 3 }, { "id": "api/commands/screenshot#automatic-screenshots-on-test-failure", "text": "Automatic screenshots on test failure", "level": 4 }, { "id": "api/commands/screenshot#viewing-screenshots", "text": "Viewing Screenshots", "level": 3 }, { "id": "api/commands/screenshot#screenshots-in-ci", "text": "Screenshots in CI", "level": 4 }, { "id": "api/commands/screenshot#asynchronous", "text": "Asynchronous", "level": 3 }, { "id": "api/commands/screenshot#understanding-when-the-screenshot-is-taken", "text": "Understanding when the screenshot is taken", "level": 4 }, { "id": "api/commands/screenshot#full-page-captures-and-fixed-sticky-elements", "text": "Full page captures and fixed/sticky elements", "level": 3 }, { "id": "api/commands/screenshot#chromium-specific-behavior-with-regard-to-tabs", "text": "Chromium-specific behavior with regard to tabs", "level": 3 }, { "id": "api/commands/screenshot#rules", "text": "Rules", "level": 2 }, { "id": "api/commands/screenshot#requirements-learn-about-chaining-commands", "text": "Requirements Learn about chaining commands", "level": 3 }, { "id": "api/commands/screenshot#assertions-learn-about-assertions", "text": "Assertions Learn about assertions", "level": 3 }, { "id": "api/commands/screenshot#timeouts-learn-about-timeouts", "text": "Timeouts Learn about timeouts", "level": 3 }, { "id": "api/commands/screenshot#command-log", "text": "Command Log", "level": 2 }, { "id": "api/commands/screenshot#history", "text": "History", "level": 2 }, { "id": "api/commands/screenshot#see-also", "text": "See also", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "screenshot" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Take a screenshot of the application under test and, optionally, the\n" }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/open-mode.md#Command-Log", "children": [ { "type": "text", "value": "Cypress Command Log" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Syntax" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": ".screenshot()\n.screenshot(fileName)\n.screenshot(options)\n.screenshot(fileName, options)\n\n// ---or---\n\ncy.screenshot()\ncy.screenshot(fileName)\ncy.screenshot(options)\ncy.screenshot(fileName, options)" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Usage" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Correct Usage" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "cy.screenshot()\ncy.get('.post').screenshot()" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Arguments" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "fileName (String)" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A name for the image file. Will be relative to the\n" }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/configuration.md#Folders--Files", "children": [ { "type": "text", "value": "screenshots folder" } ] }, { "type": "text", "value": " and the\npath to the spec file. When passed a path, the folder structure will be created.\nSee the " }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/screenshot.md#Naming-conventions", "children": [ { "type": "text", "value": "Naming conventions" } ] }, { "type": "text", "value": " below\nfor more." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "options (Object)" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Pass in an options object to change the default behavior of `.screenshot()`." } ] }, { "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": "`log`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`true`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Displays the command in the " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/open-mode.md#Command-Log", "children": [ { "type": "text", "value": "Command log" } ] } ] } ] }, { "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`, the application under test is captured in the current viewport. When `fullPage`, the 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": "`clip`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`null`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Position and dimensions (in pixels) used to crop the final screenshot image. Should have the following shape: `{ x: 0, y: 0, width: 100, height: 100 }`" } ] } ] }, { "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": "`padding`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "`null`" } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Padding used to alter the dimensions of a screenshot of an element. It can either be a number, or an array of up to four numbers " }, { "type": "link", "title": null, "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties", "children": [ { "type": "text", "value": "using CSS shorthand notation" } ] }, { "type": "text", "value": ". This property is only applied for element screenshots and is ignored for all other types." } ] } ] }, { "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` when `capture` is `runner`." } ] } ] }, { "type": "tableRow", "children": [ { "type": "tableCell", "children": [ { "type": "text", "value": "`timeout`" } ] }, { "type": "tableCell", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/app/references/configuration.md#Timeouts", "children": [ { "type": "text", "value": "`responseTimeout`" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Time to wait for `.screenshot()` to resolve before " }, { "type": "link", "title": null, "url": "#Timeouts", "children": [ { "type": "text", "value": "timing out" } ] } ] } ] }, { "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. When capturing screenshots of an element, the argument is the element being captured. For other screenshots, the argument is the `document`." } ] } ] }, { "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. When capturing screenshots of an element, the first argument is the element being captured. For other screenshots, the first argument is the `document`. The second argument is properties concerning the screenshot, including the `path` it was saved to and the `dimensions` of the saved screenshot." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For more details on these options and to set some as defaults across all uses of\n`.screenshot()`, see the\n" }, { "type": "link", "title": null, "url": "/llm/markdown/api/cypress-api/screenshot-api.md", "children": [ { "type": "text", "value": "Cypress.Screenshot API doc" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Yields " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management", "children": [ { "type": "text", "value": "Learn about subject management" } ] } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`.screenshot()` yields the same subject it was given." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "It is " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/retry-ability.md#Only-queries-are-retried", "children": [ { "type": "text", "value": "unsafe" } ] }, { "type": "text", "value": "\nto chain further commands that rely on the subject after `.screenshot()`." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Examples" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The screenshot will be stored in the `cypress/screenshots` folder by default.\nYou can change the directory where screenshots are saved in the\n" }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/configuration.md#Folders--Files", "children": [ { "type": "text", "value": "Cypress configuration" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "No Args" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Take a screenshot" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "// cypress/e2e/users.cy.js\n\ndescribe('my tests', () => {\n it('takes a screenshot', () => {\n // screenshot will be saved as\n // cypress/screenshots/users.cy.js/my tests -- takes a screenshot.png\n cy.screenshot()\n })\n})" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Filename" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Take a screenshot and save as a specific filename" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "// screenshot will be saved as\n// cypress/screenshots/spec.cy.js/clicking-on-nav.png\ncy.screenshot('clicking-on-nav')" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Take a screenshot and save in a specific directory" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "// screenshot will be saved as\n// cypress/screenshots/spec.cy.js/actions/login/clicking-login.png\ncy.screenshot('actions/login/clicking-login')" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Clip" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Crop a screenshot to a specific position and size" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "// screenshot will be clipped 20px from the top and left\n// to the dimensions 400px x 300px\ncy.screenshot({ clip: { x: 20, y: 20, width: 400, height: 300 } })" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Screenshot an element" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Take a screenshot of the first .post element" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "cy.get('.post').first().screenshot()" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Take a screenshot of the first .post element with 10px of padding around it" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "cy.get('.post').first().screenshot({ padding: 10 })" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Chain off the screenshot to click the element captured" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "cy.get('button').first().screenshot().click()" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Get screenshot info from the onAfterScreenshot callback" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "cy.screenshot('my-screenshot', {\n onAfterScreenshot($el, props) {\n // props has information about the screenshot,\n // including but not limited to the following:\n // {\n // name: 'my-screenshot',\n // path: '/Users/janelane/project/screenshots/spec.cy.js/my-screenshot.png',\n // size: '15 kb',\n // dimensions: {\n // width: 1000,\n // height: 660,\n // },\n // scaled: true,\n // blackout: [],\n // duration: 2300,\n // }\n },\n})" }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Notes" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Naming conventions" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Screenshot naming follows these rules:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Screenshots are saved inside the\n" }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Asset-File-Paths", "children": [ { "type": "text", "value": "screenshots folder" } ] }, { "type": "text", "value": ".\nInside that folder, the screenshot is saved inside a folder structure relative\nto the path of the spec file, which is adjusted to remove any common ancestor\npaths shared with all other spec files. Inside this folder, the screenshot\nwill be saved with the test name:\n`{screenshotsFolder}/{adjustedSpecPath}/{testName}.png`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "For a named screenshot, the name is used instead of the suites and test name:\n`{screenshotsFolder}/{adjustedSpecPath}/{name}.png`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "For any duplicate screenshots (named or not), they will be appended with a\nnumber: `{screenshotsFolder}/{adjustedSpecPath}/{testName} (1).png`." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "This behavior can be changed by passing the `{overwrite: true}` option to\n`cy.screenshot()` to explicitly overwrite duplicate screenshots." } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "For a failure screenshot, the default naming scheme is used and the name is\nappended with ` (failed) `:" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "{screenshotsFolder}/{adjustedSpecPath}/{testName} (failed).png" } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For example, given a spec file located at `cypress/e2e/users/login.cy.js`:" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "describe('my tests', () => {\n it('takes a screenshot', () => {\n // NOTE: This file has multiple screenshots\n // each screenshot has a common ancestor path of `/users/`.\n // In this scenario `/users/` is stripped from the path.\n // cypress/screenshots/login.cy.js/my tests -- takes a screenshot.png\n cy.screenshot()\n // cypress/screenshots/login.cy.js/my tests -- takes a screenshot (1).png\n cy.screenshot()\n // cypress/screenshots/login.cy.js/my tests -- takes a screenshot (2).png\n cy.screenshot()\n\n // cypress/screenshots/login.cy.js/my-screenshot.png\n cy.screenshot('my-screenshot')\n // cypress/screenshots/login.cy.js/my-screenshot (1).png\n cy.screenshot('my-screenshot')\n // cypress/screenshots/login.cy.js/my/nested/screenshot.png\n cy.screenshot('my/nested/screenshot')\n\n // if this test fails, the screenshot will be saved to\n // cypress/screenshots/login.cy.js/my tests -- takes a screenshot (failed).png\n })\n})" }, { "type": "paragraph", "children": [ { "type": "text", "value": "To learn more about how to write and organize tests and how assets are saved,\nsee\n" }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Asset-Files", "children": [ { "type": "text", "value": "Writing And Organizing Tests" } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "after:screenshot plugin event" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "You can get details about any given screenshot and manipulate it after it has\nbeen written to disk with the\n" }, { "type": "link", "title": null, "url": "/llm/markdown/api/node-events/after-screenshot-api.md", "children": [ { "type": "text", "value": "`after:screenshot` plugin event" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Test Failures" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Automatic screenshots on test failure" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When running through `cypress run` or in\n" }, { "type": "link", "title": null, "url": "/llm/markdown/app/continuous-integration/overview.md", "children": [ { "type": "text", "value": "Continuous Integration" } ] }, { "type": "text", "value": ", Cypress\nautomatically takes a screenshot when a test fails. You can optionally turn this\noff by setting `screenshotOnRunFailure` to `false` within your\n" }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/configuration.md#Screenshots", "children": [ { "type": "text", "value": "`screenshotOnRunFailure`" } ] }, { "type": "text", "value": " or\n" }, { "type": "link", "title": null, "url": "/llm/markdown/api/cypress-api/screenshot-api.md", "children": [ { "type": "text", "value": "Cypress.Screenshot.defaults()" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Viewing Screenshots" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Screenshots in CI" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "You can see screenshots taken during a CI run in\n" }, { "type": "link", "title": null, "url": "https://on.cypress.io/cloud", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": " without any extra work." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Alternatively, to see screenshots in your Continuous Integration UI, most CI\nproviders document a way to export the screenshots as artifacts and to make them\navailable. Please see their appropriate documentation." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Asynchronous" } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Understanding when the screenshot is taken" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Taking a screenshot is an asynchronous action that takes around `100ms` to\ncomplete. By the time the screenshot is taken, it is possible something in your\napplication may have changed. It is important to realize that the screenshot\nmay not reflect what your application looked like 100% when the command was\nissued." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For example - say a command we wrote timed out:\n" }, { "type": "link", "title": null, "url": "/llm/markdown/api/commands/get.md", "children": [ { "type": "text", "value": "`cy.get('#element')`" } ] }, { "type": "text", "value": ". This causes your test to fail.\nCypress then automatically takes a screenshot when the test fails, but it is\npossible something in your application changed within this `100ms` timeframe.\nHypothetically, your app could render the element you were originally expecting\nto be present. When this happens, the screenshot may provide confusing results.\nIt is unlikely, but theoretically possible." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Another potential problem to be aware of is that our own Command Log is using\nReact under the hood and only rendering asynchronously during an animation\nframe. It is possible you will see screenshots taken before our Command Log is\ndone rendering. This means you may not see the error displayed in the\nscreenshot. But this is also why we allow taking a video - to show you the\ncomplete failure." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "We make our best effort to synchronize taking a screenshot with our renderer,\nbut the current state of your application under test could have changed in the\nmeantime and not be an accurate representation of what you want to capture." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Full page captures and fixed/sticky elements" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When passing `fullPage` to the `capture` option, Cypress scrolls the application\nunder test from top to bottom, takes screenshots at each point and stitches them\ntogether. Due to this, elements that are `position: fixed` or `position: sticky`\nwill appear multiple times in the final screenshot. To prevent this, in most\ncases you can programmatically change the element to be `position: absolute`\nbefore the screenshot and change it back afterwards like shown below:" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "cy.get('.sticky-header').invoke('css', 'position', 'absolute')\ncy.screenshot()\ncy.get('.sticky-header').invoke('css', 'position', null)" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Chromium-specific behavior with regard to tabs" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Chromium will not capture screenshots when the renderer process for the Cypress\ntab is paused. This most often happens if a new tab was opened by clicking on\nan anchor with `target=\"_blank\"`. To accommodate capturing screenshots in this\nsituation, Cypress will attempt to activate the Cypress tab when a screenshot is\ncaptured. We make our best effort to activate the tab via our Chromium extension.\nIf the extension is disabled, Cypress will force the main tab to the front. This\nwill cause the browser to steal focus in open mode. To prevent Cypress from\nstealing focus, " }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/troubleshooting.md#Allow-the-Cypress-Chrome-extension", "children": [ { "type": "text", "value": "ensure that the extension is enabled" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Rules" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Requirements " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Chains-of-Commands", "children": [ { "type": "text", "value": "Learn about chaining commands" } ] } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`cy.screenshot()` can be chained off of `cy` or off a command that yields a\nsingle DOM element." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Assertions " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Assertions", "children": [ { "type": "text", "value": "Learn about assertions" } ] } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`cy.screenshot()` will only run assertions you have chained once, and will not\n" }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/retry-ability.md", "children": [ { "type": "text", "value": "retry" } ] }, { "type": "text", "value": "." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Timeouts " }, { "type": "link", "title": null, "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Timeouts", "children": [ { "type": "text", "value": "Learn about timeouts" } ] } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`cy.screenshot()` should never time out." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Because `cy.screenshot()` is asynchronous it is technically possible for there\nto be a timeout while talking to the internal Cypress automation APIs. But for\npractical purposes it should never happen." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Command Log" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Take a screenshot with a specific filename" } ] }, { "type": "code", "lang": "javascript", "meta": null, "value": "cy.screenshot('my-image')" }, { "type": "paragraph", "children": [ { "type": "text", "value": "The commands above will display in the Command Log as:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When clicking on `screenshot` within the command log, the console outputs the\nfollowing:" } ] }, { "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#3-5-0", "children": [ { "type": "text", "value": "3.5.0" } ] } ] }, { "type": "tableCell", "children": [ { "type": "text", "value": "Added support for option `padding`." } ] } ] } ] }, { "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/node-events/after-screenshot-api.md", "children": [ { "type": "text", "value": "After Screenshot API" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/api/cypress-api/screenshot-api.md", "children": [ { "type": "text", "value": "`Cypress.Screenshot`" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/api/commands/debug.md", "children": [ { "type": "text", "value": "`cy.debug()`" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/api/commands/pause.md", "children": [ { "type": "text", "value": "`.pause()`" } ] } ] } ] }, { "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/cloud/features/test-replay.md", "children": [ { "type": "text", "value": "Test Replay" } ] } ] } ] }, { "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": 2467 }