Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallPut a .gitlab-ci.yml file in your repository, install dependencies, start your app, and run its Cypress test script. A single-worker run does not require Cypress Cloud. Cypress’s documented multi-machine parallel workflow does: GitLab provisions workers with parallel, while Cypress Cloud coordinates spec distribution when you use --record --parallel.
Start with a single-worker pipeline
GitLab reads pipeline configuration from .gitlab-ci.yml at the repository root. This minimal job follows Cypress’s documented starting pattern:
stages:
- test
test:
image: node:latest
stage: test
script:
- npm ci
- npm start &
- npm run e2eBefore using it, confirm that your repository has a working e2e script in package.json, that npm start launches the application Cypress should test, and that the CI environment has the browser and runtime dependencies Cypress needs. The node:latest tag is the minimal example, not a stable version pin; for maintained pipelines, choose and pin an appropriate Node image version.
Starting the app in the background does not by itself guarantee it is ready when tests begin. If startup time varies, add a readiness check appropriate to your project between npm start and npm run e2e. GitLab and Cypress do not require one particular readiness tool.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →This approach is appropriate when one CI job can run the suite within your time limit and you do not need Cloud-recorded results or Cloud-coordinated distribution.
Choose a browser image when the browser matters
A generic Node image is sufficient only if the required Cypress runtime, browser, and browser dependencies are available in that environment. If you need a particular installed browser, choose an appropriate Cypress browser image and pass the browser name to Cypress. Cypress’s GitLab guide demonstrates this Firefox example:
test:
image: cypress/browsers:22.15.0
stage: test
script:
- npm ci
- npm start &
- npx cypress run --browser firefoxcypress/browsers:22.15.0 is a documented example tag, not a promise that it will remain the preferred tag. Select an image version that suits your project, pin it instead of relying on a moving tag, and maintain it as your Cypress, Node, and browser requirements change. The Cypress CI guide describes its official images as a way to provide a consistent Cypress/browser environment rather than inheriting arbitrary browser updates from the CI host. The guide says its maintained images are built with Google Chrome, Mozilla Firefox, and Microsoft Edge; check the current image documentation for available tags and browser support.
The key distinction is whether your job needs a named browser. If it does, use an image that explicitly supplies that browser and invoke it with --browser. That option selects an installed browser; it does not install one.
Cache dependencies and retain test evidence
A GitLab cache can speed later jobs by reusing dependencies. Artifacts preserve files produced by a job so they remain available for inspection. They solve different problems: do not rely on a cache as the authoritative record of evidence from a failed run.
Cypress’s GitLab example uses a branch-slug cache key and retains screenshots and videos as artifacts:
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 dayTreat the paths, key, and one-day expiry as example values. Match cache paths to the package manager and dependency layout you actually use, and match artifact paths to Cypress’s configured output locations. Set retention to give your team enough time to investigate failures without keeping outputs longer than needed. when: always asks GitLab to collect the configured outputs even when the job fails, which is useful when a failure is the reason you need them.
Use parallel workers only when the trade-off is worthwhile
Start with one worker and measure suite duration. If it is too long, GitLab can create multiple instances of a job with its parallel setting, but that setting alone does not coordinate Cypress spec assignment. Cypress’s documented multi-machine strategy uses recorded runs with Cypress Cloud: GitLab provisions workers, and Cypress distributes whole spec files among them using historical duration information.
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-ChromeThis is a pattern to adapt, not a complete pipeline for every repository: it assumes the app can start in each worker, the selected image includes Chrome, and the project is configured for Cypress Cloud recording with credentials available to CI. A parallel: 5 job asks GitLab for five workers; the number is an example, not a recommendation for every runner pool. Each worker consumes CI capacity, so compare the saved wall-clock time with the added worker resources and any Cloud feature or plan requirements that apply.
Parallel assignment is by spec file, not by individual test, and spec execution order is not guaranteed. Tests must not depend on another spec having run first. Files with reasonably similar durations generally distribute more evenly; one especially long spec can limit the benefit even when other workers finish early. Cypress’s Kitchen Sink vendor example reports a serial run of 1 minute 51 seconds becoming 59 seconds on two machines, a 53% reduction. That example is not a forecast for your suite: browser startup and video encoding overhead can reduce gains, especially when specs are short.
Know what Cypress Cloud adds
A basic single-machine job can run Cypress locally in CI without recording to Cloud. Cloud becomes necessary for Cypress’s documented multi-machine parallelization workflow, and it can also store recorded run results. Cypress’s GitLab integration can post run status checks and merge request comments; enabling that integration requires GitLab administrator access and a reliable commit SHA supplied by CI.
| Setup | What it does | When it fits |
|---|---|---|
| Single worker, no recording | Runs the test command in one CI job; does not use Cloud-coordinated distribution. | Use when the suite duration is acceptable and Cloud recording features are not needed. |
| Multiple GitLab workers with Cypress parallel flags | GitLab creates worker jobs; Cypress Cloud coordinates recorded spec assignment. | Use when measurements justify more CI concurrency and the project is set up for Cloud recording. |
| Cloud integration features | Can provide recorded run results, status checks, and merge request comments. | Use when those results and GitLab notifications are useful; integration setup has additional requirements. |
Keep the CLI options distinct:
--browserselects a browser installed in the environment.--recordrecords a run to Cypress Cloud using project setup and credentials.--parallelrequests Cloud-coordinated distribution of recorded specs across machines.--grouplabels related recorded runs, such as theUI-Chromegroup in the example.
Do not put a record key in repository source. Store credentials in protected CI variables and follow current Cypress guidance for secret handling. Check current Cypress and GitLab documentation for image tags, Cloud features, and plan requirements, since these can change.
Troubleshoot common CI failures
- The
e2escript is missing or exits immediately: verify thatpackage.jsondefines the script invoked by the job and that it runs Cypress with the intended configuration. - Cypress cannot connect to the app: check that
npm startlaunches the expected service in CI, that the app binds to an address reachable from the test process, and that the job waits for readiness before launching Cypress. - The selected browser is unavailable: use an image containing that browser and its dependencies, or select a browser that is installed. The
--browserflag does not install browsers. - Artifacts are absent after a failed job: check that artifact collection uses
when: always, that the configured paths match Cypress’s output locations, and that the files were actually produced. - Parallel workers run the same pattern without distributing specs: confirm that the run is recorded, Cloud setup and credentials are valid, and the Cypress command includes both
--recordand--parallel. GitLab’sparallelsetting provisions jobs; it does not replace Cypress Cloud coordination. - A parallel run is slower than expected: compare suite time and spec durations, check for short specs whose startup overhead dominates, and weigh the result against the CI capacity consumed by each worker.
Or skip the browser setup
If your CI task is to capture a web page rather than execute interactive end-to-end assertions, ScreenshotNeo offers a screenshot API and MCP server. One GET request returns an image or PDF; its options include full-page capture, browser/device settings, and waiting for a selector or network idle. For Cypress tests, continue using Cypress; a screenshot API is not a substitute for test assertions.
Install no browser for this example; replace the target URL and API key with your own values:
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. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for free.
Frequently Asked Questions
Can Cypress run in GitLab CI without Cypress Cloud?
Yes. A single-worker job can run Cypress in CI without Cloud recording; Cloud is required for Cypress’s documented multi-machine parallelization workflow.
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 problemsDoes GitLab’s parallel setting distribute Cypress specs by itself?
No. It creates worker jobs. Cypress Cloud coordinates spec distribution when the recorded run uses --record --parallel.
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.
