Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →If a Cypress test is missing from the Specs page, check discovery before changing the test code. Cypress only lists files that match the active specPattern, and then removes anything matching excludeSpecPattern. The default E2E pattern requires a .cy. filename infix, so cypress/e2e/login.js is not discovered while cypress/e2e/login.cy.js is.
The rule that decides whether Cypress can see a test
Cypress builds its runnable set from configured glob patterns. Conceptually, the set is:
specPattern matches − excludeSpecPattern matches
The --spec command-line option narrows that already configured set; it does not add a file outside specPattern. A correct-looking path can therefore still produce “no spec files found” when the file is outside the active pattern.
| Testing type | Documented default pattern | Example that is discovered | Example that is not |
|---|---|---|---|
| E2E | cypress/e2e/**/*.cy.{js,jsx,ts,tsx} |
cypress/e2e/login.cy.js |
cypress/e2e/login.js |
| Component | **/*.cy.{js,jsx,ts,tsx} |
src/Button.cy.tsx |
src/Button.test.tsx unless you change the pattern |
These are documented defaults; your project may override them in its Cypress configuration. Start by identifying which testing type and configuration Cypress is actually using.
#1 Best Overall
Fix a missing spec step by step
1. Confirm the project and testing type
Run Cypress from the repository you intend to test, and verify whether you opened the E2E or Component Testing setup. A monorepo can contain several package directories and several configuration files, so a command launched from the wrong working directory can search a different project than the one you edited.
- Check the shell’s current directory and the package in which Cypress is installed.
- Open the Cypress launch screen and select the testing type that owns the file.
- Check the configuration file loaded by that project before editing a pattern.
The E2E and component defaults are different, so a filename that works for one mode is not proof that it belongs to the other. Cypress’s configuration reference and FAQ describe the project and setup concepts.
2. Check the filename and extension
For an unmodified E2E setup, use the .cy. infix and a supported JavaScript or TypeScript extension:
cypress/e2e/login.cy.js
cypress/e2e/login.cy.jsx
cypress/e2e/login.cy.ts
cypress/e2e/login.cy.tsxRename a file when its location and naming are accidental inconsistencies. For example, rename cypress/e2e/login.js to cypress/e2e/login.cy.js, then reopen the Specs page. Also check capitalization: a path that differs only by case can work on a case-insensitive local filesystem and fail in a case-sensitive CI environment.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsComponent specs use the same supported extensions in the documented default, but they can be located anywhere matched by **/*.cy.{js,jsx,ts,tsx}. A file named Button.test.tsx will remain invisible until you deliberately change the component pattern.
3. Compare the complete path with specPattern
Do not inspect only the basename. The directory, intermediate folders and extension all have to match the glob. If your repository intentionally stores E2E specs in tests/, configure that location explicitly.
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
specPattern: [
'cypress/e2e/**/*.cy.{js,jsx,ts,tsx}',
'tests/**/*.cy.{js,jsx,ts,tsx}'
]
}
})Keep the standard pattern when you still use cypress/e2e; add the alternate pattern rather than replacing a directory unintentionally. If you want a different convention, make the change explicit and document it for local and CI commands. The Writing and organizing tests guide explains the naming and organization model.
4. Inspect excludeSpecPattern
An exclusion can remove a file after it has matched. Review every exclusion in the active E2E or component configuration, including broad globs inherited from a shared config.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
specPattern: 'cypress/e2e/**/*.cy.{js,jsx,ts,tsx}',
excludeSpecPattern: [
'cypress/e2e/experimental/**/*.cy.ts',
'**/*.draft.cy.js'
]
}
})Temporarily remove or narrow an exclusion only if the file should be part of the normal suite. If the exclusion is intentional, do not use a broad --spec path as a workaround; keep the suite definition honest and place experimental coverage in a separately configured pattern or testing command.
5. Treat --spec as a filter, not an override
When running a targeted spec, the argument must identify a file that the active pattern already includes. A command such as:
npx cypress run --e2e --spec 'cypress/e2e/login.cy.ts'can narrow the configured E2E set to that file. It cannot make cypress/e2e/login.ts discoverable when the configured pattern requires .cy., and it cannot bypass an exclusion. If the targeted command reports no matching specs, first test the file against the configuration, then test the regular unfiltered run.
6. Turn on discovery debug logs
When the path appears correct, use Cypress’s discovery namespaces to see how arguments and project files are being handled:
DEBUG=cypress:cli,cypress:data-context:sources:FileDataSource,cypress:data-context:sources:ProjectDataSource npx cypress run --e2eOn Windows Command Prompt, set the variable for the command session before running Cypress:
set DEBUG=cypress:cli,cypress:data-context:sources:FileDataSource,cypress:data-context:sources:ProjectDataSourcenpx cypress run --e2e
Read the output for the project root, configuration path, parsed CLI arguments and file-search activity. This distinguishes “the glob found nothing” from “the command was launched against another project.” Cypress documents these namespaces in its troubleshooting guidance.
7. Compare local and CI invocation details
Do not assume that local and CI use the same inputs. Compare, side by side:
- working directory and repository checkout path;
- the Cypress configuration file and testing type;
- the exact
--specvalue, if any; - environment variables that construct or replace a pattern;
- path separators and filename case;
- the debug output showing the project and discovered files.
A CI command can also run from a package subdirectory while your local command runs at the repository root. Make the working directory explicit in the CI job, or pass the intended project location consistently, then rerun with the discovery debug namespaces enabled.
Recommended Free Tools
8. Separate discovery from compilation
A spec can be discovered successfully and still fail before its tests execute. Syntax errors, TypeScript errors, missing imports and bundler failures are compilation problems, not missing-spec problems. If Cypress lists the file and then reports a compile or module error, keep the pattern unchanged and fix the reported source error. Cypress’s common error messages reference helps classify those failures.
Configuration patterns that avoid surprises
Keep E2E and component settings separate
Put each pattern under the testing type that owns it. A component pattern under e2e does not make component specs appear, and vice versa.
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
specPattern: 'cypress/e2e/**/*.cy.{js,jsx,ts,tsx}'
},
component: {
specPattern: '**/*.cy.{js,jsx,ts,tsx}'
}
})Use arrays when more than one location is intentional
Arrays make alternate directories visible to reviewers and reduce the temptation to use an overly broad glob. Keep each entry specific enough that fixtures, generated files and documentation examples do not become specs by accident.
Review inherited configuration
If your configuration is generated or merged from another file, inspect the effective value rather than only the local fragment. A later assignment can replace an earlier specPattern, and an inherited exclusion can silently remove a matching file.
Best Value
Rename the file or change the pattern?
| Situation | Preferred fix | Reason |
|---|---|---|
| The file is the only item that violates the repository convention. | Rename it to the existing convention. | It preserves the project-wide defaults and avoids configuration drift. |
| Specs intentionally live in another directory. | Add that directory to specPattern. |
The location is a project decision, not an accidental typo. |
| A matching file is a draft or generated artifact. | Keep or narrow excludeSpecPattern. |
It should not enter the normal suite. |
| You need one test for a focused run. | Use --spec after confirming it is included. |
It narrows discovery without redefining the suite. |
| Local and CI disagree. | Align project root, config, testing type and command first. | Changing a glob can hide an invocation mismatch. |
Common symptoms and precise fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| The Specs page is empty. | Wrong testing type, project or pattern. | Confirm the project and mode, then compare the full path with the active specPattern. |
| “No spec files found” for a targeted command. | The --spec path is outside the configured set or excluded. |
Use a matching .cy. filename, correct the directory, or remove an unintended exclusion. |
| The file appears locally but not in CI. | Different working directory, config, path case or shell argument. | Compare debug output and exact invocation details in both environments. |
| The file is listed, then the run fails immediately. | Compilation or bundling failure. | Read the syntax, import or TypeScript error; do not change discovery patterns unless the file is actually absent. |
| A newly added directory is ignored. | The default E2E glob does not include it. | Add an intentional pattern such as tests/**/*.cy.{js,jsx,ts,tsx}. |
A file with .cy. is still absent. |
An exclusion, wrong testing type or wrong project is active. | Inspect excludeSpecPattern, verify the mode and run the discovery debug command. |
Keeping discovery reliable in CI
- Use one documented naming convention and enforce it in code review.
- Keep
specPatternnarrowly scoped to test directories; broad repository-wide globs increase search work and can match unintended files. - Keep exclusions close to the reason for them, with comments when a generated or experimental directory is involved.
- Print the working directory and the Cypress command in CI logs so a future failure can be compared with a local run.
- Use
--specfor diagnosis or a deliberately targeted job, not as a substitute for a correct suite definition. - When upgrading or restructuring a repository, run an unfiltered discovery check for both E2E and component modes before debugging individual tests.
Or skip the browser setup
If your immediate goal is to capture a visual record of a page while diagnosing a test—not to execute Cypress itself—ScreenshotNeo can return a screenshot or PDF through one request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.
See the ScreenshotNeo API documentation for authentication and options. A basic request is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe same capture from Python:
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)And 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}`);For test diagnostics, relevant options include full-page capture with lazy images loaded, a CSS-selector element capture, custom viewport or one of 12 device presets, dark mode, retina scale, custom CSS or JavaScript, clicking before capture, waiting for a selector, delay or network idle, hiding selectors, blocking ads or resource types, custom headers, cookies, user agent, Authorization, timezone and geolocation. It also supports transparent backgrounds, resizing, a chosen cache TTL, signed links, asynchronous jobs with signed webhooks, up to 100 URLs per bulk call, a usage API and an OpenAPI specification. Every feature is available on every plan, and parameter names used by other screenshot APIs also work for easier migration.
An 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 screenshots. Create a free ScreenshotNeo account.
Free tools Windows power users keep installed
One-click scans. No signup required.
FAQ
What should I include when reporting a missing-spec problem?
Include the exact Cypress command, working directory, testing type, configuration path, file path, effective specPattern and excludeSpecPattern, plus the discovery debug output. That bundle lets another developer reproduce the discovery inputs instead of guessing from a screenshot of the Specs page.
Why is changing the test code usually the wrong first move?
A file that is outside the configured discovery set is never compiled or executed, so edits inside its describe block cannot make it appear. Prove discovery first; only then investigate test syntax, imports or browser behavior.
Further reading
For a general introduction to Cypress end-to-end testing, see Packt’s End-to-End Web Testing with Cypress by Waweru Mwaura (paperback, first edition, published January 29, 2021). It is optional background material; the current Cypress documentation should be your source for configuration behavior.
Frequently Asked Questions
What should I include when reporting a missing-spec problem?
Include the exact Cypress command, working directory, testing type, configuration path, file path, effective specPattern and excludeSpecPattern, plus discovery debug output.
Why is changing the test code usually the wrong first move?
A file outside the configured discovery set is never compiled or executed, so edits inside its test block cannot make it appear. Prove discovery first.
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.
