What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Put a .gitlab-ci.yml file in your repository, install dependencies in a CI job, start the application, and run your Cypress end-to-end script. Begin with one worker; use a Cypress browser image when you need a specific browser, and add multiple workers only when you are ready to record runs with Cypress Cloud.
Start with a single-worker GitLab CI job
GitLab reads pipeline configuration from .gitlab-ci.yml at the repository root. Cypress’s basic GitLab example uses a Node image, installs packages with npm ci, starts the app in the background, then invokes the project’s end-to-end script:
As an Amazon Associate I earn from qualifying purchases.
stages:
- test
test:
image: node:latest
stage: test
script:
- npm ci
- npm start &
- npm run e2eThis is a starting point, not a universal recipe. Your package.json must define an e2e script that runs Cypress, and the app must be reachable at the URL configured for the tests. For example, a project might define "e2e": "cypress run" if Cypress is installed and configured in that repository.
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 →Starting a process with & does not establish that it is ready to serve requests. If the app takes time to boot, add a readiness check appropriate to your project before running Cypress; otherwise, tests may race the server and fail before the first page loads. GitLab and Cypress do not require one particular readiness-check tool for this pattern.
Choose an image that matches the browser under test
A Node image is suitable only if the environment provides the Cypress runtime and browser dependencies your tests need. If the job must use an installed browser such as Chrome or Firefox, use a Cypress browser image and explicitly select the browser in the Cypress command. Cypress’s GitLab guide demonstrates the cypress/browsers:22.15.0 image tag with Firefox:
test:
image: cypress/browsers:22.15.0
stage: test
script:
- npm ci
- npm start &
- npx cypress run --browser firefoxThe versioned tag is a documented example, not a promise that it will remain the best choice. Select and maintain an image version deliberately so the CI browser and runtime environment are explicit rather than inherited from an arbitrary host update. Cypress describes its official Docker images as providing a consistent environment; its documentation lists images built with Google Chrome, Mozilla Firefox, and Microsoft Edge. Check the current image tags and browser support when choosing an image: Cypress: Run Cypress in GitLab CI.
Cache dependencies and retain useful test output
GitLab caches and artifacts solve different problems. A cache can reuse dependencies between jobs or pipeline runs; artifacts preserve job outputs so you can inspect them later. Treat artifacts, rather than a dependency cache, as the retained evidence for a failed run.
Cypress’s GitLab example uses a branch-slug cache key, caches node_modules/ and .npm/, and retains screenshots and videos as artifacts for one day:
cache:
key: ${CI_COMMIT_REF_SLUG}
paths:
- node_modules/
- .npm/
test:
# image, stage, and script omitted
artifacts:
when: always
paths:
- cypress/videos/**/*.mp4
- cypress/screenshots/**/*.png
expire_in: 1 dayThose paths and the one-day retention are examples, not requirements. Match cache paths to your package manager and repository, and confirm Cypress is configured to write the screenshot or video outputs you want to retain. Set artifact expiry according to how long your team needs to investigate failures; when: always asks GitLab to retain outputs even when the job fails.
Use Cypress Cloud when distributing specs across workers
GitLab’s parallel job setting creates multiple workers. Cypress’s --parallel option asks Cypress Cloud to coordinate the distribution of spec files among those workers, so this documented multi-machine workflow requires recorded runs and Cypress Cloud setup. A representative pattern is:
ui-chrome-tests:
image: cypress/browsers:22.15.0
stage: test
parallel: 5
script:
- npm ci
- npm start &
- npx cypress run --record --parallel --browser chrome --group UI-ChromeThe example uses five GitLab workers and a Chrome group; adjust both for your suite and runner capacity. Configure the Cypress project and credentials for recording, and supply secrets through protected CI variables according to current Cypress guidance. Do not commit a record key to repository source.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute--browserselects a browser installed in the job environment.--recordrecords the run to Cypress Cloud using your project setup and credentials.--parallelrequests Cloud-coordinated distribution of recorded specs across machines.--grouplabels related recorded runs, such as a browser-specific group.
A basic single-machine job can run without Cloud recording. Cloud also stores recorded run results; its GitLab integration can post run status checks and merge-request comments. Cypress’s integration documentation says the person enabling that integration needs GitLab administrator access and the CI job must supply a reliable commit SHA. Treat these as optional integration features, separate from the requirements for the basic test job.
Decide whether the additional workers are worth it
Start with one worker and measure your suite’s elapsed time before increasing concurrency. Parallelization assigns whole spec files, uses historical duration information to balance work, and does not guarantee spec execution order. A spec must not rely on another spec having run first. Files with reasonably similar durations tend to distribute more evenly.
More workers consume more CI capacity, and the available runner concurrency and Cloud features affect whether the setup is practical. Cypress’s Kitchen Sink example reports that a 1:51 serial run became 59 seconds on two machines, a 53% reduction; this is a vendor example, not a forecast for another suite. Cypress notes that browser-launch and video-encoding overhead can reduce the benefit when specs are short. Compare actual wall-time savings with the cost and availability of your CI workers.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common failures and practical fixes
- The app is unreachable when Cypress starts: the background start command may return before the server is ready, or the configured test URL may not match the app. Check the job log and URL, then add a project-appropriate readiness check.
- Cypress cannot launch the requested browser: the browser may not be installed in the selected image. Use an image that contains the intended browser and runtime, and verify the spelling passed to
--browser. - GitLab reports missing screenshot or video artifacts: the configured paths may not match Cypress’s output settings, or the run may not have generated those files. Confirm output settings and artifact paths; retain artifacts with
when: alwayswhen you need failure evidence. - Parallel recording cannot coordinate workers:
--parallelis for Cloud-coordinated recorded runs, not an unrecorded local-style run. Configure project recording and credentials, and ensure all workers participate in the same recorded run. - Parallel tests fail intermittently because of ordering: worker assignment does not preserve a guaranteed spec order. Remove dependencies between specs and keep each spec independently runnable.
- Parallelization saves little time: short specs may be dominated by startup and video overhead. Compare measured wall time and worker usage, then return to a single worker if added capacity does not justify the reduction.
Or skip the browser setup
If the goal is to capture a page rather than run browser-driven end-to-end assertions, ScreenshotNeo offers a website screenshot API and MCP server. A single GET request returns a PNG, JPEG, WebP, or PDF. For example, save a WebP capture with cURL:
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 API documentation for request options. ScreenshotNeo accepts cookie or consent banners before capture 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 cost nothing, with response headers identifying the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Frequently Asked Questions
Can I run Cypress in GitLab CI without Cypress Cloud?
Yes. A single-worker job can run the project’s Cypress command without recording. Cypress Cloud is required for the documented multi-machine parallel distribution workflow.
Does GitLab parallelism preserve the order of Cypress spec files?
No. Specs can run in different orders across workers, so tests should be independent of other specs.
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.
Recommended Free Tools
