Skip to content
Back to Knowledge Base

Automatically Split Slow Tasks by File (Atomizer)

Certain tasks like end-to-end (e2e) tests, integration tests, or large unit test suites can be large, monolithic tasks that 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 these slow tasks can be complex and require ongoing maintenance. Nx Atomizer solves this by automatically generating runnable targets for each test file. For example, a task that takes 10 minutes can be split and distributed as five 2-minute tasks per agent. This allows for:

Enable automated task splitting

Section titled “Enable automated task splitting”

Step 1: Connect to Nx Cloud

Section titled “Step 1: Connect to Nx Cloud”

To use automated task splitting, you need to connect your workspace to Nx Cloud (if you haven't already).

Terminal window
npx nx@latest connect

Connect from your browserSign in to Nx Cloud and connect your repository without the CLI

For the full pipeline walkthrough, see Setting Up CI.

Step 2: add the appropriate plugin

Section titled “Step 2: add the appropriate plugin”

Run this command to set up inferred tasks and enable task splitting for each plugin:

Terminal window
nx add @nx/cypress

This command will register the appropriate plugin in the plugins array of nx.json.

Update an existing project to use automated task splitting

Section titled “Update an existing project to use automated task splitting”

If you are already using the @nx/cypress, @nx/playwright, @nx/jest, @nx/vitest, or @nx/gradle 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

Section titled “Verify automated task splitting works”

Run the following command to open the project detail view for your test project:

Terminal window
nx show project my-project-e2e

If you configured Nx Atomizer properly, you'll see that there are tasks named e2e, e2e-ci (or similar for other test types) and a task for each test file.

During local development, you'll want to continue using the base task (e.g., e2e, test) as it is more efficient on a single machine.

Terminal window
nx e2e my-project-e2e

The -ci variant task truly shines when configured and run on CI.

Configure automated task splitting on CI

Section titled “Configure automated task splitting on CI”

Update your CI pipeline to run the -ci variant task (e.g., e2e-ci, test-ci), which will automatically run all the inferred tasks for the individual test files. Distribution and stop conditions come from your .nx/ci-config.yaml file:

.nx/ci-config.yaml
dte:
  distribute-on: 3 linux-medium-js
lifecycle:
  stop-after:
    - e2e-ci

Here's an example of a GitHub Actions workflow:

.github/workflows/ci.yml
name: CI
# ...
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          filter: tree:0


      - uses: pnpm/action-setup@v6
        with:
          version: 9


      - run: pnpm dlx nx-cloud start-workers


      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: 'pnpm'


      - run: pnpm install --frozen-lockfile
      - uses: nrwl/nx-set-shas@v5


      - run: pnpm exec nx affected -t lint test build e2e-ci

Learn more about configuring your CI provider with these workflow examples.

Skip unaffected test files

Section titled “Skip unaffected test files”

Splitting an e2e suite lets its test files run in parallel, but by default each task still depends on the whole app, its dependencies, and the e2e project. Even a small change can rerun every test file.

Scoping each test file to the code it tests lets Nx reuse the other files' cached results. For example, a change limited to checkout reruns checkout.spec.ts, while search.spec.ts reuses its cached result. A change to shared code that both tests depend on reruns both.

This means fewer tests to execute on each PR, shorter CI runs, and lower compute costs as your suite grows.

Use @nx-ignore-server-inputs with Ultracache to track the code a test imports, or @nx-depends-on to list the projects it covers. See skip unaffected split e2e tests for examples and setup instructions.

Last updated: