Configure Cypress’s application viewport with viewportWidth, viewportHeight, or cy.viewport(). Configure the headless Chrome display screen separately in before:browser:launch with --window-size (and, when needed, --force-device-scale-factor). The two controls affect different dimensions: the first determines how your application lays out, while the second determines screenshot and video output dimensions.
The two viewport dimensions Cypress controls
Most confusing Cypress sizing bugs come from treating these as one setting:
| Control | What it changes | Typical use |
|---|---|---|
viewportWidth and viewportHeight |
The CSS-pixel viewport available to the application under test (AUT) | Responsive breakpoints, layout assertions and component behavior |
cy.viewport() |
The AUT viewport for the current test or subsequent commands | Testing a mobile, tablet or desktop layout in one spec |
--window-size=WIDTH,HEIGHT |
Headless Chrome’s display screen | Screenshot and video artifact dimensions |
--force-device-scale-factor=N |
Browser rendering scale (device-pixel-ratio-like output) | Controlling physical pixels and retina-style artifacts |
Cypress documents default AUT dimensions of 1000 × 660 CSS pixels. Its documented headless rendering defaults are 1280 × 720 with device pixel ratio 1. Changing the display screen does not change the AUT viewport.
Set the AUT viewport project-wide
Put defaults in cypress.config.js or cypress.config.ts:
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
import { defineConfig } from 'cypress'
export default defineConfig({
viewportWidth: 1280,
viewportHeight: 720,
})These values apply to tests unless a narrower scope overrides them. Cypress restores the configured/default viewport between tests, which prevents one spec from silently changing the next spec’s starting conditions.
Change the viewport inside a test
Use cy.viewport(width, height) when the test itself needs to move between layouts:
describe('responsive navigation', () => {
it('works on a phone-sized viewport', () => {
cy.viewport(550, 750)
cy.visit('/dashboard')
cy.get('[data-testid="mobile-menu"]').should('be.visible')
})
it('works on a desktop viewport', () => {
cy.viewport(1280, 720)
cy.visit('/dashboard')
cy.get('[data-testid="desktop-nav"]').should('be.visible')
})
})The command accepts documented device presets and an orientation such as landscape. It changes viewport dimensions only; Cypress states that it does not simulate devicePixelRatio. If your application branches on pixel density, configure the browser’s scale factor separately.
Use suite- or test-level configuration
For a group of tests that share a responsive layout, set dimensions in the suite or test configuration. Cypress applies the values for that scope and restores the previous defaults afterward:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →describe('tablet checkout', {
viewportWidth: 834,
viewportHeight: 1112,
}, () => {
it('shows the two-column summary', () => {
cy.visit('/checkout')
cy.get('[data-testid="order-summary"]').should('be.visible')
})
})This is preferable to repeating cy.viewport() in every test when all cases in the suite use the same dimensions.
Override dimensions from the command line or environment
One headless run
npx cypress run --config viewportWidth=1280,viewportHeight=720The comma-separated --config values override project configuration for that run.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
Environment variables
CYPRESS_VIEWPORT_WIDTH=800 CYPRESS_VIEWPORT_HEIGHT=600 npx cypress runUse the equivalent environment-variable syntax for your shell or CI provider. This is useful when a pipeline matrix supplies several responsive sizes without editing the repository configuration.
Do not mutate the viewport with Cypress.config() at runtime
With Cypress 16.0.0 and later, changing viewportWidth or viewportHeight through Cypress.config() during test execution is not supported. Use cy.viewport() for an immediate change, or suite/test configuration for a scoped value.
PC 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 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchSet headless Chrome’s screen for screenshots and videos
Configure the before:browser:launch event in setupNodeEvents. Check both the browser name and browser.isHeadless so the argument is applied only to headless Chrome:
import { defineConfig } from 'cypress'
export default defineConfig({
e2e: {
setupNodeEvents(on, config) {
on('before:browser:launch', (browser, launchOptions) => {
if (browser.name === 'chrome' && browser.isHeadless) {
launchOptions.args.push('--window-size=1400,1200')
launchOptions.args.push('--force-device-scale-factor=1')
}
return launchOptions
})
},
},
})The first switch requests a 1400 × 1200 display screen. The second fixes the scale factor at 1. These arguments influence captured screenshot and video dimensions; they do not set viewportWidth or viewportHeight. Choose the screen size and scale factor based on the artifact you need. Cypress documentation also demonstrates a scale factor of 2 for retina-like output, which produces more physical pixels without changing the CSS layout dimensions.
Make the two settings work together
A common desktop capture configuration is:
import { defineConfig } from 'cypress'
export default defineConfig({
viewportWidth: 1280,
viewportHeight: 720,
e2e: {
setupNodeEvents(on, config) {
on('before:browser:launch', (browser, launchOptions) => {
if (browser.name === 'chrome' && browser.isHeadless) {
launchOptions.args.push('--window-size=1440,900')
launchOptions.args.push('--force-device-scale-factor=1')
}
return launchOptions
})
},
},
})Here the page lays out in a 1280 × 720 CSS viewport while Chrome’s captured display surface is 1440 × 900. If you need the artifact and AUT to have the same CSS dimensions, set both pairs to the same numbers, but keep in mind that the scale factor still changes physical pixel output.
Headless screenshots, videos and debugging
cypress run launches browsers headlessly by default. Cypress uses the --headless=new mode for Chrome, Chromium and Edge. To investigate a failure that appears only in CI or headless mode, run a visible browser:
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
npx cypress run --headed --no-exit --browser chromeCompare the headed result with the failing screenshot or video. A headed run can reveal browser chrome, timing, font loading or layout differences that are hidden in an automated run.
Capture a point-in-time image with cy.screenshot(). During cypress run, Cypress also captures screenshots automatically when a test fails unless you disable that behavior. Video recording is disabled by default; enable it with video: true for cypress run. Cypress does not record videos in cypress open.
Choose the right setting: a practical decision guide
- Responsive behavior is wrong: change
viewportWidth/viewportHeight,cy.viewport(), or suite/test configuration. - The screenshot canvas is the wrong size: change Chrome’s
--window-sizeinbefore:browser:launch. - The image is blurry or has unexpected physical dimensions: inspect
--force-device-scale-factor. - Only one CI command needs a different layout: use
--configor environment variables. - Several tests share a device size: use suite-level configuration.
- You need to switch sizes during one test: use
cy.viewport().
Troubleshooting common dimension problems
“I changed --window-size, but the page breakpoint did not move.”
That is expected. The launch argument changes Chrome’s display screen, not the AUT viewport. Set viewportWidth and viewportHeight, or call cy.viewport().
“My screenshot is still 1280 × 720.”
Confirm that the event is inside the active e2e.setupNodeEvents (or the relevant testing-type configuration), that the browser name is chrome, and that browser.isHeadless is true. Also ensure the run is using the configuration file you edited.
“The test passes headed but fails headless.”
Run cypress run --headed --no-exit --browser chrome and compare artifacts. Check for timing-sensitive code, fonts or images that have not loaded, viewport-dependent selectors, and code that reads device pixel ratio.
“Changing Cypress.config() has no effect.”
For Cypress 16.0.0 and later, runtime mutation of these viewport keys is not allowed. Replace it with cy.viewport() or suite/test configuration.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
“The layout is correct, but the image looks soft.”
CSS viewport size and physical output size are different. Set an explicit scale factor, such as 1 for predictable output or 2 for retina-like output, and validate the resulting artifact in the same browser and CI environment used for releases.
“The screenshot cuts off content below the fold.”
A larger browser screen does not automatically make a page full-page. Design the test and capture flow around the content you need, and ensure lazy-loaded content has appeared before calling cy.screenshot().
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Or skip the browser setup
If your goal is a clean website image rather than a Cypress assertion, ScreenshotNeo provides a single HTTP request. It removes cookie and consent banners, newsletter popups and chat widgets before capture; bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and each response identifies the page verdict and billing status in headers. Its MCP server lets Claude, Cursor and other MCP clients call take_screenshot, get_page_info and capture_pdf.
cURL
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}`);See the complete parameter list and response behavior in the ScreenshotNeo documentation. Options include full-page capture with lazy images loaded, CSS-selector element capture, dark mode, device presets or custom viewports, retina scale, PDF paper and margin controls, custom CSS and JavaScript, clicks, selector or network-idle waits, ad/tracker/request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, usage reporting and an OpenAPI specification.
| Plan | Included shots | Price |
|---|---|---|
| Free | 1,000 per month | No card |
| Starter | 3,000 | $5 |
| Growth | 15,000 | $15 |
| Pro | 60,000 | $39 |
| Scale | 250,000 | $99 |
| Business | 1,000,000 | $249 |
Yearly billing provides two months free, and every feature is available on every plan. Start with 1,000 free screenshots a month without a card.
FAQ
Does cy.viewport() change device pixel ratio?
No. It changes CSS viewport dimensions. Configure browser scale separately when physical pixel density matters.
Recommended Free Tools
What are Cypress’s default AUT dimensions?
The documented defaults are 1000 × 660 CSS pixels.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
What are headless Chrome’s documented Cypress defaults?
Cypress documents a 1280 × 720 display screen with device pixel ratio 1 for headless rendering.
Can I use the Chrome launch argument to test responsive breakpoints?
No. Use Cypress viewport settings for breakpoint behavior; use launch arguments for artifact display dimensions.
Frequently Asked Questions
Does cy.viewport() change device pixel ratio?
No. It changes CSS viewport dimensions. Configure browser scale separately when physical pixel density matters.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →What are Cypress’s default AUT dimensions?
The documented defaults are 1000 × 660 CSS pixels.
What are headless Chrome’s documented Cypress defaults?
Cypress documents a 1280 × 720 display screen with device pixel ratio 1 for headless rendering.
Can I use the Chrome launch argument to test responsive breakpoints?
No. Use Cypress viewport settings for breakpoint behavior; use launch arguments for artifact display dimensions.
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.
Free tools Windows power users keep installed
One-click scans. No signup required.
