How to Run a single test in Cypress (2026)

TL;DR

To run one Cypress test, use it.only locally, or run npx cypress run --spec "path/to/file.cy.ts" without editing source. For title-level focus, use a grep plugin or tags. In the GUI, open the spec and select the example. Never commit .only markers.

Key Takeaways

• Use it.only or describe.only for short local debugging loops, never for committed main-branch code.
• Prefer npx cypress run --spec for file or folder isolation that stays clean in CI.
• Add title or tag grep when one file still contains too many examples.
• cypress open lets you click a single test for time-travel debugging without permanent source edits.
• Gate exclusive tests with ESLint and CI checks so focus markers cannot merge silently.
• Combine --spec with --browser and --headed when reproduction depends on a real window.
• Always re-expand from one test to the full file before you merge a fix.

The short answer to cypress how to run a single test is to isolate it either by Mocha focus (it.only / describe.only), by CLI filters (cypress run --spec and optional grep plugins), or by selecting the test in cypress open. For local debugging, it.only is the fastest feedback loop. For CI and shared machines, prefer --spec (and grep when you need title-level targeting) so isolation never depends on edited source that could be committed by mistake.

Running one test is not a luxury. It is how you diagnose flaky failures, refine selectors, and keep a large suite usable. This guide covers every practical isolation method Cypress supports in 2026, when to use each one, how to avoid committing focused tests, and how to make single-test workflows safe in CI.

TL;DR

Start with the method that matches your context. Local debugging favors Mocha focus. Shared runners favor file and title filters that leave source clean.

1. Cypress How to Run a Single Test: Choose the Right Isolation Layer

Cypress organizes execution in layers: project, browser, spec file, describe block, and individual it example. Isolation can happen at any of those layers. Picking the wrong layer creates either too little focus (you still wait for half the suite) or too much risk (you ship it.only and silently skip coverage).

Spec-file isolation is best when the failing scenario lives alone in a file, or when a file is already small and cohesive. Suite isolation with describe.only is best when several related examples share expensive setup you still need. Example isolation with it.only is best for a single assertion path. Title filtering is best when the suite is large and you cannot edit the file, such as in a temporary CI re-run.

Also separate run mode from open mode. cypress run is headless by default, exits with a code, and is what CI uses. cypress open launches the Test Runner GUI for interactive debugging. You can isolate in both, but the UX differs. For headed single-test runs without the full GUI, see how to run tests in headed mode in Cypress.

Write down the question you are answering: "Does this one assertion pass?" versus "Does this whole payment flow file pass?" The answer dictates whether you need it.only, --spec, or a folder glob.

2. Use it.only and describe.only for Local Debugging

Mocha focus is the fastest way to answer cypress how to run a single test when you already have the file open. Prefix the target with .only:

// cypress/e2e/checkout/payment.cy.ts
describe('Checkout payment', () => {
  beforeEach(() => {
    cy.loginAs('buyer@example.com')
    cy.visit('/checkout')
  })

  it.only('applies a valid promo code', () => {
    cy.get('[data-cy=promo-input]').type('SAVE10')
    cy.get('[data-cy=apply-promo]').click()
    cy.get('[data-cy=discount-line]').should('contain', '10%')
  })

  it('rejects an expired promo code', () => {
    // skipped while it.only is active
  })
})

describe.only focuses an entire block and still runs nested before / beforeEach hooks for that block:

describe.only('Checkout payment', () => {
  it('applies a valid promo code', () => { /* ... */ })
  it('rejects an expired promo code', () => { /* ... */ })
})

Rules that keep .only safe:

1. Never commit focused tests to the default branch.
2. Prefer one .only at a time. Multiple .only markers still run only the focused set, but the intent becomes harder to read.
3. Nested .only behaves as you would expect: the focused suite or test is selected, and non-focused siblings are skipped.
4. Pair with an ESLint rule such as mocha/no-exclusive-tests or a Cypress lint rule so CI fails if focus lands in a PR.

Focused tests are a scalpel. They cut the feedback loop to seconds. They are not a release strategy. When the bug is fixed, remove .only immediately and re-run the surrounding file.

3. Filter Specs With cypress run --spec

When you need a single file or a small set of files without editing source, pass --spec:

