What is the Best Way to Run Specific Cypress Tests

Why Run Specific Tests in Cypress?

Running the full test suite every time can quickly become a bottleneck, especially for large applications. You may make a small change, but then wait minutes for unrelated tests to complete. Failures in unrelated tests can distract you, and repeated long waits make debugging frustrating. Targeting specific tests solves these issues and keeps your workflow efficient.

Here are practical reasons to run specific tests in Cypress:

• Verify only the changed feature: If you updated a login form, running only the tests for authentication ensures you focus on that feature without waiting for unrelated modules like dashboards or reports.
• Isolate failing tests quickly: When a test fails, rerunning only that test or its file allows you to debug immediately without rerunning the full suite.
• Optimize CI pipelines: Large CI workflows can be slow and costly. Running targeted tests reduces pipeline runtime and speeds up feedback loops.
• Test dynamic or conditional features: For single-page applications or feature flags, you can run only the tests relevant to the current route or enabled feature, avoiding false positives from inactive sections.
• Support parallel or distributed execution: When executing tests across multiple machines, targeting specific files ensures each node runs only the relevant tests, improving efficiency and resource utilization.

How to Install and Set Up Cypress

Before you can run specific tests, you need a working Cypress setup. Installing Cypress is straightforward, but a proper configuration ensures smooth test execution and makes targeting individual tests easier.

Here’s how to get started:

• Install via npm: Run npm install cypress --save-dev in your project folder. This ensures Cypress is added as a development dependency and stays consistent across your team.
• Open Cypress for the first time: Use npx cypress open to launch the Test Runner. Cypress will automatically create a cypress/ folder with example tests and the default configuration.
• Organize your test files: Place your tests in cypress/e2e/ (or your preferred folder). Structuring tests by feature or module makes it easier to run specific files later.
• Configure baseUrl: In cypress.config.js, set a baseUrl to simplify test commands. For example, if your app runs on http://localhost:3000, this allows cy.visit('/') instead of repeating the full URL in every test.
• Set environment variables (optional): Use env in the Cypress config or CLI to pass data like API keys or feature flags. This is particularly useful when skipping or targeting tests based on conditions.
• Verify installation: Open the Cypress Test Runner and check that the example tests run correctly. This confirms that your environment is ready for running specific tests.

With Cypress installed and configured, you can now write tests that are easy to target and manage. Proper setup ensures you spend less time troubleshooting setup issues and more time running the tests that actually matter.

Create Your First Test in Cypress

Before you can run specific tests, you need a test to target. Creating a well-structured test ensures it can be easily isolated, skipped, or filtered when running only a subset of your suite. Here’s how to get started:

Step 1: Create a new test file

Inside your cypress/e2e/ folder, create a new file for your test. For example, login.spec.js. Structuring tests by feature or module helps later when you want to run just a single file.

Step 2: Import Cypress and describe your test suite

Start by using the describe block to define your test suite. For example:

The describe block groups related tests, making it easier to filter or run them selectively.

Step 3: Write your first test case

Use the it block to write individual test cases. For example:

Each it block represents a single test scenario, which you can target later using keywords or file names.

Step 4: Save and run

Once your test is written, save the file. You can now run it using the Test Runner or CLI to verify it works as expected. Proper naming of files and test cases ensures you can run specific tests efficiently.

How to Run a Single Test File in Cypress

Once you have multiple test files, running the entire suite every time becomes inefficient. If you are working only on the login feature, there is no reason to execute tests for payments, dashboards, or reports. Cypress allows you to run a single test file directly from the command line or through the Test Runner.

Here is how to do it properly.

Step 1: Identify the test file path

Go to your cypress/e2e/ folder and note the exact file name. For example:

You need the correct relative path because Cypress uses it to determine which file to execute.

Step 2: Run the test using the CLI in headless mode

Use the following command:

The --spec flag tells Cypress to execute only the specified file instead of the entire suite. This is the most common and reliable way to run a specific test file, especially in CI pipelines.

Step 3: Run the file in interactive mode (optional)

If you prefer the visual Test Runner, use:

Then manually click on login.spec.js in the UI. This runs only that file in interactive mode, which is useful for debugging.

Step 4: Use glob patterns for multiple specific files (advanced)

If you want to run more than one targeted file, you can use patterns:

This runs all test files inside the auth folder while skipping the rest of the suite.

Running a single test file gives you faster feedback, cleaner debugging, and better control over execution scope. It becomes especially powerful when combined with keyword filtering or conditional skipping, which we will cover next.

Run Your First Cypress Test on BrowserStack

Running a single test locally is useful for quick feedback. However, local execution only reflects your machine’s browser and environment. If your users access the app from different browsers or operating systems, you need to validate your specific test there as well. That is where tools like BrowserStack become relevant.

Instead of running the entire suite on a cloud grid, you can run only the targeted test file you are working on. This keeps cloud execution focused and efficient.

Here’s how BrowserStack helps when running specific Cypress tests:

• Cross-browser validation for a single test: Run only the targeted spec file across Chrome, Firefox, Edge, or Safari without executing the entire suite on every browser.
• Parallel execution of specific files: Even if you are testing just one module, BrowserStack can run that file across multiple browser and OS combinations simultaneously, reducing overall validation time.
• Real device and OS coverage: Validate your specific test against real browser environments instead of local emulators, which improves accuracy for UI and rendering issues.
• CI-friendly targeted execution: Integrate focused test runs into CI pipelines so only impacted test files execute after a commit, reducing pipeline duration.
• Debugging support with logs and videos: When a specific test fails on a certain browser, you get session logs, screenshots, and recordings, making root cause analysis faster.
• Scalable infrastructure without local limits: You do not depend on your local machine’s resources, which is especially useful when validating targeted tests across multiple environments.

