Cypress Spec Files

What Is a Spec File?

A spec file is a JavaScript or TypeScript file containing one or more tests, typically organized with describe() and it(). By default, Cypress looks for files matching **/*.cy.{js,jsx,ts,tsx} inside the cypress/e2e folder.

Nothing prevents you from nesting spec files in subfolders that mirror your application's feature areas, Cypress will discover them recursively based on the configured specPattern.

cypress/e2e/
  auth/
    login.cy.js
    signup.cy.js
  checkout/
    cart.cy.js
    payment.cy.js

Grouping spec files by feature area keeps a growing suite navigable as it scales past a handful of files.

Configuring specPattern

// cypress.config.js
export default defineConfig({
  e2e: {
    specPattern: 'cypress/e2e/**/*.cy.{js,ts}',
  },
});

• specPattern accepts a glob (or array of globs) controlling which files Cypress treats as specs.
• Changing specPattern is useful when migrating an existing test suite into a Cypress-friendly layout.
• Component test specs typically use a separate pattern, often colocated next to source files as *.cy.jsx.

Spec File Conventions

Default naming and location conventions Cypress expects out of the box.

One Spec File per Feature, Not per Page

A common organizational mistake is creating one spec file per page component. A more durable pattern is organizing by user-facing feature or flow, since a single feature (like checkout) might span several pages, and a single page might support several distinct features.

• Group tests around a complete user flow (e.g., "checkout"), not a single component.
• Keep each spec file focused enough that a failure's cause is quick to narrow down.
• Split an oversized spec file once it starts mixing unrelated concerns.

Running a Subset of Spec Files

You rarely want to run every spec file while actively developing a single feature. The --spec CLI flag and the Test Runner's spec list both let you target a subset quickly.

npx cypress run --spec "cypress/e2e/checkout/**/*.cy.js"

This runs only the spec files inside the checkout folder, useful for fast local iteration.

Common Mistakes

• Creating a one-to-one mapping between page components and spec files instead of organizing by user flow.
• Letting a single spec file grow to hundreds of lines covering unrelated scenarios.
• Forgetting that changing specPattern can silently exclude existing spec files from being discovered.
• Not using --spec during local development, leading to slow, unnecessary full-suite runs.

Key Takeaways

• Spec files are discovered based on the specPattern configuration, defaulting to cypress/e2e/**/*.cy.{js,ts}.
• Organize spec files around user-facing features and flows, not one-to-one with page components.
• Nested folders under cypress/e2e/ help keep a large suite navigable.
• Use --spec to target a subset of files during local development for faster feedback.