Automatically Split E2E Tasks by File (Atomizer)
End-to-end (e2e) tests are often large, monolithic tasks that can take a considerable amount of time to execute. As a result, teams often push them to a nightly or even weekly build rather than running them for each PR. This approach is suboptimal as it increases the risk of merging problematic PRs.
Manually splitting large e2e test projects can be complex and require ongoing maintenance. Nx's Atomizer solves this by automatically generating runnable targets for e2e tests for each spec file. Instead of one large e2e task, you get multiple smaller e2e tasks that can be run individually. This allows for:
- parallelization across multiple machines with Nx Agents
- faster flakiness detection & retries by isolating and re-running only the failed tests
Enable Automated e2e Task Splitting
Step 1: Connect to Nx Cloud
To use automated e2e task splitting, you need to connect your workspace to Nx Cloud (if you haven't already).
❯
npx nx connect
See the connect to Nx Cloud recipe for all the details.
Step 2: Add the Appropriate Plugin
Run this command to set up inferred tasks and enable task splitting for each plugin:
❯
nx add @nx/cypress
This command will register the appropriate plugin in the plugins array of nx.json.
If you upgraded Nx from an older version, ensure that inferred tasks are enabled in nx.json:
1{
2 ...
3 // turned on by default; just make sure it is not set to false
4 useInferencePlugins: true
5}
6Update an Existing e2e Project to use Automated Task Splitting
If you are already using the @nx/cypress, @nx/playwright, or @nx/jest plugin, you need to manually add the appropriate configuration to the plugins array of nx.json. Follow the instructions for the plugin you are using:
Verify Automated Task Splitting Works
Run the following command to open the project detail view for the e2e project:
❯
nx show project my-project-e2e
If you configured Nx Atomizer properly, you'll see that there are tasks named e2e, e2e-ci and a task for each e2e test file.
During local development, you’ll want to continue using e2e as it is more efficient on a single machine.
❯
nx e2e my-project-e2e
The e2e-ci task truly shines when configured and run on CI.
Configure Automated Task Splitting on CI
Update your CI pipeline to run e2e-ci, which will automatically run all the inferred tasks for the individual e2e test files. Here's an example of a GitHub Actions workflow:
1name: CI
2# ...
3jobs:
4 main:
5 runs-on: ubuntu-latest
6 steps:
7 - uses: actions/checkout@v4
8 with:
9 fetch-depth: 0
10
11 - uses: pnpm/action-setup@v4
12 with:
13 version: 9
14
15 - run: pnpm dlx nx-cloud start-ci-run --distribute-on="3 linux-medium-js" --stop-agents-after="e2e-ci"
16
17 - uses: actions/setup-node@v3
18 with:
19 node-version: 20
20 cache: 'pnpm'
21
22 - run: pnpm install --frozen-lockfile
23 - uses: nrwl/nx-set-shas@v4
24
25 - run: pnpm exec nx affected -t lint test build e2e-ci
26Learn more about configuring your CI provider by following these detailed recipes.