How to Conditionally Skip Tests in Cypress the Right Way

When writing end-to-end tests in Cypress, you may encounter scenarios where you need to conditionally skip certain tests. Maybe you want to disable tests based on an environment variable, a feature flag, or a configuration setting. While it seems straightforward, there’s a common pitfall when trying to set the condition inside a before hook.

In this post, I’ll explain the problem and provide multiple ways to correctly handle conditional test execution in Cypress.

The Common Pitfall

A naive approach to skipping a test might look like this:

if (condition) {
    it('should run this test', () => {
        // test code
    });
}

This works fine if the condition is static. However, if the condition is determined inside a before hook, this approach fails because Cypress won’t even execute the before hook unless there’s at least one test to run.

The Fix: Place the Condition Inside the Test Block

Instead of skipping the test definition, move the condition check inside the it block:

it('should run this test only if condition is met', () => {
    if (!condition) {
        return;
    }

    // test code here
});

This ensures that the before hook runs, sets up the condition, and only then determines whether to run the test.

---

Alternative Approaches to Skipping Tests

1. Using Cypress.env() for Configuration-Based Skipping

If your condition is based on an environment variable, you can check it before defining tests:

if (Cypress.env('SKIP_TESTS')) {
    return;
}

it('should run only if SKIP_TESTS is false', () => {
    // test code
});

This is useful when you need to control test execution via external configurations.

2. Using this.skip() in a beforeEach Hook

If you need to dynamically determine whether to skip a test inside a beforeEach hook, use this.skip(), which is built into Mocha (Cypress’s underlying test framework):

beforeEach(function () {
    if (Cypress.env('SKIP_TESTS')) {
        this.skip();
    }
});

it('should be skipped when condition is met', () => {
    // test code
});

This approach is useful when multiple tests in a suite should be skipped dynamically.

3. Skipping Entire Suites Conditionally

If you want to conditionally skip an entire test suite (describe block), you can use:

(Cypress.env('RUN_TESTS') ? describe : describe.skip)('Conditional Test Suite', () => {
    it('test 1', () => {
        // test code
    });

    it('test 2', () => {
        // test code
    });
});

This method keeps the suite clean by completely excluding tests if RUN_TESTS is false or undefined.

Conclusion

Skipping tests conditionally in Cypress is essential for handling feature flags, environment differences, and flaky tests. However, you need to be careful about where and how you apply conditions, especially when dealing with before hooks.

To recap:

• Move conditions inside the it block to avoid skipping before hooks.
• Use this.skip() in beforeEach for dynamic skipping.
• Skip entire test suites using describe.skip.
• Leverage Cypress.env() for environment-based skipping.

By using the right approach, you can make your Cypress test suite more flexible and maintainable.