How to Set the Viewport in Cypress

Use cy.viewport(width, height) to change the browser viewport during a Cypress test, for example cy.viewport(1280, 720). Set viewportWidth and viewportHeight in Cypress configuration for project-wide defaults. Use suite- or test-specific configuration when only part of the test suite needs different dimensions.

Cypress’s documented default viewport is 1000 × 660 pixels. A viewport preset such as iphone-6 is a convenient width-and-height shortcut, but it does not reproduce every behavior of a physical phone: Cypress does not simulate devicePixelRatio or run native mobile apps.

1. Change the viewport in a test with cy.viewport()

Pass a width and height in CSS pixels to set an exact viewport size:

describe('responsive navigation', () => {
  it('shows the desktop navigation at 1280 × 720', () => {
    cy.viewport(1280, 720);
    cy.visit('/');

    cy.get('[data-cy="desktop-nav"]').should('be.visible');
    cy.get('[data-cy="mobile-menu-button"]').should('not.be.visible');
  });
});

Call cy.viewport() from the Cypress command chain. It yields null, so there is no viewport value to assert on or chain into another assertion. Set the viewport before visiting the page when you want the application to initialize at those dimensions.

Use a named device preset

Presets select documented width and height values. The orientation defaults to portrait:

cy.viewport('iphone-6');
cy.visit('/');

cy.viewport('iphone-6', 'landscape');
cy.visit('/');

Landscape reverses the preset’s width and height. Use numeric dimensions when you need a precise breakpoint size that is not a preset.

Preset	Documented dimensions (portrait)
`ipad-2`, `ipad-mini`	768 × 1024
`iphone-3`, `iphone-4`	320 × 480
`iphone-5`	320 × 568
`iphone-6`, `iphone-7`, `iphone-8`, `iphone-se2`	375 × 667
`iphone-6+`	414 × 736
`iphone-x`	375 × 812
`iphone-xr`	414 × 896
`samsung-note9`	414 × 846
`samsung-s10`	360 × 760
`macbook-11`	1366 × 768
`macbook-13`	1280 × 800
`macbook-15`	1440 × 900
`macbook-16`	1536 × 960

Preset names and dimensions are Cypress API details that may change between versions. Check the current cy.viewport() API reference before relying on a particular preset.

Pass command options

The documented numeric and preset forms accept an options object as well. For example, disable command logging for a specific viewport change with log: false:

cy.viewport(1280, 720, { log: false });
cy.viewport('iphone-6', 'landscape', { log: false });

The API also documents timeout as a command option. In normal cases, use the default timeout; adjust it only if the command itself is timing out in your setup. See the current API reference for the complete option definitions for your Cypress version.

2. Set project-wide viewport defaults

Configure viewportWidth and viewportHeight in the Cypress configuration file. For example, in cypress.config.js:

const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    viewportWidth: 1280,
    viewportHeight: 720,
  },
});

For an ESM configuration file, use imports and exports:

import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    viewportWidth: 1280,
    viewportHeight: 720,
  },
});

These values become defaults for tests in that project. Cypress resets the viewport between tests, so a viewport change made in one test does not silently become the next test’s starting size.

Override dimensions from the command line

Use the --config option to override configuration for one run:

npx cypress run --config viewportWidth=1280,viewportHeight=720

This can be useful in CI when the same test suite needs a particular fixed viewport. Cypress also supports environment variables such as CYPRESS_VIEWPORT_WIDTH and CYPRESS_VIEWPORT_HEIGHT to override configured values. Configuration precedence and file details are documented in Cypress configuration.

3. Scope dimensions to a suite or test

Use test-specific configuration when a group of tests should share dimensions without changing the project default. Cypress applies the scoped values to the matching suite or test and returns to the previous configuration afterward. The exact syntax depends on your Cypress version; consult the configuration reference for the supported test configuration format.

For a responsive check that needs several widths within one test, change the viewport explicitly for each state:

it('adapts navigation at the mobile and desktop breakpoints', () => {
  cy.visit('/');

  cy.viewport(375, 812);
  cy.get('[data-cy="mobile-menu-button"]').should('be.visible');
  cy.get('[data-cy="desktop-nav"]').should('not.be.visible');

  cy.viewport(1280, 720);
  cy.get('[data-cy="desktop-nav"]').should('be.visible');
  cy.get('[data-cy="mobile-menu-button"]').should('not.be.visible');
});

If the application only calculates layout at startup, visit or reload after changing the viewport so the app can initialize against the new dimensions. Otherwise, assert that the layout updates after the resize.

4. Choose dimensions for responsive tests

Pick widths that exercise the breakpoints your application actually defines. Device presets are recognizable examples, but a breakpoint-focused test is often more precise: test just below and above a CSS breakpoint to catch off-by-one behavior.

const mobileBreakpoint = 768;

it('switches layout at the tablet breakpoint', () => {
  cy.visit('/');

  cy.viewport(mobileBreakpoint - 1, 900);
  cy.get('[data-cy="compact-layout"]').should('be.visible');

  cy.viewport(mobileBreakpoint, 900);
  cy.get('[data-cy="wide-layout"]').should('be.visible');
});

