Custom Parallel Execution Using Tags:
To enhance the performance of Cypress tests, running them in parallel is a proven approach. While Cypress offers a built-in parallel execution feature, a more flexible and powerful method is tag-based parallel execution using a custom configuration. This method allows to fine-tune which tests are executed concurrently, based on tags in. feature files.
What Is Tag-Based Parallel Execution?
Tag-based execution filters test scenarios using custom tags (e.g., @login, @checkout) defined in you. feature files. Instead of running all tests or manually selecting files, this method dynamically identifies and runs only the tagged scenarios. It’s particularly useful for CI/CD pipelines and large test suites.
Key Components:
This approach uses several cores Node.js modules:
- child process – To execute terminal commands.
- glob – To search. feature files based on patterns.
- fs – To read file content for tag matching.
- crypto – To generate unique hashes for port management.
Execution Strategy:
1. Set Tags and Config via Environment Variables:
You define which tests to run by setting environment variables:
TAGS='@db'→ runs only tests with@dbtag<strong>THREADS=2→ number of parallel threadsSPEC='cypress/support/feature/*.feature'→ file location pattern
These variables help dynamically control test selection and concurrency.
2. Collect All Matching Feature Files:
Using the glob package, the script searches for all . feature files that match the provided pattern (e.g., *. feature). This gives a complete list of potential test files before filtering by tag.
3. Filter Feature Files by Tag:
Each . feature file is opened and scanned using fs.readFileSync(). If it contains the specified tag (like @db or @smoke), it gets added to the list for execution. This ensures only relevant tests run.
4. Assign Unique Ports for Each File:
To avoid port conflicts during parallel execution, the script uses crypto.createHash('md5') on the file path + tag combination. A slice of the hash becomes the unique port number. This is crucial when running UI-based tests in parallel.
5. Run Cypress Tests in Parallel:
The script spawns multiple Cypress instances using child_process.exec or spawn, one per tagged test file. Each command is built with its own spec file and unique port, and all are run simultaneously using Promises.
6. Error Handling and Logging:
If no files match the tag, the script logs a warning and exits cleanly. If any Cypress test fails, the corresponding error is caught, logged, and the overall process exits early to prevent false positives in CI pipelines.
7. Trigger the Execution from Terminal:
The full command is triggered from the terminal via a script in package.json:
"cy:parallel-tag-exec": "cross-env TAGS='@db' THREADS=2 SPEC='cypress/support/feature/*.feature' ts-node parallel-tag-config.ts"
8. Run the below command:
npm run cy:parallel-tag-exec
This executes the full workflow with just one command.
Complete TypeScript Code
The code handles the entire logic: matching tags, assigning ports, and running Cypress commands in parallel. Refer to the image below for the full implementation.
Benefits of This Approach:
- Greatly reduces overall test runtime.
- Offers flexibility with test selection using tags.
- Avoids port conflict issues through dynamic assignment.
- Works well with CI pipelines and large-scale projects.
Final Thoughts:
This custom configuration allows you to harness the full power of parallel testing with Cypress in a tag-specific, efficient manner. It’s scalable, highly customizable, and especially suitable for complex projects where targeted test runs are required.
For more information, you can refer to this website: https://testgrid.io/blog/cypress-parallel-testing/
Similar Approach for Cypress Testing:
- Cypress Grep Plugin – https://github.com/cypress-io/cypress-grep
Nx Dev Tools (Monorepo) – https://nx.dev/technologies/test-tools/cypress/api
Source: Read MoreÂ
