Cypress screenshot scale option makes screenshots blurry

If a Cypress screenshot looks blurry, first check the capture type and the dimensions of the saved image. The scale option controls whether Cypress scales the application to fit the browser viewport; it does not by itself request a higher-resolution image. Cypress documents a default of false, but runner captures force scaling to true. Also, Cypress does not simulate devicePixelRatio, and its preview may scale an image to fit the available space.

This guide covers Cypress’s own screenshot workflow and how to distinguish a soft preview from a low-resolution saved file. For API-based captures outside a Cypress test runner, ScreenshotNeo is an alternative that returns a screenshot from one request.

1. What Cypress’s `scale` option does

Cypress defines scale as scaling the application to fit into the browser viewport. The option defaults to false. Cypress always coerces it to true for runner captures, which include the browser viewport and Cypress Command Log. That means setting scale: false does not make a runner capture behave like a regular viewport capture.

Scaling may make the captured content appear smaller in the available browser or preview area. It is separate from the saved image’s pixel dimensions. Changing viewportWidth and viewportHeight sets the application’s CSS viewport; it does not automatically increase physical output pixels or simulate a higher device pixel ratio.

Cypress documents that scaling the app should not affect its calculations or behavior. That statement is about application behavior, not a guarantee about screenshot sharpness.

2. Identify the capture type first

Before changing options, determine which screenshot Cypress is producing. Capture type changes what the output contains and how scale is handled.

Capture type	What it captures	Scale considerations
`viewport`	The app in the current browser viewport	Check the effective scale setting and saved file dimensions.
`fullPage`	The app from top to bottom; Cypress scrolls and stitches captures	Inspect the resulting image dimensions and check whether content changes while scrolling.
`runner`	The browser viewport and Cypress Command Log	Cypress forces `scale: true` for this type.
`element`	A selected element	Check the selected element’s bounds and the saved output dimensions.

Failure screenshots are coerced to runner captures. If the screenshot appears only after a test failure, account for runner behavior even if your normal screenshots use another capture type.

3. Check the saved PNG dimensions

Do not diagnose resolution from the Cypress preview alone. Cypress may scale and center the app in its preview if the screen cannot display all configured viewport pixels. The saved artifact can therefore have different apparent sharpness or dimensions from the preview.

Use onAfterScreenshot to log the saved path and dimensions reported by Cypress:

cy.screenshot('checkout', {
  onAfterScreenshot($el, props) {
    // Cypress supplies the saved file path and dimensions in props.
    console.log('Screenshot:', props.path);
    console.log('Dimensions:', props.dimensions);
  },
});

Then inspect the image file itself with an image viewer or image metadata tool. Compare its pixel width and height with the dimensions you expected. A larger CSS viewport is not proof that the saved PNG has more pixels.

4. A diagnostic sequence for blurry Cypress screenshots

Record the capture type. Note whether it is viewport, fullPage, runner, or element. For failure captures, assume runner behavior applies.
Check screenshot defaults. Review any call to Cypress.Screenshot.defaults() and the options passed to .screenshot(). Defaults can affect screenshots, including failure screenshots.
Read the saved dimensions. Log the screenshot callback properties and inspect the actual PNG rather than judging only the preview pane.
Separate CSS viewport from output pixels. Cypress viewport dimensions define the app’s viewport. Cypress does not simulate devicePixelRatio, so do not treat viewport width and height as physical image dimensions.
Check for fit-to-iframe scaling. A larger viewport can still look scaled down if the app is fitted into the available iframe or preview. Confirm behavior in the browser and run mode you use.
Keep the rendering environment fixed. For visual comparisons, use the same Cypress and browser versions, operating system, display scaling, and installed fonts where possible.

5. Set scale deliberately

For a normal viewport capture, you can set scale explicitly. This example makes the intended setting clear, though it cannot override runner capture behavior:

cy.viewport(1280, 800);

cy.get('[data-cy=checkout]').screenshot('checkout', {
  capture: 'viewport',
  scale: false,
});

To make a setting the default for screenshot commands, use Cypress.Screenshot.defaults() in your support setup. Confirm the option names and supported values against the Cypress version in your project.

Cypress.Screenshot.defaults({
  capture: 'viewport',
  scale: false,
});

If you need a full-page screenshot, select that capture mode explicitly and expect Cypress to scroll and stitch the page:

cy.get('body').screenshot('full-page', {
  capture: 'fullPage',
  scale: false,
});

