Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Use cy.viewport(width, height) to set the application viewport for a Cypress test, or set viewportWidth and viewportHeight in Cypress configuration for defaults. If you need to change the display area used for headless screenshots or videos, configure the browser in before:browser:launch instead. These are separate settings: changing the headless browser window does not resize the application viewport Cypress uses for assertions.
First decide which “screen size” you need
Cypress exposes three related but different dimensions. Choosing the wrong one is the most common reason a responsive test appears not to resize.
| Need | Use | What changes |
|---|---|---|
| Resize the page under test now | cy.viewport(width, height) or a preset |
The application viewport for the current test |
| Choose a default for tests | viewportWidth and viewportHeight in Cypress config |
The default application viewport, unless a test overrides it |
| Give one suite or test its own dimensions | Suite- or test-level configuration | A scoped application viewport that ends with that scope |
| Override dimensions for a run | --config or documented CYPRESS_VIEWPORT_WIDTH/CYPRESS_VIEWPORT_HEIGHT variables |
Run-level application configuration |
| Change headless screenshot or video output | before:browser:launch |
The browser’s display window or rendering surface, not Cypress’s application viewport |
In open mode, the runner can scale the preview to fit its pane. That visual scaling is only a presentation adjustment; it does not change the viewport dimensions reported to the application.
Resize the application in one test with cy.viewport()
Call the command before the assertions that depend on a breakpoint. Cypress accepts a numeric width and height in pixels:
#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
describe('responsive navigation', () => {
it('shows the desktop navigation at 1280px', () => {
cy.viewport(1280, 720)
cy.visit('/dashboard')
cy.get('[data-testid="desktop-nav"]').should('be.visible')
})
})The command changes the current test’s application viewport. It is suitable for checking a single breakpoint or for switching sizes during one scenario:
it('changes layout when the viewport crosses a breakpoint', () => {
cy.visit('/dashboard')
cy.viewport(390, 844)
cy.get('[data-testid="menu-button"]').should('be.visible')
cy.viewport(1280, 720)
cy.get('[data-testid="desktop-nav"]').should('be.visible')
})When you do not need an exact custom size, use a Cypress device preset. Presets provide dimensions and can be rotated with the orientation argument:
cy.viewport('iphone-6')
cy.viewport('iphone-6', 'landscape')The landscape form swaps the preset’s width and height. A preset is a viewport-size shortcut, not complete physical-device emulation: cy.viewport() does not simulate a device pixel ratio.
Set default dimensions in cypress.config.js or cypress.config.ts
Cypress’s documented default application viewport is 1000 by 660 pixels. Set your project’s normal test size in the root configuration file when most tests should use another dimension.
const { defineConfig } = require('cypress')
module.exports = defineConfig({
viewportWidth: 1280,
viewportHeight: 720,
e2e: {
setupNodeEvents(on, config) {
return config
},
},
})With TypeScript, the same properties go in defineConfig in cypress.config.ts:
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
import { defineConfig } from 'cypress'
export default defineConfig({
viewportWidth: 1280,
viewportHeight: 720,
e2e: {
setupNodeEvents(on, config) {
return config
},
},
})Cypress resets the viewport to the configured default between tests. A cy.viewport() call can still choose a different size for an individual test without changing the project-wide default.
Use a different size for one suite or one test
Keep mobile and desktop cases isolated by putting viewport settings in the suite or test configuration object. Cypress applies the setting only to that scope and then returns to the previous default.
describe(
'mobile checkout',
{
viewportWidth: 390,
viewportHeight: 844,
},
() => {
it('uses the mobile checkout layout', () => {
cy.visit('/checkout')
cy.get('[data-testid="mobile-summary"]').should('be.visible')
})
},
)
it(
'uses a tablet layout for this case only',
{ viewportWidth: 768, viewportHeight: 1024 },
() => {
cy.visit('/account')
cy.get('[data-testid="tablet-sidebar"]').should('be.visible')
},
)This approach is useful when a spec contains several responsive groups: each group states its dimensions next to the tests that need them, while unrelated tests continue to use the project default.
Override the size from the command line or environment
For a one-off run, pass both values through Cypress’s configuration override:
npx cypress run --config viewportWidth=1280,viewportHeight=720Cypress also documents environment-variable overrides named CYPRESS_VIEWPORT_WIDTH and CYPRESS_VIEWPORT_HEIGHT. They are useful in CI matrices where each job supplies a different size without editing the repository configuration. A command-line or environment override establishes the run’s default; a test-level configuration or cy.viewport() can still select a more specific size.
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.
Change the headless browser screen for screenshots and video
If the problem is the dimensions of a headless browser’s screenshot or video, configure the browser launch event. This setting controls the browser display surface and is independent of viewportWidth, viewportHeight, and cy.viewport().
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 matchIn cypress.config.js, add a before:browser:launch handler:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
on('before:browser:launch', (browser, launchOptions) => {
if (browser.family === 'chromium') {
launchOptions.args.push('--window-size=1440,900')
}
if (browser.family === 'electron') {
launchOptions.preferences.width = 1440
launchOptions.preferences.height = 900
}
return launchOptions
})
return config
},
},
})Use the browser-specific branch that matches the browser you run in CI. Cypress documents a 1280 by 720 headless screen and device pixel ratio 1 in its browser-launch guidance; those are headless rendering defaults, not the 1000 by 660 application-viewport defaults. If you set a 1440 by 900 browser window but leave the application viewport at 1000 by 660, the page can still lay out at 1000 by 660 inside that larger window.
What Cypress does—and does not—simulate
- CSS breakpoints: The application viewport supplied by
cy.viewport()or configuration is the value to use for responsive layout assertions. - Device pixel ratio: Viewport presets do not simulate a physical device’s DPR. A test at an iPhone preset size should not be described as complete hardware emulation.
- Runner appearance: Open Mode may shrink the preview to fit the runner pane. Inspect the configured values, not the preview’s on-screen scale.
- Browser display: Use
before:browser:launchwhen the required output is a particular headless screenshot or video canvas.
A practical responsive-test pattern
Keep the viewport choice close to the behavior being checked, and use a small set of intentional sizes rather than resizing after every assertion.
const cases = [
{ name: 'phone', width: 390, height: 844 },
{ name: 'tablet', width: 768, height: 1024 },
{ name: 'desktop', width: 1280, height: 720 },
]
describe('navigation at supported layouts', () => {
cases.forEach(({ name, width, height }) => {
it(`renders the ${name} navigation`, () => {
cy.viewport(width, height)
cy.visit('/dashboard')
cy.get('[data-testid="page-shell"]').should('be.visible')
})
})
})Use your product’s actual breakpoint contract for the numbers. The values above are examples of explicit test inputs, not a claim that every site should support those exact layouts.
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 →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
Troubleshooting common size problems
The page still looks mobile after setting a desktop size
- Confirm that the
cy.viewport()call runs before the responsive assertion (and, when practical, beforecy.visit()). - Check that you changed the application viewport, not only the headless window. A launch argument alone does not replace
cy.viewport(). - Look for a later command, suite setting, or test setting that overwrites the dimensions.
The screenshot or video has the wrong outer dimensions
Configure before:browser:launch for the browser family used by the run. Changing viewportWidth and viewportHeight changes page layout, but it does not necessarily change the browser display surface used for media output.
The open-mode preview appears smaller than expected
The runner scales the preview to fit its pane. Scaling is visual only; it does not alter the application viewport.
Cypress.config() throws when changing viewport dimensions
In Cypress 16.0.0 and later, changing viewportWidth or viewportHeight with Cypress.config() while a test is executing throws. Replace that runtime mutation with cy.viewport(), or put the dimensions in the test or suite configuration.
A preset does not match a real device screenshot
Presets provide dimensions and orientation only. They do not reproduce the device’s pixel ratio, browser chrome, or every hardware characteristic. Treat the result as a viewport-layout test.
CI and local runs use different sizes
Compare the committed config with any --config arguments and the CYPRESS_VIEWPORT_WIDTH/CYPRESS_VIEWPORT_HEIGHT environment variables supplied by CI. The most specific run or test setting is the one to investigate first.
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.
Or skip the browser setup
When the goal is a clean image or PDF of a URL rather than an interactive Cypress assertion, ScreenshotNeo returns the capture through one HTTP request. It accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the 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.
See the ScreenshotNeo documentation for all options, including device presets and custom viewports, full-page and element capture, lazy-image loading, dark mode, retina scale, PDF margins and page ranges, custom CSS or JavaScript, clicks, waits, blocked resources, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting, and the OpenAPI specification.
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}`);The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots, and every feature is included on every plan. Create a free ScreenshotNeo account to get the 1,000 monthly shots.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choosing the right Cypress setting
Use cy.viewport() for a dimension that belongs to one test, configuration properties for a project default, scoped configuration for a suite or test group, and before:browser:launch for the headless browser surface used by screenshots or video. Keeping those targets separate makes responsive assertions predictable and prevents a larger capture window from being mistaken for a larger application viewport.
Frequently Asked Questions
Can one Cypress test check several responsive sizes?
Yes. Call cy.viewport(width, height) before each layout assertion in the same test, or generate separate tests from a list of width-and-height cases when you want isolated failures.
Should I use a preset or explicit pixel values?
Use a preset when a named device layout is the requirement; use explicit dimensions when your application’s breakpoint or a screenshot specification requires exact pixels.
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.
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 →