Use your app’s real breakpoint and expected selectors in place of the example. A useful coverage set commonly includes narrow mobile, a width near each important breakpoint, and desktop. Avoid adding every possible size if it does not exercise a distinct layout state.

Viewport size is not the Cypress runner window

The Cypress app may scale and center the application preview to fit the available runner window. That visual scaling does not change the application’s viewport calculations. Distinguish the viewport you set in the test from the runner’s zoomed preview when diagnosing apparent size differences. See Cypress open mode.

Viewport emulation is not a physical device

A mobile-sized viewport is useful for testing responsive web layouts, but it does not simulate devicePixelRatio. It also does not turn Cypress into a native iOS or Android app test runner. Cypress’s FAQ explains its native app limitation in Frequently asked questions.

5. Keep screenshot comparisons repeatable

For visual regression checks, use the same viewport dimensions and a consistent environment for both the baseline and the comparison capture. Otherwise, a difference in viewport, browser, fonts, or rendering environment can appear as a page change. Cypress recommends controlling the environment and viewport for screenshot comparisons in its visual testing guide.

it('renders the pricing page at a fixed size', () => {
  cy.viewport(1280, 800);
  cy.visit('/pricing');
  cy.get('main').screenshot('pricing-desktop');
});

This captures a Cypress screenshot at a controlled viewport. If you need a screenshot of a live website without managing a Cypress browser run, ScreenshotNeo is a website screenshot API and MCP server from ScreenshotNeo.

Or skip the browser setup

For a website capture, use ScreenshotNeo’s one-request API. The examples save the response body as an image; see the ScreenshotNeo API documentation for request parameters and response behavior.

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

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)

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(`ScreenshotNeo returned ${res.status}`);
await import('node:fs/promises').then(({ writeFile }) =>
  writeFile('shot.webp', Buffer.from(await res.arrayBuffer()))
);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. Plans include 1,000 screenshots per month free with no card, then paid plans starting at $5 for 3,000 screenshots. Every feature is on every plan.

Troubleshooting

Symptom	Likely cause	Fix
`cy.viewport()` rejects the dimensions	The width or height is not a finite, non-negative number, or the arguments do not match a documented signature.	Pass numeric pixel dimensions such as `cy.viewport(1280, 720)`, or use a valid preset and optional orientation.
The page still looks small in the Cypress app	The runner is scaling and centering the preview to fit its window.	Check the application’s actual responsive behavior with assertions. The runner preview scale does not change the app’s viewport calculations.
The next test starts at a different size than expected	Cypress resets the viewport between tests; a prior in-test resize is not a project default.	Set project defaults in configuration or call `cy.viewport()` in each test that needs a custom size.
Changing `Cypress.config()` for viewport dimensions throws	From Cypress 16.0.0, viewport dimensions cannot be changed through `Cypress.config()` while a test is executing.	Use `cy.viewport()` for an in-test change, or test-specific configuration for scoped dimensions.
A preset is not recognized or behaves differently	The preset name or dimensions differ in the Cypress version installed.	Check the current viewport API reference, or use explicit numeric dimensions.
The responsive page does not update after resizing	The app may calculate layout only during initialization, or an assertion may run before the resulting UI update.	Visit or reload at the target dimensions if layout is initialization-based; otherwise wait on an observable UI condition and assert the resulting state.
Visual snapshots differ across machines	Viewport, browser, fonts, or other rendering conditions are inconsistent.	Fix the viewport and keep the screenshot generation and comparison environments consistent.

Performance, reliability, and cost

cy.viewport() changes the browser’s viewport within an existing test run; it does not itself visit a URL or capture a screenshot. A practical responsive suite covers meaningful breakpoints without repeating equivalent sizes. Keep the viewport fixed for visual comparisons so that size is not a moving variable.

For Cypress viewport behavior, the relevant operational detail is repeatability: set the needed dimensions in configuration or each test, account for Cypress’s reset between tests, and keep screenshot environments consistent. The cited Cypress documentation does not give a cost or performance benchmark for viewport changes.

ScreenshotNeo is a separate option when the task is capturing a website image or PDF rather than testing application behavior inside Cypress. Its free plan includes 1,000 shots monthly without a card; paid plans are Starter $5 for 3,000, Growth $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000, and Business $249 for 1,000,000. Yearly billing gives two months free. See the docs for API options and billing headers.

FAQ

Can I set different viewport sizes in one Cypress test?

Yes. Call cy.viewport() again with the next dimensions, then assert the layout for that state.

Does a mobile preset test a native mobile app?

No. It sets a browser viewport for mobile web layout checks. Cypress does not run native mobile apps, and viewport presets do not simulate devicePixelRatio.

Can I use a viewport preset with landscape orientation?

Yes. Pass 'landscape' as the second argument; Cypress swaps the preset’s width and height.

Can I change the viewport using Cypress.config() during a test?

Not from Cypress 16 onward. Use cy.viewport() for a change during the running test.