Cypress High-Resolution Screenshots and Videos

Updated 8 November 2026 · Standard formula, shown below

Cypress can capture screenshots and test-run videos, but their pixel dimensions depend on the browser viewport and the settings used when the capture is made. Set a larger viewport for more image detail, control screenshot scaling, and check video settings so the saved files suit your review or documentation workflow.

What You’ll Need

A working Cypress project with at least one test that can run.
Node.js and the project’s installed Cypress dependency, using the version and package manager already configured for the project.
A target image size in pixels, plus enough screen space and memory to run the browser at the chosen viewport.
A way to inspect image dimensions and video playback, such as your operating system’s file details or a media player.

Step-by-Step

Decide what “high resolution” means for your output. A screenshot’s pixel dimensions are not the same as its displayed size or the density of a physical screen. If you need a 1920 × 1080 screenshot, for example, use a browser viewport with those dimensions and avoid scaling it down afterward. If you need a sharper image for a report, consider whether a larger viewport is appropriate; it can change responsive layouts and is not equivalent to increasing device pixel ratio.
Set the viewport in Cypress configuration. Open the active Cypress configuration file, usually cypress.config.js or cypress.config.ts. In the configuration object, set viewportWidth and viewportHeight, for example:
```
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  viewportWidth: 1920,
  viewportHeight: 1080,
})
```
For an ES module or TypeScript configuration, keep the file’s existing import and export style and add the same two properties to defineConfig. If you use separate end-to-end and component test settings, place them in the configuration for the test type you are running. Restart Cypress after changing configuration if it does not reload it automatically.
Check the viewport in a test. Run a test that visits the page you want to capture. You can also set the dimensions for one test with cy.viewport(1920, 1080) before visiting the page. This per-test call takes effect for that test and is useful when only some captures need a larger viewport. Confirm that the page displays the intended layout; a larger viewport may switch the site from its mobile layout to desktop navigation, or reveal content that was previously below the fold.
Capture a screenshot at the right point. Add cy.screenshot('dashboard-large') after the page has loaded and reached the state you want to document. For a full-page capture, use cy.screenshot('dashboard-full', { capture: 'fullPage' }). Cypress screenshots are saved in the configured screenshots folder, commonly cypress/screenshots. A full-page screenshot captures page content beyond the visible viewport, but it does not make the browser render at a higher device pixel ratio. Check the saved file’s actual pixel dimensions rather than relying on its displayed size.
Configure screenshot scaling when necessary. Cypress screenshot options include scale, which controls whether the captured image is scaled to fit the browser viewport, and disableTimersAndAnimations, which can help reduce animation-related variation. For example, cy.screenshot('dashboard', { scale: false }) avoids scaling the screenshot to fit the viewport where supported by the capture mode and environment. Scaling behavior can vary with the browser and capture type, so inspect the output. Do not assume that setting scale: false increases the browser’s underlying pixel density.
Make test-run videos. Run Cypress in headless mode, such as with your project’s usual command for cypress run. Cypress records videos of test runs by default in supported configurations; the output is generally placed in cypress/videos. Review your configuration for video and videosFolder. Set video: true if recording has been disabled, and use videosFolder to choose an output directory. A video records the browser run; it is not a still image, and its playback dimensions and compression affect perceived sharpness.
Set video quality only if your Cypress version supports it. Cypress configuration versions that support the videoCompression option let you adjust compression for recorded video. Consult the configuration reference for the version installed in your project before setting it: accepted values and behavior can depend on the version, and compression settings do not increase the browser viewport’s resolution. Lower compression can produce larger files. Keep the default unless you have checked the supported option and have a clear need to trade storage for image quality.
Run, find, and verify the output. Use your project’s established test command, then inspect the generated screenshot or video in its output folder. Check image pixel dimensions, whether the intended content is visible, and whether the video is readable at normal playback size. If the page needs a different layout or more visible content, adjust viewport dimensions or use a full-page screenshot; do not rely on a video-quality setting to fix a small viewport.

Common Mistakes

Confusing viewport size with device pixel ratio. A 1920 × 1080 viewport sets the browser’s CSS-pixel area; it does not guarantee a 4K image or high-density display rendering. Cypress viewport settings and operating-system display scaling are separate.
Expecting video settings to change screenshot dimensions. Video compression affects video output, not the resolution of a separately captured screenshot.
Using full-page capture when a viewport capture is required. Full-page screenshots may be very tall and can differ from what was visible during normal scrolling. Choose the capture mode that matches the deliverable.
Changing the viewport without checking layout. Bigger dimensions can alter responsive breakpoints, menus, and content placement, so the resulting screenshot may no longer represent the target device or scenario.
Assuming every run creates a video. Video recording can be disabled, unsupported for a particular run setup, or affected by configuration. Confirm the output exists rather than assuming it was saved.

Tips

Use a named screenshot and a consistent viewport for repeatable comparisons.
Wait for the page’s important content and images to load before capturing; use a reliable application-ready condition rather than an arbitrary long delay where possible.
Disable or finish animations if they make screenshots inconsistent. Cypress screenshot options can disable timers and animations for a capture, but verify that this does not change the state you intend to show.
Keep large videos out of source control unless the project explicitly needs them. Check the project’s ignore rules and retain artifacts through your CI system if that is the intended workflow.
Use the Cypress configuration reference for your installed version when selecting less common capture or video options.

Troubleshooting

The screenshot is still small or blurry: Check its pixel dimensions and the viewport used at capture time. Make sure the test-level cy.viewport() call is not overriding the configured dimensions. Open the original file rather than a resized preview, and avoid enlarging it in an editor, which cannot restore missing detail.

The page looks different in the capture: Confirm the viewport matches the intended device and inspect responsive breakpoints. Wait for fonts, images, network requests, and application state to settle. If content is clipped, try a full-page capture or adjust the viewport height.

No video appears: Confirm you ran tests in a mode that records video, inspect whether video is disabled in configuration, and look in the configured videosFolder. Check test output for recording errors and confirm your installed Cypress version and run environment support video capture.

The video looks soft or is too large: Check playback at its native size and confirm the viewport dimensions first. Review the installed version’s video compression options, if available, and balance file size against clarity. Compression cannot compensate for a low-resolution browser viewport.

Frequently Asked Questions

Can Cypress capture a 4K screenshot?
It can capture a large browser viewport, subject to browser and machine limits. Set the viewport to the desired pixel dimensions and verify the resulting file; this does not automatically reproduce a 4K device-pixel-ratio display.

Does cy.viewport() increase image quality?
It changes the browser’s viewport dimensions and can increase the screenshot’s pixel width and height. It does not, by itself, raise device pixel ratio or sharpen assets that are already low resolution.

Where does Cypress save screenshots and videos?
By default, screenshots and videos are commonly saved under cypress/screenshots and cypress/videos. The configured screenshotsFolder and videosFolder can change those locations.

Can Cypress record video during interactive testing?
Video recording is primarily associated with test runs. Check the behavior supported by your installed Cypress version and run mode; use screenshots for individual captures in a test when a video artifact is not being produced.

Why does a full-page screenshot look different from the page in the browser?
A full-page capture includes content beyond the visible viewport and may involve a different capture process than a normal viewport screenshot. Compare it with the intended deliverable and use a viewport capture if you need only the visible screen.

How can I make screenshots consistent in CI?
Use the same viewport, browser, test state, and capture options across runs. Wait for relevant content to load and avoid animations or time-dependent content where possible. Differences in browser, operating system, fonts, or rendering environment can still affect pixels.

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