Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →To get higher-resolution Cypress screenshots in Jenkins, control four separate layers together: the application viewport, the CI virtual display, the browser’s device scale factor, and Cypress’s screenshot fitting mode. Set the viewport you actually need, give Xvfb a display at least that large, apply a deliberate Chromium scale-factor argument when appropriate, and capture with scale: false. Then use Cypress’s after:screenshot event to log the real file dimensions before Jenkins archives the screenshots.
Why changing viewportWidth alone often fails
Cypress’s documented default application viewport is 1000 × 660 pixels. viewportWidth and viewportHeight change the layout viewport used by your application; they do not simulate devicePixelRatio or guarantee that the PNG has matching physical dimensions.
The application runs inside an iframe in the browser window. When the available browser window or desktop is smaller than the requested content, Cypress can scale that iframe to fit. A larger CSS viewport can therefore still produce an unexpectedly sized image. Jenkins adds another constraint: headless or Xvfb-backed agents may expose fewer display pixels than the browser window you intend to use.
Treat the controls as different instruments:
| Control | What it changes | Where to set it | How to verify |
|---|---|---|---|
viewportWidth/viewportHeight |
Application layout viewport in CSS pixels | cypress.config.js or cy.viewport() |
Test configuration and screenshot dimensions |
| Xvfb display size | Physical desktop area available to the browser | Jenkins agent, Xvfb wrapper, or pipeline shell | Display configuration and after:screenshot output |
| Chrome device scale factor | Browser pixel density used when rendering | before:browser:launch |
Logged screenshot dimensions and optional pixelRatio |
Cypress scale |
Whether the application is fitted into the browser window | Cypress.Screenshot.defaults() or per-capture options |
scaled value from after:screenshot |
Increasing one layer while leaving another too small is the usual reason a Jenkins screenshot does not get larger.
Configure the viewport in Cypress
Set a project-wide viewport
const { defineConfig } = require('cypress')
module.exports = defineConfig({
viewportWidth: 1440,
viewportHeight: 900,
screenshotsFolder: 'cypress/screenshots',
e2e: {
setupNodeEvents(on, config) {
on('before:browser:launch', (browser, launchOptionsOrArgs) => {
if (browser.family === 'chromium') {
launchOptionsOrArgs.args.push('--force-device-scale-factor=1')
}
return launchOptionsOrArgs
})
},
},
})This establishes a 1440 × 900 application viewport and requests a Chromium device scale factor of 1. Use the current before:browser:launch callback shape for the Cypress major version installed on your agent: the callback argument has changed between releases. Confirm that the returned launch options are the ones your version expects.
Override a viewport for one test
it('renders the desktop checkout', () => {
cy.viewport(1440, 900)
cy.visit('/checkout')
cy.screenshot('checkout', { capture: 'viewport', scale: false })
})Document the target dimensions beside the test. A viewport is a layout contract, not a promise about the final PNG’s pixel density.
Give Jenkins a large enough virtual display
Run the browser on an Xvfb display whose width and height are at least as large as the browser window and the viewport you need. A common display specification is 1440x900x24, where the final number is color depth. The exact Jenkins syntax depends on the Xvfb plugin or Pipeline step installed on your controller.
If you manage Xvfb in a shell, the essential shape is:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsexport DISPLAY=:99
Xvfb :99 -screen 0 1440x900x24 >/tmp/xvfb.log 2>&1 &
XVFB_PID=$!
trap 'kill $XVFB_PID' EXIT
npm ci
npx cypress runDo not choose a display smaller than the browser window merely because the CSS viewport is smaller. Cypress or Chrome may fit the content and scale it. Keep the display dimensions stable between runs, especially for visual regression tests.
Choose the capture mode and scaling deliberately
Viewport capture
cy.screenshot('checkout', {
capture: 'viewport',
scale: false,
})This captures the application viewport without the Cypress command log.
Full-page capture
cy.screenshot('checkout-full-page', {
capture: 'fullPage',
scale: false,
})Use this when the evidence must include the entire application page. Lazy-loaded content may need to be made visible or otherwise loaded before capture.
Runner capture
capture: 'runner' includes the Cypress UI. Runner captures are always coerced to scaled mode, so they are not the right choice when your goal is an unscaled application image. Use them only when the command log or runner chrome is part of the evidence.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
The scale option controls fitting the application into the browser viewport. It is not a substitute for a larger Xvfb display or a browser device scale factor. You can set a project default with Cypress.Screenshot.defaults(), but per-test options make the intended behavior easier to audit.
Apply the browser device-scale setting
For Chromium browsers, add --force-device-scale-factor=1 through Cypress’s browser-launch hook when you need predictable physical pixels. The example configuration above applies it only when browser.family === 'chromium'. Avoid assuming that a launch argument was accepted: log the resulting screenshot metadata and inspect a file from the Jenkins workspace.
A scale factor of 1 is useful for deterministic, one-CSS-pixel-to-one-device-pixel output. If you intentionally need higher-density output, choose and document the factor supported by your browser and agent image, then verify the resulting dimensions rather than inferring them from the viewport setting.
Make captures reproducible for visual comparisons
Cypress recommends generating and comparing screenshots in the same environment. Pin the Jenkins container or agent image, Cypress version, browser version, installed fonts, viewport, Xvfb dimensions, and relevant browser arguments. Operating-system differences, font substitution, browser updates, and display scaling can alter pixels even when application code is unchanged.
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 & 11Crashes, 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 minute- Use a fixed viewport for baseline and comparison runs.
- Keep the same browser family and version on every agent.
- Install the same fonts and locale data.
- Keep Xvfb dimensions and color depth constant.
- Disable animations or wait for the application’s stable state before capture.
- Use a selector wait, a deliberate delay, or network-idle strategy where asynchronous content would otherwise race the screenshot.
Verify the actual PNG dimensions
The after:screenshot event exposes the saved path, dimensions, scaled state, and optional pixelRatio. Log those values instead of trusting configuration:
// cypress.config.js
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
on('after:screenshot', (details) => {
console.log(JSON.stringify({
path: details.path,
width: details.width,
height: details.height,
scaled: details.scaled,
pixelRatio: details.pixelRatio,
}))
})
},
},
})Property availability can vary by Cypress version, so tolerate an absent pixelRatio. Compare the logged width and height before and after your Jenkins changes. Cypress writes screenshots to cypress/screenshots by default, or to the directory named by screenshotsFolder.
Archive screenshots even when tests fail
Failure screenshots are taken during cypress run by default. Put artifact publication in a Jenkins post/finally path so a failed test still leaves evidence:
pipeline {
agent any
stages {
stage('Cypress') {
steps {
sh 'npm ci'
sh 'npx cypress run'
}
}
}
post {
always {
archiveArtifacts artifacts: 'cypress/screenshots/**/*', allowEmptyArchive: true
}
}
}Keep the artifact path stable across agents. If you changed screenshotsFolder, archive that configured path instead.
Free tools Windows power users keep installed
One-click scans. No signup required.
Troubleshoot common resolution problems
The PNG is still the old size
Check all four layers: the test may override the configured viewport; Xvfb may be smaller than the browser window; the launch hook may not match your Cypress version; or scale may still be fitting content. Read the after:screenshot log and inspect the archived file.
The browser will not start after adding the flag
The callback signature or launch-options object may differ in your installed Cypress major version. Use that version’s before:browser:launch signature, add the argument to the browser-family branch only, and return the object Cypress expects.
Full-page output is unexpectedly tall or clipped
Confirm that you selected capture: 'fullPage', wait for lazy content to load, and ensure the application has reached a stable layout before capture. A larger viewport does not replace full-page capture.
Runner screenshots remain scaled
This is expected: runner captures are always scaled. Capture the application with viewport or fullPage when unscaled output is required.
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 →Images differ between Jenkins agents
Compare browser and Cypress versions, fonts, operating-system image, Xvfb size, device scale factor, locale, and timing. Pin the agent image and make waits deterministic before changing screenshot dimensions again.
No screenshots are available as a build artifact
Verify that Cypress ran in cypress run mode, that the configured folder matches the archive pattern, and that archiving runs under post { always { ... } } (or the equivalent finally handling).
Performance and cost considerations
Larger viewport and full-page images contain more pixels, increasing file size and archive time. Full-page captures also require the page to render and load more content. Use viewport captures for focused evidence, reserve full-page images for cases that need them, and avoid rerunning an entire suite merely to inspect dimensions. A single metadata log from after:screenshot is cheaper and more reliable than manually opening every artifact.
Or skip the browser setup
For server-side captures, ScreenshotNeo accepts one request and returns a PNG, JPEG, WebP, or PDF. Its preprocessing accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response reports the result with X-Page-Verdict and X-Billed headers. It also provides an MCP server for AI agents, including Claude, Cursor, and other MCP clients.
See the ScreenshotNeo documentation for all options, including viewport and device presets, full-page and element capture, dark mode, retina scale, custom CSS and JavaScript, waits, request blocking, headers and cookies, geolocation, transparent backgrounds, resizing, TTL caching, signed links, asynchronous webhooks, bulk capture, usage, 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 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free. Create a free ScreenshotNeo account to try it.
FAQ
What is the default Cypress viewport?
Cypress documents a default application viewport of 1000 × 660 pixels. Set explicit dimensions when screenshot size matters.
Should I use a retina device scale factor?
Only when you need higher-density output and can keep that setting consistent across agents. Verify the resulting dimensions and pixel ratio rather than relying on the viewport numbers.
Where should Jenkins store screenshots?
Use the configured screenshotsFolder; the default is cypress/screenshots. Archive it in an always-run post or finally block.
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.