Full-page output can be tall, and content that loads or animates during scrolling may not look identical in every stitched region. Stabilize the page before capture, for example by waiting for a known content selector or disabling animations in the test environment.

6. When the goal is higher pixel resolution

Changing viewportWidth or viewportHeight alone may not produce a sharper saved image. Cypress’s engineering discussion of high-resolution screenshots explains that the app can still be scaled to fit the available iframe. It also discusses browser device scale factor and the Chrome argument --force-device-scale-factor=1.

Treat browser flags as environment-specific. Verify the saved dimensions and rendering in the actual browser and run mode you use; the flag is not a universal multiplier or a guarantee that every Cypress capture will gain resolution. Cypress does not simulate devicePixelRatio as part of its viewport behavior.

If your goal is stable visual regression, consistent rendering is usually more useful than simply requesting a larger viewport. Fix the Cypress and browser versions, OS, fonts, display scaling, viewport, and test data across runs. Cypress notes that those environment differences can affect rendering.

7. Troubleshooting

Symptom	Likely cause	What to do
The Cypress preview looks blurry, but the downloaded PNG looks sharp.	The preview scaled the image to fit the available display area.	Judge the saved artifact at its native size and inspect its pixel dimensions.
`scale: false` has no visible effect on a failure screenshot.	Failure screenshots are runner captures, and runner captures force scale to true.	Use a regular viewport or element screenshot for the application image, or accept runner scaling for failure artifacts.
A larger `viewportWidth` does not create a larger PNG.	CSS viewport size is not the same as physical output pixel count; the app may also be fitted to an iframe.	Inspect the saved PNG dimensions and verify browser scale behavior in your run mode.
Screenshots differ across machines.	OS, browser version, display scaling, and installed fonts can change rendering.	Pin the environment and compare captures at a fixed viewport.
A full-page capture has seams or inconsistent regions.	Cypress scrolls and stitches the page, and page content may change while it scrolls.	Wait for the page to settle, disable animation where appropriate, and inspect the captured regions.
The output is the wrong size despite an explicit option.	A default configured through `Cypress.Screenshot.defaults()` or another capture mode may affect the command.	Log the capture type and dimensions, then review both command-level options and screenshot defaults.

8. Performance, reliability, and cost notes

Cypress screenshot capture runs inside your test workflow, so the work and runtime belong to that workflow. Full-page capture has additional scrolling and stitching work compared with a viewport capture. Larger pages and unstable content can make full-page results harder to compare reliably.

For repeatable results, wait for the specific content you need rather than relying on an arbitrary delay, keep the browser environment fixed, and inspect output dimensions when resolution matters. This guide makes no general claim about a particular speed or resolution improvement: results depend on capture mode and execution environment.

If you need screenshots as an API response rather than as test artifacts, ScreenshotNeo is a website screenshot API and MCP server. Its billing rules say clean screenshots are billed; bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed. See the ScreenshotNeo API documentation for request options and response details.

9. Or skip the browser setup

For an API-based website screenshot, call ScreenshotNeo with a URL. This cURL request saves a WebP image:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Equivalent Python:

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)

Equivalent 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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', new Uint8Array(await res.arrayBuffer()));

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account for 1,000 screenshots a month, with no card required.

10. FAQ

Does `scale: false` increase screenshot resolution?

No. It disables scaling the app to fit the viewport where the capture mode honors the setting. It does not request a higher device pixel ratio or promise more saved pixels.

Why does Cypress scale runner screenshots?

Cypress documents that runner captures always coerce scale to true. Runner images include Cypress’s Command Log as well as the browser viewport.

Should I increase viewport dimensions to fix blur?

Only if the test needs a larger CSS viewport. Increasing viewport dimensions alone does not ensure the saved image has more physical pixels. Check the artifact dimensions and preview scaling first.

Can I use Cypress screenshots for visual regression?

cy.screenshot() captures images but does not compare them. Cypress’s visual testing guidance names integrations such as Applitools and SmartBear VisualTest for comparison workflows.

Sources

Cypress.Screenshot API — options, defaults, and capture behavior.
Cypress cy.screenshot() command — capture modes, full-page stitching, and post-capture properties.
Cypress cy.viewport() command — viewport sizing, preview scaling, and device pixel ratio behavior.
Cypress engineering blog on high-resolution screenshots — iframe scaling and browser scale factor.
Cypress visual testing guidance — controlled comparisons and integrations.