# one file
npx cypress run --spec "cypress/e2e/login.cy.ts"

# several files (comma-separated)
npx cypress run --spec "cypress/e2e/login.cy.ts,cypress/e2e/logout.cy.ts"

# glob a folder
npx cypress run --spec "cypress/e2e/checkout/**/*.cy.ts"

On Windows shells, quoting rules differ. Prefer double quotes around globs and avoid unquoted * expansion. In npm scripts, escape carefully:

{
  "scripts": {
    "cy:login": "cypress run --spec \"cypress/e2e/login.cy.ts\"",
    "cy:checkout": "cypress run --spec \"cypress/e2e/checkout/**/*.cy.ts\""
  }
}

--spec works with both absolute and project-relative paths. In CI, relative paths from the repo root are clearer in logs. Combine with browser and headed flags when needed:

npx cypress run --browser chrome --headed --spec "cypress/e2e/login.cy.ts"

Spec filtering is the correct default for "run this area of the product" workflows. It does not require dirty working trees, and it composes cleanly with sharding strategies that already split by file path.

4. Match a Single Test Title With Grep-Style Filters

File-level isolation is often still too broad. Title-level filtering lets you run one example by its name. The common 2026 approach is a grep plugin such as @cypress/grep (or a maintained community equivalent with the same usage pattern). After installing and registering it in support and config, you can target titles from the CLI:

# conceptual usage with a grep plugin
npx cypress run --env grep="applies a valid promo code"
npx cypress run --env grep="promo" --spec "cypress/e2e/checkout/**/*"
npx cypress run --env grepTags="@smoke"

Typical registration lives in config and support files per the plugin docs. Tagging tests improves grepping:

it('applies a valid promo code', { tags: ['@smoke', '@checkout'] }, () => {
  cy.get('[data-cy=promo-input]').type('SAVE10')
  cy.get('[data-cy=apply-promo]').click()
  cy.get('[data-cy=discount-line]').should('be.visible')
})

Without a plugin, you can still approximate title focus with temporary it.only, or by moving one example into a scratch spec. Prefer a documented grep approach for shared teams so engineers do not invent incompatible scripts.

Title filters shine when CI re-runs "the one test that failed in the last job" without checking out a patch that adds .only. Combine --spec and grep so the runner does not load unrelated files.

5. Run One Test Interactively in cypress open

Interactive mode is ideal when you need time-travel debugging, DOM snapshots, and command log inspection for a single example.

npx cypress open
# or pin e2e testing type
npx cypress open --e2e --browser chrome

Workflow:

1. Choose E2E Testing (or Component Testing).
2. Pick the browser.
3. Open the target spec from the list.
4. Click a single test title in the runner to re-run only that example.
5. Use the command log, snapshots, and console to inspect failures.

Open mode still honors it.only in the source if present. For pure UI isolation without source edits, select the test from the list after the spec loads. This is the best path for teaching juniors and for visual confirmation of selector behavior.

When scrolling or visibility issues make a single test fail only under certain viewport sizes, open mode plus viewport presets reveals the problem quickly. Pair with how to scroll to an element in Cypress when the failure is actionability related.

6. Compare Isolation Methods Side by Side

Practical rule: edit source only on your machine for minutes, not for hours on a shared branch. Convert a local .only session into a --spec or grep command before you push, open a PR, or ask a teammate to reproduce.

Also note Mocha's skip API is the opposite of focus. it.skip and describe.skip exclude tests intentionally. Focus includes; skip excludes. For a full treatment of skip, pending, and grouping patterns, read how to skip and group tests in Cypress.

7. Wire Package Scripts and Environment-Specific Single Runs

Teams waste time retyping long CLI strings. Encode the common single-run patterns once:

{
  "scripts": {
    "cy:open": "cypress open --e2e",
    "cy:run": "cypress run",
    "cy:run:chrome": "cypress run --browser chrome",
    "cy:spec": "cypress run --spec",
    "cy:smoke": "cypress run --env grepTags=@smoke"
  }
}

Usage examples:

npm run cy:spec -- "cypress/e2e/login.cy.ts"
npm run cy:smoke
CYPRESS_baseUrl=https://staging.example.com npm run cy:spec -- "cypress/e2e/auth/**/*"

