Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteConfigure the size of the application under test with viewportWidth and viewportHeight; configure what the screenshot contains separately with capture. Cypress documents 1000 × 660 pixels as the default application viewport. Set project defaults in cypress.config.js or cypress.config.ts, call cy.viewport() for an in-test change, and use cy.screenshot({ capture: 'viewport' }) when you want only the currently visible app area instead of Cypress’s documented default, fullPage.
Viewport size and screenshot capture are different settings
A Cypress test has an application viewport: the width and height available to the page being tested. Responsive CSS, media queries and layout calculations use this size. A screenshot has a capture mode: it determines whether Cypress records that viewport, the whole application document, or the Cypress runner itself.
| Question | Setting | Effect |
|---|---|---|
| How wide and tall should the page be? | viewportWidth, viewportHeight, or cy.viewport() |
Changes the application’s layout viewport. |
| Which pixels should the image contain? | cy.screenshot({ capture: ... }) or screenshot defaults |
Chooses viewport, fullPage or runner capture. |
| Why is the image or video rendered at an unexpected outer size? | Headless browser display configuration | Can change rendering dimensions without changing the application’s Cypress viewport. |
Keeping these decisions separate prevents a common mistake: changing the browser’s display size and expecting the page’s responsive breakpoints to change, or changing viewportWidth and expecting a full-page screenshot to become a viewport-only image.
Set project-wide viewport defaults
Cypress documents 1000 pixels wide by 660 pixels high as its default application viewport. Put different defaults in the project configuration when most tests should run at the same size.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →JavaScript configuration
const { defineConfig } = require('cypress')
module.exports = defineConfig({
viewportWidth: 1280,
viewportHeight: 720,
})Save this as cypress.config.js. Every test starts with a 1280 × 720 application viewport unless a narrower scope or a command changes it.
TypeScript configuration
import { defineConfig } from 'cypress'
export default defineConfig({
viewportWidth: 1280,
viewportHeight: 720,
})Use the same two properties in cypress.config.ts if your Cypress project is TypeScript-based. Keep the values in source control so local runs and CI use the same responsive baseline.
Override the defaults for one command-line run
For a one-off CI matrix entry or debugging run, override both values without editing the file:
npx cypress run --config viewportWidth=1280,viewportHeight=720The command-line values apply to that invocation. They are useful when the same test suite must be checked at several desktop sizes.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Change the viewport during a test
Use cy.viewport() when a test needs to move between responsive layouts. The numeric form accepts width and height in pixels:
it('shows the compact navigation', () => {
cy.viewport(550, 750)
cy.visit('/account')
cy.get('[data-testid="mobile-nav"]').should('be.visible')
})A viewport preset can also be passed to cy.viewport(). Presets are convenient for device-oriented checks; explicit numbers are clearer when a design specification gives exact dimensions. Set the viewport before the assertion that depends on it, and make the intended size obvious in the test name when several layouts are covered.
Scope a suite or an individual test
Cypress lets a suite or test provide viewportWidth and viewportHeight as test configuration:
describe('medium viewport layout', {
viewportWidth: 400,
viewportHeight: 1000,
}, () => {
it('shows the compact navigation', () => {
cy.visit('/dashboard')
cy.get('[data-testid="compact-nav"]').should('be.visible')
})
})This scope is useful when every test in a block represents one layout. Cypress says the values return to the prior defaults after the suite or test finishes, so another suite does not inherit the temporary dimensions.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Do not resize the running test with Cypress.config()
Starting with Cypress 16.0.0, attempting to set viewportWidth or viewportHeight through Cypress.config() while a test is executing throws an error. Use cy.viewport() for a runtime change; reserve configuration properties for project, suite or test setup.
Choose what cy.screenshot() captures
The screenshot command has an independent capture option. Cypress documents fullPage as the default.
| Capture value | Pixels included | Use it when |
|---|---|---|
viewport |
The application currently visible in its viewport. | You need a screenshot that matches what a user sees without scrolling. |
fullPage |
The application from top to bottom. Cypress scrolls through the page and stitches the captures. | You are documenting or comparing the complete document. |
runner |
The browser viewport together with the Cypress Command Log. | You need test-runner context for diagnosis rather than a clean page image. |
Capture the current application viewport
cy.viewport(1280, 720)
cy.visit('/pricing')
cy.screenshot('pricing-viewport', { capture: 'viewport' })This records the 1280 × 720 application area currently visible after the page has loaded. It does not include the Command Log.
Capture the complete page
cy.screenshot('pricing-full-page', { capture: 'fullPage' })fullPage uses the current application width and extends vertically through the document. Very long pages require more scrolling and stitching than a viewport capture, so use this mode deliberately in visual-regression jobs.
Capture the Cypress runner
cy.screenshot('debug-runner', { capture: 'runner' })A runner image contains the browser viewport and Cypress’s Command Log. Cypress also coerces screenshots taken automatically for test failures to runner, which ensures diagnostic commands are visible.
Set a capture mode for many screenshots
When a project consistently wants one capture style, set the screenshot default in a support file that loads before test files:
Cypress.Screenshot.defaults({
capture: 'viewport',
})Place this in a support file such as cypress/support/e2e.js (or its TypeScript equivalent). A per-call option on cy.screenshot() still lets an individual test choose another mode.
Useful screenshot defaults
disableTimersAndAnimations: trueis Cypress’s documented default and helps prevent moving content during capture.scale: falseis the documented default for application captures; runner captures enable scaling.- Blackout selectors can hide sensitive or intentionally variable elements before the image is written.
These options affect the image operation, not the responsive viewport used by your application. A blackout selector hides content in the output; it does not remove that element from layout calculations.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Failure screenshots, folders and CI behavior
During cypress run, Cypress captures screenshots on test failure by default. It does not automatically take failure screenshots during cypress open. Disable the run-time behavior with screenshotOnRunFailure: false or through screenshot defaults when failure images are not wanted.
Generated files go to cypress/screenshots by default. Set screenshotsFolder in Cypress configuration if your CI artifact collector expects another directory. Remember that failure images use runner capture, so they are not equivalent to the viewport-only images created by an explicit cy.screenshot({ capture: 'viewport' }).
Why headless screenshots can have surprising dimensions
The headless browser’s display size and Cypress’s application viewport are distinct. Cypress explicitly states that changing the former does not change viewportWidth or viewportHeight. Display settings can affect the outer rendering of screenshots and videos, while the application still lays itself out at the configured Cypress viewport.
When an image is the wrong size, identify which layer is wrong:
- If responsive elements are in the wrong layout, check
viewportWidth,viewportHeight, suite/test configuration and anycy.viewport()call. - If the page layout is correct but the bitmap has unexpected borders or scaling, inspect headless display and screenshot
scale. - If the image contains more or less content vertically than expected, check
capture:fullPageandviewportintentionally produce different heights. - If Cypress controls appear in the image, the capture is
runner—often because it is an automatic failure screenshot.
A reliable viewport-and-screenshot workflow
- Choose the application dimensions that represent the layout under test.
- Set them globally in
cypress.config.js/.ts, or scope them to a suite or test when only part of the suite needs that size. - Use
cy.viewport()immediately before a deliberate in-test breakpoint change. - Wait for the page state you intend to document, including route completion and any content that must be visible.
- Select
viewport,fullPageorrunnerexplicitly when the default is not the desired output. - Keep one-off command-line overrides visible in CI configuration so a later run is reproducible.
For visual comparisons, keep the viewport, capture mode, scaling behavior and dynamic-content handling consistent. A change in any one of those can look like a UI regression even when application code is unchanged.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common errors and fixes
“My screenshot is full page even though I set a 720-pixel height.”
The height setting controls the application viewport, not capture mode. Pass { capture: 'viewport' } to cy.screenshot() or set that value with Cypress.Screenshot.defaults().
“Changing Cypress.config('viewportWidth', ...) throws.”
That runtime pattern is unsupported from Cypress 16.0.0 onward. Replace it with cy.viewport(width, height); use configuration files or test configuration for defaults.
“The page uses the desktop layout in headless mode.”
Check the Cypress application viewport first. Headless display dimensions do not set viewportWidth or viewportHeight. Confirm the effective values in the configuration and in any preceding cy.viewport() call.
“A failure image includes the Command Log.”
That is expected: Cypress coerces automatic failure screenshots to runner. Create a separate explicit viewport screenshot when you need a clean application image.
“Tests at different sizes affect one another.”
Prefer suite/test viewport configuration for isolated groups, and keep explicit cy.viewport() calls close to the assertions they serve. Cypress restores scoped suite/test values after their scope finishes; avoid relying on an accidental prior test state.
“The full-page image misses content that appears later.”
Make the page reach the intended state before calling cy.screenshot(). Assert that the relevant content exists or wait for the application request and rendering condition your test owns; capture mode cannot make an unfinished page complete.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server when you need an image outside the Cypress runner. One GET request can return PNG, JPEG or WebP (or a PDF), with options for full-page capture, element selection, device or custom viewport, dark mode, retina scale, waits, custom CSS and JavaScript, headers, cookies, geolocation, blocking rules and more. It removes cookie-consent banners, newsletter popups and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the page verdict and billing result in X-Page-Verdict and X-Billed headers.
Use the API documentation at https://screenshotneo.com/docs/ for the complete option list. This request captures the target URL without installing a browser:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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)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}`);ScreenshotNeo also exposes an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots, and every feature is available on every plan. Create a free ScreenshotNeo account to get started.
Frequently Asked Questions
Can I keep a desktop default while testing a mobile breakpoint in one test?
Yes. Leave the project default unchanged, call cy.viewport() for the breakpoint section, and set the screenshot’s capture value independently.
Which Cypress file is best for a team-wide screenshot convention?
Use the support file loaded before test files with Cypress.Screenshot.defaults(); keep exceptions explicit on the individual cy.screenshot() call.
Free tools Windows power users keep installed
One-click scans. No signup required.
Does changing capture mode alter responsive CSS breakpoints?
No. Breakpoints respond to the application viewport dimensions. Capture mode only decides which rendered pixels Cypress writes to the image.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
