Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use cypress run in your CI job. Cypress launches the selected browser headlessly by default, so no visible desktop is required. A dependable pipeline installs Cypress and the browser, starts the application, waits for a real readiness check, then runs the tests. Keep a headed command for diagnosing differences.

How do I run Cypress headlessly in CI?

Install Cypress as a development dependency with your project’s existing package manager, install or select a browser available on the runner, and invoke the CLI:

npm install --save-dev cypress
npx cypress run

cypress run executes specs to completion in headless mode. cypress open is the interactive, headed interface. To see a CLI run while retaining the same command flow, add --headed:

npx cypress run --browser chrome --headed --no-exit

Replace chrome with an installed supported browser, such as Firefox. Cypress documents Chrome-family browsers and Firefox; WebKit support is experimental. Check the current browser-launching reference before standardizing a browser in a long-lived pipeline.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
#1 Best Overall
Elebase USB to USB C Adapter for iPhone 18 Pro Max,USBC Car Charger Adapter
  • Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
  • Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
  • Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
  • Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
  • 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.

The CI sequence that avoids race conditions

A headless test is only as reliable as the environment around it. The tested site must be running and accepting requests before Cypress starts.

  1. Install dependencies. Run your normal lockfile-based install and install Cypress in the project.
  2. Provide a browser. Use a runner image with Chrome, Chrome for Testing, Firefox, or another supported browser. A Cypress Docker image can supply Linux prerequisites and browsers.
  3. Start the application. Launch the local server or target a deployed preview.
  4. Wait for readiness. Poll the URL or health endpoint with a readiness tool instead of using an arbitrary sleep.
  5. Run Cypress. Set the base URL and execute cypress run.
  6. Upload artifacts. Preserve failure screenshots, and enable video only when its diagnostic value justifies storage and encoding time.

Starting a server in the background and immediately running Cypress (for example, npm start && npx cypress run) can create a race: the process may exist while the HTTP server is still compiling. Cypress’s CI guidance recommends a readiness-checking tool; the official GitHub Action exposes start and wait-on options.

Example GitHub Actions job

name: e2e
on: [push, pull_request]
jobs:
  cypress:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - name: Run Cypress
        uses: cypress-io/github-action@v6
        with:
          start: npm run dev -- --host 0.0.0.0
          wait-on: http://127.0.0.1:3000
          browser: chrome
          command: npx cypress run

Adjust the start command, port, Node version, and action version to your repository. If the job tests a preview or staging deployment, set CYPRESS_BASE_URL in the job environment instead of starting a local server:

env:
  CYPRESS_BASE_URL: https://preview.example.test

Browser selection and reproducibility

Browser choice affects rendering, APIs, timing, and the confidence your suite provides. Chrome for Testing is a useful default when available because its versioned binaries do not silently auto-update, improving repeatability. That is a reproducibility recommendation, not a reason to ignore browsers your users depend on.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Policy When it fits Trade-off
One primary browser Fast feedback for every commit Less coverage of browser-specific defects
Primary plus critical paths on secondary browsers Most teams balancing risk and CI time More setup and runtime
Full suite on every supported browser High-risk, browser-sensitive products Highest infrastructure and artifact cost

Choose a policy based on user traffic and product risk. The runner must actually contain the requested browser; a command such as --browser firefox cannot download a missing binary by itself.

Headless display versus application viewport

Two dimensions are easy to confuse:

  • Browser display defaults: Cypress documents 1280×720 screen size and device pixel ratio 1 for headless browser launches.
  • Application viewport: viewportWidth and viewportHeight control the page’s emulated content area.

They are independent. A test can use a 1280×720 browser display while the application viewport is configured to 1000×800. If screenshot or video framing must match a target, configure the browser display in before:browser:launch and set the application viewport separately.

Rank #2
Anker USB-C Hub, 5-in-1 USB Hub for Laptops, 4K HDMI Multiport Adapter
  • 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
  • 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
  • Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
  • 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
  • What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
// cypress.config.js
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  viewportWidth: 1280,
  viewportHeight: 800,
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
        if (browser.family === 'chromium' && browser.isHeadless) {
          launchOptions.args.push('--window-size=1440,900')
        }
        return launchOptions
      })
    }
  }
})

Use the browser family and headless flags supplied by Cypress rather than assuming every runner uses the same executable name. Keep display settings in version control so local and CI artifacts are comparable.

Screenshots, videos, and retained artifacts

During cypress run, Cypress automatically captures a screenshot when a test fails unless you disable that behavior. Screenshots and videos are written to their configured folders. Cypress clears those folders before a run by default, so upload artifacts after the command or change the folder strategy if earlier runs must be retained.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Videos are opt-in:

// cypress.config.js
const { defineConfig } = require('cypress')
module.exports = defineConfig({
  video: true,
  videoCompression: 32,
  screenshotsFolder: 'cypress/screenshots',
  videosFolder: 'cypress/videos'
})

Video recording and compression consume CPU, time, and storage. Enable them for CI branches where replay is valuable, or conditionally for retries and failures, rather than treating recording as free. Upload only the folders your CI system needs.

Diagnosing headed/headless differences

A passing headed run and a failing headless run (or the reverse) is a signal to compare environments, not proof of one specific bug. Reproduce the exact browser and spec visibly:

