misc: warn when a --spec pattern matches no spec files (#34023)

* fix(run): warn when a --spec pattern matches no spec files

When a user provides multiple spec patterns via `--spec` and one or more
patterns don't match any files, Cypress now emits a warning for each
unmatched pattern instead of silently skipping them.

Fixes #22645

* fix(run): clarify SPEC_FILE_NOT_FOUND warning message

Distinguish the per-pattern warning from the NO_SPECS_FOUND error by
making it explicit that the pattern was ignored and other specs will
still run.

* chore: add changelog entry for --spec unmatched pattern warning

* chore: move changelog entry into existing Misc section

* chore: add SPEC_FILE_NOT_FOUND to schema.graphql and visual snapshot

- Add SPEC_FILE_NOT_FOUND to ErrorTypeEnum in schema.graphql (required
  whenever a new key is added to AllCypressErrors in errors.ts per AGENTS.md)
- Add SPEC_FILE_NOT_FOUND.ansi visual snapshot for the new warning type

* fix(getUnmatchedPatterns): guard against undefined spec relative paths

Integration tests mock ctx.project._specs with plain strings rather than
SpecWithRelativeRoot objects, so s.relative is undefined. Filter those out
before passing to minimatch to prevent "Cannot read properties of undefined
(reading 'split')" crashes in tests that don't exercise the --spec warning path.

* fix(getUnmatchedPatterns): handle Windows path separators and absolute paths

relativeSpecPattern uses a hardcoded '/' separator so it cannot strip an
absolute Windows path (e.g. C:\project\cypress\e2e\foo.cy.ts stays absolute).
Likewise, path.relative returns backslash-separated paths on Windows while
minimatch treats backslashes as escape characters, not path separators.

Two fixes:
- run.ts: fall back to path.relative() for any pattern still absolute after
  relativeSpecPattern, preventing false SPEC_FILE_NOT_FOUND warnings on Windows
- getUnmatchedPatterns: normalize all paths to forward slashes before minimatch
  so the comparison is correct on all platforms

* feat(run): consolidate multiple unmatched --spec warnings into one

When multiple --spec patterns match nothing, emit a single
SPEC_FILE_NOT_FOUND warning listing all unmatched patterns together
rather than one warning per pattern.

- errors.ts: SPEC_FILE_NOT_FOUND now accepts string | string[] and uses
  fmt.listItems so all unmatched paths appear under one header
- run.ts: replace per-pattern warning loop with a single warning call
- Add multiplePatterns snapshot variant to visualSnapshotErrors.spec.ts

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jennifer-shehane

cli/CHANGELOG.md

@@ -47,6 +47,7 @@
 
 - When Cypress cannot connect to a Chromium-based browser such as Chrome or Edge over the Chrome DevTools Protocol, the resulting error now suggests checking whether remote debugging has been disabled by an enterprise or group policy. Because Cypress relies on remote debugging to control the browser, the `RemoteDebuggingAllowed` policy being disabled prevents Cypress from connecting, and the error now points to `chrome://policy` or `edge://policy` to investigate. Addresses [#32526](https://github.com/cypress-io/cypress/issues/32526).
 - Improved TypeScript types for `cy.get('@alias')` and `cy.wait('@alias')` so that `@`-prefixed strings correctly resolve to `Chainable<S>` instead of `Chainable<JQuery<HTMLElement>>`. Addresses [#8762](https://github.com/cypress-io/cypress/issues/8762).
+- When running `cypress run --spec` with multiple patterns and one or more patterns do not match any spec files, Cypress now emits a warning identifying each unmatched pattern instead of silently skipping it. Addresses [#22645](https://github.com/cypress-io/cypress/issues/22645).
 
 **Dependency Updates:**
 

packages/data-context/schemas/schema.graphql

@@ -1300,6 +1300,7 @@ enum ErrorTypeEnum {
   RUN_GROUPING_FEATURE_NOT_AVAILABLE_IN_PLAN
   SETUP_NODE_EVENTS_INVALID_EVENT_NAME_ERROR
   SETUP_NODE_EVENTS_IS_NOT_FUNCTION
+  SPEC_FILE_NOT_FOUND
   SUPPORT_FILE_NOT_FOUND
   SYNCHRONOUS_XHR_REQUEST_COOKIES_NOT_APPLIED
   SYNCHRONOUS_XHR_REQUEST_COOKIES_NOT_SET

packages/data-context/src/sources/ProjectDataSource.ts

@@ -537,6 +537,21 @@ export class ProjectDataSource {
     return this.ctx.project.specs.find((x) => x.absolute === absolute)
   }
 
+  getUnmatchedPatterns (patterns: string[], specs: SpecWithRelativeRoot[]): string[] {
+    const MINIMATCH_OPTIONS = { dot: true, matchBase: true }
+    // Normalize to forward slashes: path.relative may return backslashes on Windows and
+    // minimatch treats backslashes as escape characters rather than path separators.
+    const normalize = (p: string) => p.split(path.sep).join('/')
+    const specRelativePaths = specs
+    .map((s) => s.relative)
+    .filter((p): p is string => typeof p === 'string')
+    .map(normalize)
+
+    return patterns.filter((pattern) => {
+      return !specRelativePaths.some((specPath) => minimatch(specPath, normalize(pattern), MINIMATCH_OPTIONS))
+    })
+  }
+
   async getProjectPreferences (projectTitle: string) {
     const preferences = await this.api.getProjectPreferencesFromCache()
 

packages/data-context/test/unit/sources/ProjectDataSource.spec.ts

@@ -898,4 +898,58 @@ describe('ProjectDataSource', () => {
       })
     })
   })
+
+  describe('#getUnmatchedPatterns', () => {
+    const makeSpec = (relative: string) => ({ relative } as import('@packages/types').SpecWithRelativeRoot)
+
+    it('returns empty array when all patterns match found specs', () => {
+      const specs = [
+        makeSpec('cypress/e2e/foo.cy.ts'),
+        makeSpec('cypress/e2e/bar.cy.ts'),
+      ]
+
+      const unmatched = ctx.project.getUnmatchedPatterns(
+        ['cypress/e2e/foo.cy.ts', 'cypress/e2e/bar.cy.ts'],
+        specs,
+      )
+
+      expect(unmatched).toEqual([])
+    })
+
+    it('returns patterns that did not match any spec', () => {
+      const specs = [
+        makeSpec('cypress/e2e/foo.cy.ts'),
+      ]
+
+      const unmatched = ctx.project.getUnmatchedPatterns(
+        ['cypress/e2e/foo.cy.ts', 'cypress/e2e/nonexistent.cy.ts'],
+        specs,
+      )
+
+      expect(unmatched).toEqual(['cypress/e2e/nonexistent.cy.ts'])
+    })
+
+    it('returns all patterns when no specs are found', () => {
+      const unmatched = ctx.project.getUnmatchedPatterns(
+        ['cypress/e2e/foo.cy.ts', 'cypress/e2e/bar.cy.ts'],
+        [],
+      )
+
+      expect(unmatched).toEqual(['cypress/e2e/foo.cy.ts', 'cypress/e2e/bar.cy.ts'])
+    })
+
+    it('correctly matches glob patterns against found specs', () => {
+      const specs = [
+        makeSpec('cypress/e2e/foo.cy.ts'),
+        makeSpec('cypress/e2e/bar.cy.ts'),
+      ]
+
+      const unmatched = ctx.project.getUnmatchedPatterns(
+        ['cypress/e2e/**/*.cy.ts', 'cypress/e2e/nonexistent.cy.ts'],
+        specs,
+      )
+
+      expect(unmatched).toEqual(['cypress/e2e/nonexistent.cy.ts'])
+    })
+  })
 })

