If Cypress CI reports “No spec files found,” first verify that the job is running the intended Cypress project and configuration. Then check whether the expected test files match the active testing type’s specPattern and survive excludeSpecPattern, --spec, and any runtime filters. Keep the failure when tests should run; use --pass-with-no-tests only when an empty selection is an acceptable result for that job.
What the error means
Cypress found no eligible spec files for the run. It does not necessarily mean the repository contains no tests: Cypress discovers specs according to the project it runs, the active testing type, its configured patterns and exclusions, and any command-line or runtime filters. The error text can vary by Cypress release.
As an Amazon Associate I earn from qualifying purchases.
The key distinction is whether zero specs is unexpected. If CI is meant to execute tests, treat the result as a discovery failure and fix the selection. If a particular workflow intentionally filters out every spec and is allowed to do no testing, configure that job to accept an empty selection.
Check the project directory and configuration first
Cypress looks for its configuration in the current working directory by default. CI may be running from a repository root while the Cypress app lives in a subdirectory, or from a different directory than your local command.
- Inspect the CI step’s working directory and exact Cypress command.
- Run the command from the directory containing the intended Cypress project, or specify that directory with
--project. - Identify the configuration file the run actually uses. Check the CLI arguments as well: Cypress command-line configuration can override values in the config file.
For example, a job targeting a nested app can specify its project directory as follows:
npx cypress run --project ./apps/web
Use the actual path for your repository. If the project selection is wrong, editing a different project’s patterns will not fix the CI run. See Cypress’s CLI reference for --project and command options.
Verify that intended files match the active spec pattern
Compare the real paths and filenames of the tests you expect CI to run with specPattern for the testing type the job is using. Cypress treats this setting as a glob or array of globs; a file outside the configured pattern is not eligible just because it is a test file or because it exists in the repository.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Confirm whether the command runs end-to-end tests or component tests.
- Inspect the effective configuration for that testing type’s
specPattern. - Compare the pattern with the spec’s actual directory, filename, and extension, including any case or path differences relevant to your environment.
- Check
excludeSpecPatternfor a rule that removes the matching files.
Do not assume a historical default applies to your project. Cypress’s changelog documents specPattern as testing-type-specific and records historical defaults, but effective settings depend on the project’s configuration and Cypress version. Check the Cypress changelog alongside your installed version when the current configuration is unclear.
Check command-line and runtime filters
A --spec argument narrows the candidate set; it does not bypass the configured pattern. Cypress runs files selected by --spec only if they also match specPattern. Check both sides of the selection, as well as any runtime filtering that may intentionally or accidentally remove all candidates.
--spec: Confirm the path or glob points to the intended files and is compatible with the activespecPattern.- Config overrides: Review command-line configuration arguments that may replace values from the project config.
- Runtime filters: Check any logic that selects, skips, quarantines, or filters specs based on environment or job inputs. Cypress notes that dynamic filtering can produce a zero-file run intentionally.
The Cypress CLI documentation describes the interaction between --spec and specPattern. If a configuration that appears correct behaves differently across releases, compare the installed version with the versioned documentation and changelog; Cypress has made fixes involving filtering and path/glob handling.
Rank #4
Decide whether CI should fail when no specs run
Expected tests should run
Leave Cypress’s default no-spec failure in place. Correct the project directory, effective configuration, pattern, exclusion, or filter so the intended tests are discovered. Making the job green without running its expected tests hides a broken check.
An empty selection is an accepted outcome
For cypress run, add --pass-with-no-tests when the job is intentionally allowed to select zero specs:
Best Value
npx cypress run --pass-with-no-tests
Cypress documents this option as exiting successfully when no spec files are found. The option is listed in the current CLI reference; Cypress’s February 25, 2026 article says it starts with Cypress 15.11.0. Verify the installed version and its documentation before using it in an older project. This changes the exit result for the no-spec case, not the selection: it does not make missing tests run. See the Cypress article on no-spec CI failures for the policy distinction.
If you use Cypress Cloud, note that Cypress says no recording begins when no specs are found before recording starts. A successful exit therefore does not mean that a test run was recorded.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting by symptom
| Symptom | Likely cause | What to check or change |
|---|---|---|
| It works locally but CI finds no specs | CI runs from a different working directory, targets a different project, or uses different configuration or CLI overrides. | Compare the exact command and working directory. Run from the intended project or set --project; inspect the effective config and command-line values. |
The named file exists but --spec selects nothing |
The file does not also match the active testing type’s specPattern, or an exclusion removes it. |
Compare the full path and filename against specPattern and excludeSpecPattern. A CLI selection does not override the configured pattern. |
| Only some CI jobs fail with no specs | A job-specific argument or runtime filter may reduce the candidate set to zero. | Inspect the failing job’s --spec, environment, and filtering logic; compare them with a job that discovers specs. |
| The configuration seems correct, but behavior differs by version | Filtering or path/glob behavior may have changed in a release. | Check the installed Cypress version and compare its documentation and release notes in the changelog. |
The job passes after adding --pass-with-no-tests, but tests are absent |
The flag accepts the empty result; it does not repair discovery. | Remove the flag if tests are required, then fix the selection. Retain it only when the workflow policy accepts no specs. |
Or skip the browser setup
If the task is to capture a page rather than run Cypress tests, ScreenshotNeo is a website screenshot API and MCP server for developers. A single request returns a PNG, JPEG, WebP, or PDF. For example, save a WebP screenshot with cURL:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorscurl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
Quick Recap
See the ScreenshotNeo API documentation for request options. ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server provides screenshot and page-information tools for AI agents. The Free plan includes 1,000 shots a month without a card; paid plans start at $5 for 3,000 shots. Sign up for free.
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.
