What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Set CYPRESS_VIEWPORT_WIDTH and CYPRESS_VIEWPORT_HEIGHT before Cypress starts. They override viewportWidth and viewportHeight in cypress.config.js or cypress.config.ts for that run:
CYPRESS_VIEWPORT_WIDTH=1280 CYPRESS_VIEWPORT_HEIGHT=800 cypress runThis changes the application layout viewport. It does not automatically enlarge the browser display, crop a saved image, or guarantee a larger file. Those are separate controls.
Set the viewport with environment variables
Cypress maps the two environment variables directly to its viewport configuration. Command-line values take precedence over values in your project configuration, so you can use one configuration file and select a size in local development or CI.
CYPRESS_VIEWPORT_WIDTH=1280 CYPRESS_VIEWPORT_HEIGHT=800 cypress runThe example requests a 1,280 × 800 CSS-pixel application viewport for the complete run. On a POSIX shell, place both assignments immediately before cypress run. In a CI job, put the same names in the job’s environment section or export them in the step that launches Cypress. In PowerShell, set the variables for the process before starting Cypress:
$env:CYPRESS_VIEWPORT_WIDTH='1280'
$env:CYPRESS_VIEWPORT_HEIGHT='800'
npx cypress runUse the same variable names in every environment. A missing value leaves that dimension at the configured value, so define both dimensions when deterministic screenshots matter.
Set a project default in configuration
For a permanent default, put the values in your Cypress configuration:
import { defineConfig } from 'cypress'
export default defineConfig({
viewportWidth: 1280,
viewportHeight: 800,
})The configuration reference documents that command-line environment variables override viewportWidth and viewportHeight options: Cypress configuration.
Know which kind of “resize” you need
A screenshot can look different for four separate reasons. Choose the control that matches the result you need rather than changing the viewport for every problem.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →| Control | When it takes effect | What it changes | Does it change layout? | Deterministic file dimensions in CI |
|---|---|---|---|---|
CYPRESS_VIEWPORT_WIDTH and CYPRESS_VIEWPORT_HEIGHT |
Before the run; run-wide | The application viewport used by the browser | Yes | Only when the browser display and rendering environment are also controlled |
cy.viewport(width, height) |
During a test, at the command’s position | The application viewport for subsequent commands | Yes | Usually, provided the display is not limiting the capture |
cy.screenshot({ clip }) |
At screenshot time | The rectangle copied into the image | No | Yes for the requested rectangle, subject to device-pixel and browser behavior |
element.screenshot({ padding }) |
At element screenshot time | The element image bounds plus padding | No | Yes when the element’s rendered size is stable |
scale: true |
At capture time | Fits a viewport or full-page capture into the browser viewport | No; it scales the capture | No, if exact source pixels are required |
The command and API references describe these screenshot controls: cy.screenshot() and the Cypress screenshot API.
Change layout dimensions for a test
Use cy.viewport() when one test must exercise several responsive breakpoints:
describe('responsive layout', () => {
it('captures the compact layout', () => {
cy.viewport(400, 1000)
cy.visit('/')
cy.screenshot('compact')
})
it('captures the desktop layout', () => {
cy.viewport(1280, 800)
cy.visit('/')
cy.screenshot('desktop')
})
})Cypress restores the configured default between tests. For a suite or test-specific size, use Cypress’s configuration object instead of changing global configuration at runtime:
describe('medium screen', { viewportWidth: 400, viewportHeight: 1000 }, () => {
it('renders the compact layout', () => {
cy.visit('/')
})
})Starting in Cypress 16.0.0, viewportHeight and viewportWidth cannot be set with Cypress.config() while a test is executing. Use cy.viewport() or suite/test configuration instead. The current API guidance is in the cy.viewport() documentation.
Crop a saved screenshot without changing the page
If the page layout is correct but the output must be an exact rectangle, use clip:
cy.screenshot('card-area', {
clip: { x: 20, y: 20, width: 400, height: 300 },
})This captures the specified coordinates; it does not make the application believe its viewport is 400 × 300. Use this approach for a stable region such as a chart, card, or toolbar.
Include breathing room around one element
For an element-level capture, padding expands the image bounds around that element:
cy.get('.post').screenshot('post-with-padding', { padding: 10 })Padding changes the captured rectangle only. It does not add CSS margin or alter responsive breakpoints.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Understand the effect of scale
scale: true fits a viewport or full-page capture into the available browser viewport. Cypress coerces scale to true for runner captures. Scaling is useful when the complete page must be visible in a constrained display, but it is not a method for obtaining native, exact pixel dimensions.
Why a larger viewport may not create a larger image file
Cypress renders the application viewport inside a real browser and iframe. If that viewport is larger than the available browser display, Cypress can scale it to fit. Consequently, changing environment variables alone may change responsive layout while leaving the output image smaller than expected.
There are two layers to coordinate:
- Application viewport: set with environment variables, project configuration,
cy.viewport(), or suite/test configuration. - Browser display: set through the
before:browser:launchnode event when the display is the limiting layer.
The browser-launch API is documented at before:browser:launch. Cypress’s high-resolution guidance explains the same distinction in Generate High-Resolution Videos and Screenshots (published August 26, 2020). That article’s approach should be reconciled with the current command and configuration documentation when behavior differs by Cypress version.
Do not rely on scale when exact pixels are the acceptance criterion. Inspect the dimensions reported by the screenshot callback or your image pipeline and adjust both viewport and browser display until they match the required output.
Recommended Free Tools
A repeatable CI setup
- Choose one explicit target. For example, use 1280 × 800 for a desktop baseline and a separate 400 × 1000 suite for a compact layout.
- Set both environment variables in the job. This keeps the run independent of a developer’s local configuration file.
- Pin the browser and operating system image. Font availability, browser versions, display scaling, and operating-system rendering can change pixels even when application code is unchanged.
- Control the display when resolution matters. Configure the browser launch dimensions through
before:browser:launchrather than assuming the application viewport controls the display. - Capture after the page is ready. Wait for the application’s stable state before calling
cy.screenshot(); otherwise timing differences can look like viewport differences. - Record the resulting dimensions. Treat the callback or image inspection result as the source of truth, especially when a runner or full-page capture may be scaled.
Cypress recommends setting an explicit, consistent viewport for visual testing. Keep the browser, OS, fonts, and display conditions stable for baseline comparisons; see Visual testing in Cypress.
Common problems and fixes
The environment variable appears to be ignored
Check spelling and placement first. The names must be exactly CYPRESS_VIEWPORT_WIDTH and CYPRESS_VIEWPORT_HEIGHT, and they must exist in the same process that launches Cypress. Confirm that a later script, matrix value, or shell step is not replacing them. Because command-line values override configuration, a correctly supplied variable should win over cypress.config.js or cypress.config.ts.
The layout changes, but the file dimensions do not
This usually means the browser display is constraining the application viewport or the capture is being scaled. Configure the browser’s launch dimensions, avoid scale for pixel-exact output, and inspect the dimensions reported by the screenshot callback.
A runtime call does not change the viewport
Use cy.viewport(width, height) in the command chain. Do not call Cypress.config('viewportWidth', ...) during a test on Cypress 16 or later; current Cypress documentation says runtime changes through Cypress.config() are not supported for these options.
Free tools Windows power users keep installed
One-click scans. No signup required.
The crop is the wrong size
Verify that clip.x and clip.y are relative to the captured page coordinates and that the requested rectangle lies within the rendered content. If the goal is to enlarge an element’s surrounding area, use element padding instead of a clip rectangle.
Visual diffs occur only in CI
Compare the browser version, operating-system image, installed fonts, display scaling, viewport variables, and browser launch dimensions. A fixed application viewport cannot compensate for differences in those rendering inputs.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup: ScreenshotNeo
If you need a website image rather than a Cypress test artifact, ScreenshotNeo returns a PNG, JPEG, WebP, or PDF from one GET request. It handles the browser layer for you and exposes options such as 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, click-before-capture, selector or network-idle waits, ad/tracker/request blocking, custom headers and cookies, user agents, Authorization, timezone and geolocation, transparent backgrounds, resizing, TTL-based caching, signed public image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Parameter names used by other screenshot APIs also work, which can simplify migration.
Example request (the API key is sent as a query parameter):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for authentication, output and option details. Equivalent Python:
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)Equivalent 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 accepts the consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be disabled. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and every response identifies the page verdict and billing state with X-Page-Verdict and X-Billed headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
| Plan | Included shots | Price |
|---|---|---|
| Free | 1,000 per month | $0, no card |
| Starter | 3,000 | $5 |
| Growth | 15,000 | $15 |
| Pro | 60,000 | $39 |
| Scale | 250,000 | $99 |
| Business | 1,000,000 | $249 |
Every feature is available on every plan, and yearly billing gives two months free. Start with 1,000 free screenshots a month with no card; paid plans start at $5 for 3,000.
Frequently Asked Questions
What is Cypress’s default viewport size?
Current Cypress documentation lists a default viewport of 1000 × 660 pixels before a test changes it.
Can I use environment variables and suite configuration together?
Yes. Environment variables provide the run-level override, while suite or test configuration scopes a different viewport to selected tests. Use the scope that matches the comparison you are making.
Which setting should I use for an exact 400 × 300 image?
Use a 400 × 300 clip rectangle when you want to crop an existing layout. Set the application viewport to 400 × 300 instead when you want responsive CSS to render for that size.
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.