packages/errors/src/errors.ts

@@ -758,6 +758,21 @@ export const AllCypressErrors = {
 
         ${fmt.listItems(globPaths, { color: 'blue', prefix: '  > ' })}`
   },
+  SPEC_FILE_NOT_FOUND: (folderPath: string, patterns: string | string[]) => {
+    const patternList = Array.isArray(patterns) ? patterns : [patterns]
+    const globPaths = patternList.map((pattern) => {
+      const [resolvedBasePath, resolvedPattern] = parseResolvedPattern(folderPath, pattern)
+
+      return path.join(resolvedBasePath!, theme.yellow(resolvedPattern!))
+    })
+
+    return errTemplate`\
+        The following ${fmt.flag('--spec')} pattern did not match any spec files and will be ignored:
+
+        ${fmt.listItems(globPaths, { color: 'blue', prefix: '  > ' })}
+
+        Other spec files that matched will still run.`
+  },
   RENDERER_CRASHED: (browserName: string) => {
     return errTemplate`\
         We detected that the ${fmt.highlight(browserName)} Renderer process just crashed.

packages/errors/test/__snapshots__/SPEC_FILE_NOT_FOUND - multiplePatterns.ansi

@@ -0,0 +1,6 @@
+The following --spec pattern did not match any spec files and will be ignored:
+
+  > /path/to/project/root/cypress/e2e/nonexistent.cy.ts
+  > /path/to/project/root/cypress/e2e/also-not-found.cy.ts
+
+Other spec files that matched will still run.

packages/errors/test/__snapshots__/SPEC_FILE_NOT_FOUND.ansi

@@ -0,0 +1,5 @@
+The following --spec pattern did not match any spec files and will be ignored:
+
+  > /path/to/project/root/cypress/e2e/nonexistent.cy.ts
+
+Other spec files that matched will still run.

packages/errors/test/visualSnapshotErrors.spec.ts

@@ -628,6 +628,12 @@ describe('visual error templates', () => {
         noPattern: ['/path/to/project/root'],
       }
     },
+    SPEC_FILE_NOT_FOUND: () => {
+      return {
+        default: ['/path/to/project/root', 'cypress/e2e/nonexistent.cy.ts'],
+        multiplePatterns: ['/path/to/project/root', ['cypress/e2e/nonexistent.cy.ts', 'cypress/e2e/also-not-found.cy.ts']],
+      }
+    },
     RENDERER_CRASHED: () => {
       return {
         default: ['Electron'],

packages/server/lib/modes/run.ts

@@ -1164,6 +1164,18 @@ async function ready (options: ReadyOptions) {
     errors.throwErr('NO_SPECS_FOUND', projectRoot, String(specPattern))
   }
 
+  if (specPatternFromCli) {
+    const rawPatterns = Array.isArray(specPattern) ? specPattern : [specPattern as string]
+    // relativeSpecPattern uses a forward-slash concat and may not strip Windows absolute paths;
+    // fall back to path.relative for any pattern that remains absolute.
+    const relativePatterns = rawPatterns.map((p) => path.isAbsolute(p) ? path.relative(projectRoot, p) : p)
+    const unmatchedPatterns = project.ctx.project.getUnmatchedPatterns(relativePatterns, specs)
+
+    if (unmatchedPatterns.length > 0) {
+      errors.warning('SPEC_FILE_NOT_FOUND', projectRoot, unmatchedPatterns)
+    }
+  }
+
   if (browser.unsupportedVersion && browser.warning) {
     errors.throwErr('UNSUPPORTED_BROWSER_VERSION', browser.warning)
   }