How to Test Single Page Apps with Cypress

Single Page Applications behave differently from traditional multi-page apps. Routes change without full page reloads, content renders dynamically, and components update based on API responses. Because of this, running specific tests in SPAs requires careful targeting.

When working with SPAs, you typically want to run only the tests related to the route, feature, or component you modified.

Here’s what matters when targeting specific tests in SPAs:

• Target route-specific test files: Organize tests by routes such as dashboard.spec.js or profile.spec.js. If you update the profile component, run only the profile-related spec file instead of the entire app suite.
• Focus on component-driven scenarios: In SPAs, UI changes often affect isolated components. Structure your tests around these components so they can be executed independently.
• Handle dynamic rendering correctly: Since SPAs load data asynchronously, use proper waiting strategies like cy.intercept() and cy.wait() to ensure your specific test remains stable and does not fail due to timing issues.
• Test state-based behavior: Many SPA features depend on application state. When running a specific test, ensure the test sets up its required state instead of relying on previous tests.
• Avoid cross-test dependency: In SPAs especially, tests must be independent. This allows you to safely run a single spec file without needing the rest of the suite to execute first.

How to Target Individual Files in Cypress Command Line

The command line gives you precise control over which tests run. This is essential when you want to execute a specific file, folder, or pattern without opening the interactive runner.

The most important tool here is the --spec flag.

To run a single file:

To run multiple specific files:

To run an entire folder:

You can also use glob patterns for more flexible targeting:

This allows pattern-based execution, which is extremely useful in large projects where tests are grouped by feature or naming convention.

Using CLI targeting is especially powerful in CI pipelines. Instead of triggering the full suite after every commit, you can configure your pipeline to run only the impacted test files based on file changes. This keeps feedback fast and reduces resource consumption.

How to Skip Tests Based on Conditions in Cypress

Sometimes you do not just want to run a specific file. You want certain tests to run only under specific conditions. This is common when features are environment-based, behind flags, or dependent on external services.

Cypress allows you to control execution dynamically so you can skip tests based on environment variables, runtime values, or configuration settings.

One common approach is using environment variables.

For example, suppose a feature exists only in staging:

You can pass environment variables through the CLI:

This ensures that specific tests run only when the correct environment is active.

Another practical approach is conditional logic inside hooks:

Using this.skip() inside a before hook skips all tests in that suite when the condition fails. This is useful when a feature flag controls whether functionality exists.

You can also combine conditional skipping with CI pipelines. For example, smoke tests can run on every commit, while heavier regression tests run only on scheduled builds. This keeps targeted execution aligned with development workflows.

However, conditional skipping should be used carefully. Overusing it can make test behavior unpredictable. Each test should clearly document why it is conditionally skipped, so other team members understand execution logic.

Conditional execution adds flexibility, but it works best when paired with structured test organization and clear naming conventions.

Best Practices for Running Specific Cypress Tests

Running specific tests in Cypress is powerful, but without structure it can create confusion, hidden dependencies, and inconsistent CI behavior. Targeted execution should improve speed and clarity, not introduce unpredictability. The following best practices ensure that running specific tests remains reliable and scalable.

• Keep tests independent and stateless: A specific test file should not depend on another test running before it. Avoid shared state between tests and always set up required data within the test or in hooks. This ensures you can run a single spec file without unexpected failures.
• Use feature-based file organization: Structure spec files by feature or module such as auth, checkout, or profile. This makes CLI targeting intuitive and prevents random grouping that complicates selective execution.
• Name test files and cases clearly: File names and describe blocks should reflect functionality precisely. For example, login-validation.spec.js is more useful than test1.spec.js. Clear naming improves both CLI filtering and keyword-based execution.
• Avoid leaving .only() in committed code: While .only() is useful during debugging, committing it accidentally can cause CI pipelines to run only a single test and ignore the rest of the suite. Use it locally, then remove it before pushing changes.
• Design for CI efficiency: When using targeted runs in CI, define clear rules for when to run specific tests versus full regression. For example, run feature-specific tests on pull requests and full regression nightly. This balances speed and coverage.
• Use tags or naming conventions for filtering: If your suite grows large, adopt consistent naming or tagging strategies. This allows you to filter tests by keyword without restructuring the entire suite later.
• Document conditional logic clearly: If tests are skipped based on environment variables or feature flags, document the reason. Hidden execution logic can confuse teams and reduce trust in test outcomes.

Conclusion

Running specific tests in Cypress gives you better control over your testing workflow. Instead of executing the entire suite every time, you can target individual files, filter by keywords, skip irrelevant scenarios, and isolate failures quickly. This improves debugging speed, reduces unnecessary execution time, and keeps development aligned with the features you are actively building.

However, running specific tests locally only validates behavior in your own environment. With BrowserStack, you can execute those same targeted Cypress tests across real browsers and operating systems without increasing execution overhead. This ensures that focused test runs remain efficient while still delivering broad cross-browser confidence and makes your targeted testing strategy both fast and reliable.

Try BrowserStack for Free