npx cypress run --browser chrome --spec "cypress/e2e/cart.cy.js" --headed --no-exit
  1. Run the same spec headlessly and headed with the same browser family and configuration.
  2. Compare failure screenshots and, when enabled, video.
  3. Check browser versions, viewport settings, device pixel ratio, environment variables, network access, and available CPU or memory.
  4. Look for timing assumptions, animations, lazy content, and selectors that depend on an element being visible at a particular moment.
  5. Use Cypress Test Replay when available to inspect the recorded DOM, network requests, console logs, JavaScript errors, and rendering.

These checks can expose timing, rendering, browser-version, or runner-environment differences. They are diagnostic possibilities, not guaranteed causes. Fix the underlying synchronization or environment mismatch instead of adding a larger unconditional delay.

Common CI failures and fixes

“Cypress cannot find the browser”

Cause: The runner image does not contain the browser named by --browser. Fix: Install that browser, select one already present, or use a Cypress image that includes the required Linux libraries and browser.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #3
Sale
Anker USB C Hub, 7in1 Multi-Port USB Adapter, 4K@60Hz USBC to HDMI Splitter
  • Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
  • Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
  • Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
  • Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
  • What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.

Connection refused or blank page at startup

Cause: Cypress started before the application was ready, or the server bound to a different host or port. Fix: Verify the URL from inside the runner, bind the server to an accessible interface, and use a polling readiness check.

Tests pass locally but time out in CI

Cause: Slower CPU, cold builds, missing environment variables, blocked services, or resource contention. Fix: Log the resolved base URL and browser version, wait on the actual dependency, and investigate service reachability before increasing timeouts.

Artifacts are missing after a failed job

Cause: The CI workflow did not upload files after a non-zero Cypress exit, or a later step cleared the artifact folder. Fix: Configure artifact upload with an “always” condition and upload the configured screenshots and videos directories.

Headless screenshots look cropped or differently scaled

Cause: Browser display dimensions and application viewport dimensions were configured independently. Fix: Set both explicitly and account for device pixel ratio when comparing images.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Video makes the job too slow

Cause: Encoding and file transfer add work. Fix: Record only selected jobs or specs, tune compression, and retain screenshots for routine failures.

Performance, reliability, and cost decisions

There is no universal “headless is X percent faster” figure here: runtime depends on the browser, application, server, test count, video workload, and runner resources. Optimize the system you actually operate.

Rank #4
Sale
UGREEN USB to USB C Adapter Combo 4-Pack, 10Gbps USB C Converter Space Gray
  • Dual Converters, Infinite Potential:Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
  • Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
  • Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
  • Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
  • Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
  • Reduce avoidable waiting: wait for network or application state rather than fixed sleeps.
  • Control parallelism: split specs only when the runner and backend can handle concurrent browsers.
  • Pin versions: lock Node, Cypress, and browser images to make failures reproducible.
  • Separate feedback tiers: run smoke tests on every change and broader cross-browser coverage on protected branches or scheduled jobs.
  • Budget artifacts: screenshots are automatic on failure; videos require explicit storage and encoding capacity.

Containerized headless execution on Linux can work without an extra display server when prerequisites are present. Interactive cypress open in a container does require a graphical display. Memory and CPU needs vary with browser, application, server, and video recording.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Or skip the browser setup

For a single URL, preview pipeline, or automation service, ScreenshotNeo provides a website screenshot API and MCP server. One request returns PNG, JPEG, WebP, or PDF. It accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

API documentation: https://screenshotneo.com/docs/

cURL

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

Python

import requests
r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo also supports full-page captures with lazy images loaded, CSS-selector element shots, dark mode, 12 device presets and custom viewports, retina scale, PDFs with paper size, margins, landscape and page ranges, HTML/CSS-to-image, custom CSS and JavaScript, clicks before capture, hidden selectors, waits for selectors, delays or network idle, request and resource blocking, custom headers, cookies, user agents and Authorization, timezone and geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed public-image links, asynchronous jobs with signed webhooks, bulk capture of 100 URLs per call, a usage API, an OpenAPI specification, and familiar parameter names for easier migration. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.

Plans include 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 shots. Every feature is on every plan, and yearly billing provides two months free. Create a free ScreenshotNeo account to get started.

FAQ

Can I run Cypress headlessly against a deployed site?

Yes. Set CYPRESS_BASE_URL to the preview or staging URL and omit the local server step. Ensure the runner can resolve and reach that deployment.

Does headless mode mean the page has no viewport?

No. Headless describes the absence of a visible desktop window. Cypress still launches a browser with display defaults, while viewportWidth and viewportHeight define the application’s content area.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Should every CI run record video?

No. Videos are disabled by default and add encoding and storage work. Enable them where replay materially improves diagnosis, while relying on automatic failure screenshots for routine evidence.

Best Value
Anker USB C Hub, 5-in-1 USBC to HDMI Splitter with 4K Display
  • 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
  • Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
  • Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
  • HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
  • What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.

Is WebKit suitable as the only Cypress browser?

WebKit support is experimental. Use supported Chrome-family or Firefox coverage for your primary policy, and add experimental browsers only when their risk and maintenance cost are acceptable.

Frequently Asked Questions

Can I run Cypress headlessly against a deployed site?

Yes. Set CYPRESS_BASE_URL to the preview or staging URL and ensure the CI runner can reach it.

Does headless mode mean the page has no viewport?

No. Headless removes the visible window; Cypress still has browser display defaults and a separately configurable application viewport.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Should every CI run record video?

No. Video is opt-in and adds encoding and storage work; failure screenshots are captured automatically during cypress run.

Is WebKit suitable as the only Cypress browser?

WebKit support is experimental. Use supported Chrome-family or Firefox coverage as your primary policy unless your project accepts that risk.

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.