Environment variables matter when the single test depends on a target environment:

export CYPRESS_baseUrl=https://staging.example.com
npx cypress run --spec "cypress/e2e/login.cy.ts"

npx cypress run --config baseUrl=https://staging.example.com --spec "cypress/e2e/login.cy.ts"

Keep secrets out of scripts committed to git. Use CI secret stores for tokens and inject them as CYPRESS_* variables. Single-test debugging against production data is usually the wrong move; prefer staging with seeded fixtures.

8. Keep Single-Test Workflows Safe in CI

CI should never depend on committed .only. Use layered defenses:

# GitHub Actions example: run one path on demand
jobs:
  cypress-one-spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npx cypress run --browser chrome --spec "${{ inputs.spec }}"

Additional CI practices:

1. Fail the build if a search finds it.only or describe.only under cypress/ on protected branches.
2. Quarantine flaky tests with skip plus ticket links rather than permanent .only workarounds.
3. Shard by spec path for full suite speed; use single-spec jobs only for reproduction and smoke.
4. Artifacts: always upload screenshots and videos for the isolated run so the single failure is inspectable.

A single-test CI job is a surgical tool for "prove this fix" and "repro this flake." It is not a substitute for the full suite gate.

9. Cypress How to Run a Single Test Across Browsers and Modes

Isolation combines with browser selection:

npx cypress run --browser electron --spec "cypress/e2e/login.cy.ts"
npx cypress run --browser chrome --spec "cypress/e2e/login.cy.ts"
npx cypress run --browser firefox --spec "cypress/e2e/login.cy.ts"
npx cypress run --browser edge --spec "cypress/e2e/login.cy.ts"

Headed single runs help when a failure is visual or timing-related under a real window:

npx cypress run --headed --browser chrome --spec "cypress/e2e/login.cy.ts"

Component tests follow the same isolation ideas with the component testing type:

npx cypress open --component
npx cypress run --component --spec "src/components/Button.cy.tsx"

If your failure only appears after a cold cache or first navigation, do not only re-run the green path in open mode. Use cypress run once to match CI determinism, then open mode to inspect. Recordings and retries can also change timing; when investigating flakes, disable extra retries temporarily so you see the first failure clearly.

For network-heavy single tests, keep intercepts tight and deterministic. Review Cypress cy.intercept examples so a solo run does not depend on unrelated backend noise.

10. Diagnose Why Your Single Test Still Runs Neighbors

Common surprises when you thought you isolated one test:

1. Multiple .only markers in imported helpers or partial files still expand the focused set.
2. Root hooks in support/e2e.ts always run and can mask timing differences.
3. Glob too wide: patterns without ** may miss nested folders, while over-broad ** may pull too much.
4. Wrong working directory: --spec paths resolve relative to the Cypress project root.
5. Grep string too loose: grep=login may match many titles; prefer unique phrases or tags.
6. Test retries: a single test may execute multiple attempts; that is isolation by title, not by attempt count.
7. it.only inside describe.skip: mixed markers confuse readers; clean them up.

Read the Cypress runner summary: it lists passing, pending, and failing counts. Pending often means skipped via .skip or filtered out. If the count is higher than one for an it.only session, search the repo for other .only occurrences.

11. Patterns for Large Monorepos and Multiple Cypress Projects

Monorepos often host several Cypress configs (app, admin, marketing). Isolation must name the config:

npx cypress run --config-file apps/web/cypress.config.ts --spec "apps/web/cypress/e2e/login.cy.ts"
npx cypress run --project apps/admin --spec "cypress/e2e/users.cy.ts"

Align path conventions so engineers do not mix admin specs into the web project. Document the canonical scripts in the root README. When using Nx, Turbo, or pnpm filters, wrap Cypress so --spec still reaches the correct package:

pnpm --filter @acme/web exec cypress run --spec "cypress/e2e/login.cy.ts"

Shared libraries that export test helpers should not contain .only. Put demo-only specs behind a path that CI never selects, or name them *.manual.cy.ts and exclude them from default globs in cypress.config.ts.

12. A Practical Playbook You Can Reuse Tomorrow

Use this sequence the next time a CI job fails on one assertion:

