How to Save Cypress Screenshots in an Azure DevOps Pipeline
Cypress saves failure screenshots during `cypress run`. Publish its screenshots folder as a pipeline artifact so you can inspect it from the Azure DevOps run.
To save Cypress screenshots from an Azure DevOps pipeline, run your tests with npx cypress run, then publish Cypress’s screenshots folder as a pipeline artifact. Cypress automatically captures screenshots when tests fail during cypress run; the default output directory is cypress/screenshots. In Azure DevOps Services, use the publish YAML shortcut and set condition: always() so the publish step can run after a failed test step.
Publish Cypress screenshots from Azure DevOps Services
Add a publish step after your Cypress command in the pipeline YAML:
steps:
- script: npx cypress run
displayName: Run Cypress tests
- publish: $(System.DefaultWorkingDirectory)/cypress/screenshots
artifact: cypress-screenshots
displayName: Publish Cypress screenshots
condition: always()The publish shortcut publishes a file or directory as a pipeline artifact. After the run, open the pipeline run summary and select the cypress-screenshots artifact to inspect or download the files. See Microsoft’s pipeline artifact guide and condition documentation.
What the YAML does
npx cypress runruns Cypress in CI mode. Cypress automatically saves screenshots for test failures unless that behavior is disabled.- The
publishstep targets the default screenshots directory under the pipeline working directory. artifact: cypress-screenshotsgives the uploaded artifact a recognizable name.condition: always()allows the step to run even when a dependency fails or the build is canceled. Microsoft notes that a custom condition replaces the default condition, so include the condition deliberately.
Keep the artifact step after the Cypress command. Publishing before the tests finish can upload an empty or incomplete directory.
Check Cypress screenshot settings
Cypress’s automatic failure screenshots work during cypress run, including CI. They are not automatically taken during cypress open. The default screenshot directory is cypress/screenshots, but your project may override it in its Cypress configuration. The pipeline’s publish path must match the configured directory. See the official Cypress screenshots and videos guide and configuration reference.
| Setting or command | What it controls | What to check |
|---|---|---|
screenshotsFolder |
Where Cypress writes screenshots. | Publish this path if it differs from cypress/screenshots. |
screenshotOnRunFailure |
Automatic screenshots when tests fail during a run. Defaults to true. |
Keep it enabled if you want failure screenshots. A value of false disables them. |
trashAssetsBeforeRuns |
Whether Cypress clears screenshots, videos, and downloads before a run. Defaults to true. |
Set it to false if files from earlier runs in those asset folders must be retained. |
cy.screenshot() |
Takes a screenshot at a point chosen by your test. | Use it for a useful checkpoint or a state you need even when the test passes; see the Cypress screenshot API. |
For example, if your configuration changes the screenshot directory to artifacts/cypress-shots, update the publish target:
- publish: $(System.DefaultWorkingDirectory)/artifacts/cypress-shots
artifact: cypress-screenshots
displayName: Publish Cypress screenshots
condition: always()Take a manual screenshot
Use cy.screenshot() when you want a capture at a specific point in a test, rather than only when a test fails:
it('shows the account page', () => {
cy.visit('/account')
cy.get('[data-testid="account-heading"]').should('be.visible')
cy.screenshot('account-page-ready')
})The screenshot is still written under the configured screenshots folder, so the same artifact publishing step can expose it. Cypress documents additional screenshot command options in its API reference.
Azure DevOps Server and Build Artifacts
Pipeline artifacts are supported by Azure DevOps Services. Microsoft’s task reference directs Azure DevOps Server and TFS 2018 users to Publish Build Artifacts instead. For Server, publish the folder with the build artifact task:
steps:
- script: npx cypress run
displayName: Run Cypress tests
- task: PublishBuildArtifacts@1
displayName: Publish Cypress screenshots
inputs:
PathtoPublish: '$(System.DefaultWorkingDirectory)/cypress/screenshots'
ArtifactName: 'cypress-screenshots'
publishLocation: 'Container'
condition: always()Choose the artifact task that matches your Azure DevOps installation. Refer to Microsoft’s Publish Pipeline Artifact task reference for the Services limitation and artifact publishing details.
Handle an empty or missing screenshot folder
If a run has no failing tests and no manual screenshot calls, Cypress may not have produced screenshot files. The provided Microsoft references require a target path but do not prescribe a Cypress-specific pattern for a missing folder. Check the actual directory behavior on your agent and decide whether a missing folder should fail the pipeline or be treated as “nothing to upload.”
If you want the publish step to have a directory available every time, create it before the test command. Cypress can still clear asset folders before runs when trashAssetsBeforeRuns is enabled, so confirm the resulting directory exists at publish time:
steps:
- script: mkdir -p cypress/screenshots
displayName: Prepare screenshot directory
- script: npx cypress run
displayName: Run Cypress tests
- publish: $(System.DefaultWorkingDirectory)/cypress/screenshots
artifact: cypress-screenshots
displayName: Publish Cypress screenshots
condition: always()This example uses a Unix-style agent command. On a Windows agent, use an appropriate directory-creation command or a script that works in the selected shell. If your Cypress configuration changes screenshotsFolder, create and publish that configured path instead.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| No screenshots appear after a successful run. | Cypress automatically captures screenshots on failure, not on every passing test. | Add a cy.screenshot() call at the point you want captured, then publish the directory. |
| No screenshots appear after a failed test. | The run used cypress open, automatic screenshots were disabled, or the configured output path differs from the published path. |
Run npx cypress run, check screenshotOnRunFailure, and align the publish target with screenshotsFolder. |
| The publish step does not run after a test failure. | The publish step uses the default success condition. | Set condition: always() if the upload should still run after a failed or canceled dependency. |
| The publish step cannot find its target. | The target directory is missing or the path is wrong for the agent’s working directory. | Check the configured screenshots folder and the agent’s working directory. Create the directory if your pipeline requires it to exist even when there are no screenshots. |
| Old screenshots disappear on a later run. | trashAssetsBeforeRuns defaults to true and clears Cypress asset folders before a run. |
Set it to false when earlier files must be retained, or collect the files before a later run clears them. |
| The pipeline artifact task is unavailable or unsupported. | The pipeline is running on Azure DevOps Server or TFS 2018, where pipeline artifacts are not supported. | Use the Publish Build Artifacts task for that installation. |
| A wildcard path does not work as the artifact target. | The Publish Pipeline Artifact task does not support wildcards in targetPath. |
Set the target to the directory itself. If you need to select files, prepare the desired directory first, then publish that directory. |
For task-specific options and path requirements, consult Microsoft’s task reference. The YAML shortcut accepts a file or folder path; the underlying task requires targetPath, and wildcards are unsupported there.
Performance, reliability, and artifact size
- Publish only what you need. The artifact step uploads the target file or directory. Point it at the screenshots folder rather than a broader workspace when screenshots are the intended output.
- Keep the upload after the tests. This ensures the files from the current run are available to publish.
- Use a stable output path. A configured screenshots folder and matching artifact target make it easier to find captures across runs.
- Account for cleanup. Cypress clears screenshots, videos, and downloads before a run by default. Disable
trashAssetsBeforeRunsonly if retaining previous files is part of the workflow. - Use the right artifact service. Pipeline artifacts apply to Azure DevOps Services; Azure DevOps Server needs Build Artifacts.
The cited Cypress and Microsoft references do not provide a Cypress-specific upload benchmark, artifact retention promise, or cost estimate. Upload time and storage impact depend on the files produced and the pipeline setup, so keep the published directory scoped to the files your team needs.
Or skip the browser setup
If your task is to capture a website page as an image or PDF rather than preserve Cypress test-run evidence, ScreenshotNeo is a website screenshot API and MCP server for developers. A single request can return a PNG, JPEG, WebP, or PDF. The API accepts the parameter names other screenshot APIs use, which can make switching straightforward. See the ScreenshotNeo API documentation.
Here is a cURL request:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe equivalent Python request is:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)And in Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);- Cookie banners are accepted and more than 60 known consent platforms, newsletter popups, and chat widgets are removed before capture; each step can be turned off.
- Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Responses include
X-Page-VerdictandX-Billedheaders. - An MCP server gives AI agents, including Claude and Cursor, tools for screenshots, page information, and PDF capture.
- The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 shots. Every feature is available on every plan.
Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.
FAQ
Does Cypress take a screenshot for every passing test?
No. Automatic screenshots are taken on test failure during cypress run. Use cy.screenshot() when you need a capture during a passing test.
Where do I find the uploaded screenshots?
Open the Azure DevOps pipeline run summary and select the artifact named in your YAML, such as cypress-screenshots.
Can I publish screenshots from Azure DevOps Server with the same task?
No. Microsoft supports Pipeline Artifacts on Azure DevOps Services. For Azure DevOps Server and TFS 2018, use Publish Build Artifacts.
Will Cypress keep screenshots from previous runs?
Not by default. Cypress clears its asset folders before runs when trashAssetsBeforeRuns is enabled, which is the default.
