Can Cypress Take Screenshots Without Running a Test?

Updated 6 November 2026 · Standard formula, shown below

Yes, you can take screenshots with Cypress without running a full test. The simplest way is to use the cy.screenshot() command inside a test, but you can also capture a screenshot directly from the Cypress Test Runner’s interactive mode, or use the cypress run command with a minimal spec file. This article explains the exact methods, when each is appropriate, and common pitfalls.

Understanding Cypress Screenshot Capabilities

Cypress is primarily a test runner, and its screenshot features are built around test execution. However, the Cypress Test Runner (the interactive GUI launched with cypress open) allows you to run a single test file and pause at any point. While paused, you can use the cy.screenshot() command from the browser’s DevTools console to capture the current state of the page. This works because the Test Runner’s command execution is live, and the screenshot command is available as a global function.

For a more automated approach, you can create a temporary spec file that contains only a cy.visit() and a cy.screenshot() command, then run it with cypress run --spec temp.spec.js. This will execute the test, take the screenshot, and exit, without running any other tests. This method is useful for capturing a page state that requires login or setup, as you can include those steps in the same spec.

Method 1: Using the Test Runner’s Console

This is the quickest way to take a screenshot without writing a formal test. It’s ideal for prototyping or debugging a specific page.

Start Cypress with cypress open and select a spec file (any file will do, even an empty one).
In the Test Runner, let the test run until it finishes or pauses. You can also use cy.pause() in the spec to halt execution.
Open the browser’s Developer Tools (F12) and go to the Console tab.
Type cy.screenshot('my-screenshot') and press Enter.
The screenshot will be saved to the cypress/screenshots folder, under a subfolder named after the spec file.

This method works because Cypress exposes its commands as global functions in the console when the Test Runner is active. The screenshot is taken of the current viewport, and you can specify a different capture area using options like { capture: 'fullPage' }.

Method 2: A Minimal Spec File

If you need to automate screenshots (e.g., for documentation or visual regression), create a dedicated spec file. This is more reliable than the console method because it’s repeatable and can be integrated into CI.

Create a new file, for example cypress/e2e/screenshot.spec.js.

Add the following code:

describe('Screenshot', () => {
  it('captures the page', () => {
    cy.visit('https://example.com');
    cy.screenshot('homepage');
  });
});

Run cypress run --spec cypress/e2e/screenshot.spec.js.
The screenshot is saved to cypress/screenshots/screenshot.spec.js/homepage.png.

You can include any number of page interactions before the screenshot, such as logging in or clicking through a flow. This is the recommended approach for capturing specific application states.

Where Screenshots Are Saved

By default, Cypress saves screenshots in the cypress/screenshots folder. The exact path depends on how you run Cypress:

When using cypress open and the console method, the file is saved under a subfolder named after the spec file that was running.
When using cypress run, the folder structure is cypress/screenshots/<spec-name>/<screenshot-name>.png.
You can change the default folder by modifying the screenshotsFolder option in your cypress.config.js file.

Note that screenshots taken during a test failure are automatically saved to a separate folder (usually cypress/screenshots/__failures__), but this only happens when a test fails.

Common Pitfalls and Issues

Several issues can arise when trying to take screenshots outside a normal test run:

Command not found: If you try cy.screenshot() in the console before the Test Runner has fully loaded, you may get an error. Wait until the test has started running.
Blank screenshots: If the page hasn’t finished loading, the screenshot may be blank. Use cy.visit() with a cy.wait() or ensure the page is fully rendered before capturing.
Full-page vs viewport: By default, Cypress captures only the viewport. To capture the entire scrollable page, use cy.screenshot({ capture: 'fullPage' }).
File overwriting: If you take a screenshot with the same name in the same spec, it overwrites the previous one. Use unique names or timestamps if you need to keep multiple versions.

Comparing Cypress Screenshot Options

Cypress offers several built-in screenshot commands, each suited to different needs:

cy.screenshot(): Captures the current page or element. Can be used anywhere in a test.
cy.screenshot({ capture: 'runner' }): Captures the entire Cypress Test Runner UI, including the command log. Useful for debugging.
cy.screenshot({ capture: 'viewport' }): The default, captures just the visible viewport.
cy.screenshot({ capture: 'fullPage' }): Captures the entire page, scrolling automatically.

For element-specific screenshots, you can chain cy.get('selector').screenshot(). This captures only that element, which is helpful for targeted visual checks.

Frequently Asked Questions

Can I take a screenshot without a spec file at all?

No, Cypress requires a running test context to execute commands. Even the console method requires a spec file to be loaded in the Test Runner. However, you can use a minimal spec with just a cy.visit() and cy.screenshot().

Does `cy.screenshot()` work in headless mode?

Yes, it works exactly the same in headless mode (using cypress run). The screenshot is saved to the same folder, and you can capture full-page screenshots as well.

How do I take a screenshot of a specific element?

Use cy.get('selector').screenshot('name'). This will capture only that element, not the whole page. This is useful for UI components.

Can I take a screenshot after a test has already finished?

No, once the test has completed, the browser context is torn down. You must take the screenshot during the test execution. If you need a screenshot after a failure, Cypress automatically captures one, but you cannot manually trigger it after the test ends.

Why is my screenshot blank or missing?

Check that the page has fully loaded before taking the screenshot. Also, ensure you are using the correct capture option (viewport vs fullPage). If using the console method, make sure the Test Runner is active and the page is visible.

Can I take screenshots in parallel runs?

Yes, each parallel run has its own screenshots folder, so files won’t overwrite each other. However, if you use the same screenshot name in multiple specs, they will be saved in separate subfolders, so no conflict occurs.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.