1. Copy the failing title and file path from the CI log.
2. Reproduce with file isolation:

   npx cypress run --browser chrome --spec "path/from/log.cy.ts"
   

3. If the file is large, add temporary it.only locally or apply a title grep.
4. Switch to cypress open for the same file when you need snapshots.
5. Fix the product or the test.
6. Remove .only, re-run the full file, then the related folder.
7. Push and let CI run the broader suite.

This playbook keeps isolation intentional. You move from wide (CI) to narrow (local) and back to wide (verification) without leaving traps in the branch.

Single-Test Hygiene Checklist

Before you merge, confirm no exclusive tests remain, the related file still passes without focus, flaky skips have tickets, and the new assertion is not covered only under a special env flag nobody runs. Confirm screenshots or videos from the isolated run are attached to the PR when the bug was hard to see. Confirm docs or scripts were updated if you introduced a new smoke tag. This checklist turns a fast local fix into durable suite health. Re-run at least once on the same browser CI uses so local Electron success is not a false friend. If the bug involved auth, reset sessions with cy.session carefully so isolation does not hide cache issues. Finally, note the reproduction command in the PR description so reviewers can re-run the same single path in minutes.

When you teach this workflow to a new hire, demonstrate both a happy path and a failure path. Show them the CI log line that prints the spec path, paste it into --spec, and watch the local runner reproduce the same assertion. Then intentionally introduce an it.only, run the suite, and show how the green bar can lie when siblings are pending. That five-minute demo prevents months of accidental coverage gaps.

Finally, store a short internal cheat sheet next to your Cypress config: one command for file isolation, one for smoke tags, one for headed Chrome, and one for open mode. Teams that write these four lines once stop inventing divergent scripts in every PR description. Consistency is part of isolation quality, not a separate concern.

Interview Questions and Answers

Q: How do you run only one Cypress test from the command line?

I use npx cypress run --spec with the file path when file isolation is enough. For title-level isolation I use a grep plugin or tags. I avoid committing it.only.

Q: What is the difference between it.only and --spec?

it.only edits source and focuses one example inside Mocha. --spec selects files without source changes and is safer for CI and shared branches.

Q: How do you prevent it.only from merging?

I enable an ESLint rule for exclusive tests and optionally a CI grep gate on protected branches. Code review also checks for focus markers.

Q: Can you run a single test in headed mode?

Yes. Combine --headed with --spec and a browser flag, or use open mode and select the test in the GUI.

Q: How do tags help single-test selection?

Tags like @smoke let grep filters select a cross-file subset without listing every path. They work well for on-demand CI jobs.

Q: What happens if multiple tests have .only?

Mocha runs the focused set: all exclusive tests and suites. Non-focused examples are skipped. That can surprise people who expected exactly one test.

Q: How do you re-run only the failed Cypress test in CI?

I re-trigger a job with an input for the spec path and optional grep string, using the same browser and baseUrl as the original failure.

Common Mistakes

• Committing it.only or describe.only to the main branch.
• Using a glob that matches far more files than intended.
• Forgetting quotes around --spec globs in shells that expand *.
• Assuming open mode behaves identically to CI headless timing.
• Using a vague grep string that matches half the suite.
• Debugging only in open mode and never confirming with cypress run.
• Leaving exclusive tests in shared support files.
• Treating it.skip as a focus tool (it excludes, it does not isolate).
• Running a single test against production without safeguards.
• Ignoring root beforeEach hooks that still dominate runtime in a "single" test.

Conclusion

For cypress how to run a single test, match the isolation tool to the job. Use it.only or the open-mode picker for rapid local debugging, --spec for clean file selection, and grep or tags when titles matter across files. Keep CI free of committed focus markers so a debugging habit never becomes silent coverage loss.

Pick one failing example from your last pipeline, reproduce it with --spec, tighten to a single title if needed, fix it, then re-expand to the full file. That narrow-wide loop is the professional habit that keeps large Cypress suites fast to debug and safe to ship.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• How to Debug a failing test in VS Code in Cypress (2026)
• How to Run a single test in Playwright (2026)
• How to Run a single test in Selenium (2026)
• How to Debug a failing test in VS Code in Playwright (2026)
• How to Debug a failing test in VS Code in Selenium (2026)
• How to Run tests in headed mode in Cypress (2026)