Can Cypress Take Screenshots Without Running a Test?
Cypress documents screenshots as a test command, not a standalone capture command. Here’s how to capture with a minimal spec, and what to use when you need no test at all.
Short answer: Cypress does not document a standalone screenshot-only command for capturing an application without executing a test. Its documented manual capture command, cy.screenshot(), runs inside a Cypress test. To take a screenshot with Cypress, put the command in a test and run that spec. If you need a screenshot without running a Cypress test, use a separate browser or screen capture workflow.
Cypress can take manual screenshots in both cypress open and cypress run. It also automatically captures screenshots when tests fail during cypress run; that automatic failure capture is not enabled in open mode. See the official cy.screenshot() API and the Cypress screenshots guide.
1. Capture a screenshot with a minimal Cypress test
Create a spec that visits the page and takes a manual screenshot. This is the documented Cypress route when you want Cypress itself to capture the page.
// cypress/e2e/capture.cy.js
describe('capture a page', () => {
it('visits the page and saves a screenshot', () => {
cy.visit('https://example.com');
cy.screenshot('example-homepage');
});
});Run that spec in CLI mode:
npx cypress run --spec cypress/e2e/capture.cy.jsOr start the interactive runner and run the spec from there:
npx cypress openManual screenshots work in both modes. The test is still executed in either case; cypress open does not turn cy.screenshot() into a standalone command.
Choose what the screenshot contains
With no options, cy.screenshot() captures the application under test. To capture the full page, pass the documented capture option:
cy.screenshot('example-full-page', { capture: 'fullPage' });To capture a specific element, call the command on a subject:
cy.get('main article').screenshot('article');The command accepts a name and screenshot options. Review the current API reference for the complete supported option list and behavior for your Cypress version. Cypress stores screenshots in cypress/screenshots by default. Change the destination in your Cypress configuration with screenshotsFolder, for example:
// cypress.config.js
const { defineConfig } = require('cypress');
module.exports = defineConfig({
screenshotsFolder: 'artifacts/screenshots',
e2e: {
baseUrl: 'https://example.com'
}
});2. Manual screenshots versus failure screenshots
| Capture type | How it happens | When it works |
|---|---|---|
| Manual | Your test calls cy.screenshot(). |
cypress open or cypress run. |
| Automatic on failure | Cypress captures a screenshot when a test fails. | cypress run; not automatically in cypress open. |
Failure screenshots are useful for debugging test runs, but they are not a way to request an arbitrary screenshot: a test has to fail to trigger that behavior. For CI output, Cypress documents Cypress Cloud as one way to view screenshots from runs. A CI provider may also let you export screenshot files as job artifacts; consult that provider’s documentation for its artifact setup. Cypress’s CLI reference explains how to run specs from the command line: Cypress CLI.
3. Can you capture a page without executing a Cypress test?
The reviewed Cypress API and CLI documentation describe manual capture as a test command and do not describe a screenshot-only CLI command. That is a limit of the documented Cypress workflow, not a claim that no plugin or external browser tool could do it.
If you need Cypress to exercise the page before capture, use the minimal spec above. If your actual requirement is simply “give me an image of this URL,” use a browser capture workflow designed for that job rather than invoking Cypress as a test runner.
4. Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| No screenshot appears | The test did not reach the cy.screenshot() call, or the spec was not run. |
Run the intended spec and check the command log for an earlier failure. Place capture after the page has loaded and any required UI state is ready. |
You expected a screenshot from cypress open after a failure |
Automatic failure screenshots are associated with cypress run, not open mode. |
Add an explicit cy.screenshot() call to the test for manual capture. |
| The screenshot is in an unexpected folder | Cypress uses cypress/screenshots by default, or the project overrides screenshotsFolder. |
Check the Cypress configuration and look in the configured folder. |
| The captured page is incomplete | The page may still be loading content or may require a state change before capture. | Wait for an app-specific element or state before calling cy.screenshot(); avoid relying on an arbitrary short delay when a visible readiness condition is available. |
| You want an image without a test run | cy.screenshot() is a Cypress test command. |
Use an external browser or screenshot service suited to direct URL capture. |
5. Performance, reliability, and cost considerations
A Cypress screenshot is part of a test run, so the run also has to start Cypress, load the spec, and visit the page. For occasional debugging this may fit naturally into the test workflow. For repeated URL capture without test assertions, a dedicated screenshot workflow avoids maintaining a spec solely to request an image.
For reliable results, capture only after the page has reached the state you need. Prefer waiting for a meaningful element or application condition, and keep the viewport and browser setup consistent if you are comparing screenshots. In CI, retain the output through Cypress Cloud or your CI provider’s artifact mechanism according to the workflow you use.
The research sources do not establish Cypress pricing or a cost comparison for this capture use case. Account for the CI or browser infrastructure your own Cypress workflow uses. For direct URL capture, ScreenshotNeo publishes its plan limits and prices on its site.
6. Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One GET request takes a URL and returns an image or PDF, without setting up a Cypress project or running a test. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://example.com \
-o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://example.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);ScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and whether the capture was billed. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for 1,000 free screenshots a month, with no card required.
7. FAQ
Does Cypress support manual screenshots in CI?
Yes. Cypress documents manual screenshots in both open and run modes, including CI usage; a test must call cy.screenshot().
Does Cypress save screenshots as part of the test result?
The default local destination is cypress/screenshots. For CI review, Cypress Cloud is one documented viewing option; your CI provider may also support artifacts.
Can I use the failure screenshot as a regular page capture?
Failure capture is tied to a failed test during cypress run. Use an explicit manual screenshot call when you want a successful test to produce a capture.
