What is the Nx Atomizer and why is one test target a poor unit of work?
Atomization is a feature of Nx inference plugins. When the Playwright or Jest plugin processes a project, it reads the runner's config, finds the test files that config would match, and generates one task for each file. It also generates a parent CI target that depends on all of those per-file tasks. The Playwright plugin commonly names this parent something like e2e-ci, with child tasks named after the files they run. Because the parent is a normal target, nx affected -t e2e-ci still works as a single command. Nx expands it into the file-level tasks and schedules them.
A single test or e2e target is a poor unit of work for three reasons:
- It cannot be split. The task graph treats one target as one task, so it runs on one machine. A 40-minute suite takes at least 40 minutes, however many CI agents are available.
- Failures are coarse. If one flaky file fails, the whole target fails. A retry reruns every file, including the ones that already passed.
- The cache is all-or-nothing. The target stores one result. If you change a single spec, nothing from that target's cache can be reused, and the whole suite runs again.
With atomized tasks, each file has its own cache entry and its own retry, and Nx can schedule each one on any agent:
nx affected -t e2e-ci- Agent 1:
e2e-ci--checkout.spec.ts,e2e-ci--cart.spec.ts - Agent 2:
e2e-ci--login.spec.ts,e2e-ci--search.spec.ts - Agent 3:
e2e-ci--profile.spec.ts(cache hit, not run)
- Agent 1:
playwright.config.ts ──> Nx Playwright plugin (inference): finds the
spec files, generates one task per file
plus a parent CI target that depends on them
$ nx affected -t e2e-ci ─────────┐
┌──────────────▼──────────────┐
│ e2e-ci (parent CI target) │
└──────────────┬──────────────┘
│ dependsOn per-file tasks
┌───────────────────────┼───────────────────────┐
▼ ▼ ▼
┌─ Agent 1 ──────────┐ ┌─ Agent 2 ──────────┐ ┌─ Agent 3 ──────────┐
│ checkout.spec.ts │ │ login.spec.ts │ │ profile.spec.ts │
│ cart.spec.ts │ │ search.spec.ts │ │ cache hit: not run │
└────────────────────┘ └────────────────────┘ └────────────────────┘
Each box lists per-file tasks, named e2e-ci--<file>.
Each task has its own cache entry and its own retry.
The Playwright plugin turns one e2e suite into per-file tasks under a parent e2e-ci target, so a single nx affected -t e2e-ci command fans out across agents and skips files that hit the cache.
Who should use it, and when should you avoid it?
That layout pays off under specific conditions. The atomizer fits best when e2e runs are slow enough to block merges, when a few flaky spec files keep forcing full reruns, and when CI can spread tasks across several agents. Each file becomes its own cache entry, so a passing cart.spec.ts is not re-executed because checkout.spec.ts failed.
The costs are real:
- Per-task overhead. Every atomized task pays for process startup, browser launch and any global setup. For a spec that runs in a few seconds, that overhead can exceed the test time.
- Limited gains without distribution. On one runner, the split tasks mostly compete for the same CPU and memory. You get caching and clearer failures, but little wall-clock improvement.
- A larger, noisier task graph. Hundreds of
e2e-ci--*tasks make run summaries and affected output harder to scan. - Fragmented reports. Each task writes its own results, which need merging later (section 6).
| Repo situation | Recommendation |
|---|---|
| Long e2e suite, flaky files, distributed agents available | Adopt |
| Long suite, single runner, distribution planned | Adopt, expect caching gains first |
| Single runner, no distribution plan | Delay |
| Small suite that finishes quickly | Skip |
| Specs depend on run order or shared mutable state | Fix isolation first (section 5) |
| Projects still on explicit executor targets | Migrate to inferred plugin targets first |
The last row matters because the atomizer generates split targets through inferred tasks. Hand-written executor targets in project.json do not get them.
How do you set up the Nx Atomizer for Playwright and Jest?
Step 1: Check which targets are inferred
Open the project's project.json. A target with an executor field, such as @nx/playwright:playwright or @nx/jest:jest, is hand-written, and the atomizer will not split it. Inferred targets usually do not appear in project.json. Nx builds them at graph time from the plugin and the tool's own config file (playwright.config.ts, jest.config.ts). If a target name appears in both places, the explicit entry wins. Delete the hand-written target, or rename it, before you continue.
Step 2: Register the plugins with a CI target name
In the plugins array of nx.json, add @nx/playwright/plugin and @nx/jest/plugin. Give each one the option that names the split CI target. This is commonly ciTargetName, with values such as e2e-ci and test-ci. Option names and defaults have changed between releases, so check them against the docs for your installed Nx version. Pin that version so an upgrade cannot rename your targets without warning.
Step 3: Confirm the generated targets
Run nx show project <name> --web. You should see one target per test file, such as e2e-ci--src/login.spec.ts. You should also see a parent e2e-ci target that depends on all of them. If the per-file targets are missing, the plugin did not match the config file. If e2e-ci exists but has no dependencies, the same problem applies.
Step 4: Run the parent target
In CI, call nx run-many -t e2e-ci or nx affected -t e2e-ci. Nx schedules each file as its own task, caches it, and can distribute it across agents.
Jest usually gains less from this than e2e suites do. Each atomized task pays the full cost of starting Jest, loading config and transforming modules. In a unit test file that runs in seconds, that fixed overhead is a large share of the runtime. In a Playwright file that runs for minutes, the same overhead is negligible.
# Step 2: plugins fragment to merge into the existing "plugins" array in nx.json.
# Option names follow recent Nx releases; check them against the docs for your
# installed version, and pin @nx/* versions in package.json.
cat <<'EOF'
{
"plugins": [
{
"plugin": "@nx/playwright/plugin",
"options": { "targetName": "e2e", "ciTargetName": "e2e-ci" }
},
{
"plugin": "@nx/jest/plugin",
"options": { "targetName": "test", "ciTargetName": "test-ci" }
}
]
}
EOF
# Step 1: hand-written targets live in project.json with an "executor" field.
# Inferred targets do not appear here, so a match means the atomizer won't split that target.
grep -n '"executor"' apps/shop-e2e/project.json
# Step 3: open the project graph view. Look for per-file targets such as
# e2e-ci--src/login.spec.ts and a parent e2e-ci target that depends on them.
nx show project shop-e2e --web
# Step 4 (CI): run the parent targets. Each test file runs as its own cacheable task.
nx affected -t e2e-ci test-ci
# or, to run them across every project:
nx run-many -t e2e-ci test-ci
Registers the Playwright and Jest plugins with CI target names, checks project.json for hand-written executor targets, inspects the generated per-file and parent targets, and runs the parent targets in CI.
What does the cache actually key on for atomized tasks?
Splitting a target into per-file tasks does not split its inputs. Each generated task, such as e2e-ci--src/checkout.spec.ts, usually inherits the project's input definition, which is typically a named input like default or production from nx.json plus the ^production inputs of its dependencies. If those inputs cover the whole project's source tree, editing one component changes the hash of every atomized task. You get finer-grained retries and scheduling, but your cache hit rate stays about the same.
Check this before assuming file-level invalidation. Run nx show project <name> and look at the inputs listed for one atomized task. Then use this procedure:
- Run the full split target twice in a row. The second run should be served entirely from cache. If it isn't, something non-deterministic is in the inputs, such as a generated file or an environment variable, and you need to fix that first.
- Edit one spec file and run the target again. Ideally, only that file's task misses the cache.
- Revert the change, then edit one shared source file, such as a page component or an API client. Run again and count the misses.
- Edit a file covered by
sharedGlobals, such as a root config, and repeat.
If step 3 invalidates every task, the inputs are project-wide. You can narrow a named input, for example by excluding other spec files from each task's view. Only do this when you can prove the narrower set still captures everything the test depends on. Excluding a file the test actually needs produces stale cache hits, which are worse than cache misses.
#!/usr/bin/env bash
# Probe what actually invalidates atomized tasks in one project.
# Assumes a clean git working tree. Placeholder project, target and paths.
set -euo pipefail
PROJECT=shop-e2e
TARGET=e2e-ci
SPEC=apps/shop-e2e/src/checkout.spec.ts
SHARED=apps/shop/src/app/cart/cart-page.tsx
GLOBAL=tsconfig.base.json
# Inspect the resolved inputs of one generated per-file task.
nx show project "$PROJECT" --json \
| jq --arg t "$TARGET--src/checkout.spec.ts" '.targets[$t].inputs'
# Run the split target and print Nx's cache summary line.
probe() {
echo "== $1"
nx run "$PROJECT:$TARGET" --outputStyle=static 2>&1 \
| grep -i 'from the cache' || echo 'no tasks were served from cache'
}
# Edit a file, probe, then restore it so each step starts from the same state.
probe_edit() {
echo '// cache probe' >> "$2"
probe "$1"
git checkout -- "$2"
}
probe 'baseline (populates cache)'
probe 'repeat: expect every task from cache'
probe_edit 'edited one spec: expect one miss' "$SPEC"
probe_edit 'edited shared source: count misses' "$SHARED"
probe_edit 'edited sharedGlobals file: expect all misses' "$GLOBAL"
A repeatable shell probe that prints the inputs of one atomized task, then edits a spec file, a shared source file, and a global config file one at a time and reports how many tasks Nx served from cache after each edit.
How do you make Playwright suites safe to split and run in parallel?
On one machine, Nx runs atomized tasks concurrently up to its --parallel limit, but the real ceiling is shared resources. Each task is a separate Playwright invocation, so two tasks that both bind port 3000, or both truncate the same test database, will fail in ways that look random. Across machines, a distributed task runner schedules each spec file independently. You cannot assume two files run in the same process, the same order, or on the same host.
What repeats per task
Everything Playwright does once per run now happens once per file. The webServer command starts a fresh server for every task, globalSetup runs every time, and any login flow that writes a storageState file runs again. Make these steps cheap and idempotent. Write auth state to a path that includes a task-specific value rather than a fixed file that concurrent tasks overwrite.
Avoiding collisions
Read the server port from an environment variable and pass the same value to both webServer.port (or url) and use.baseURL. Then have each task receive a distinct value, either from your CI matrix or from a free-port lookup in the config. Apply the same idea to data. Derive a database name, schema, or tenant ID per task, create it in globalSetup, and drop it in globalTeardown.
Finding ordering dependencies
A file that only passes after another file has seeded data will break once it runs alone. To catch this, run each atomized task by itself with --skip-nx-cache against a clean environment. Any file that fails in isolation but passes in the full suite depends on another file's side effects.
// playwright.config.ts: one config, safe to run as many concurrent atomized tasks
import { defineConfig } from '@playwright/test';
import path from 'node:path';
// CI (matrix or agent) gives each task a distinct port and ID.
// Local default keeps a single plain run working.
const port = Number(process.env.E2E_PORT ?? 3000);
const taskId = (process.env.E2E_TASK_ID ?? `local_${port}`).replace(/[^a-z0-9_]/gi, '_');
const baseURL = `
// Per-task resource names, exported so globalSetup/teardown and the app agree.
process.env.E2E_DB_NAME = `app_e2e_${taskId}`;
process.env.E2E_STORAGE_STATE = path.join('.auth', `${taskId}.json`);
export default defineConfig({
// Creates E2E_DB_NAME, seeds it, logs in, writes E2E_STORAGE_STATE.
// Runs once per task, so it must be fast and idempotent.
globalSetup: './e2e/global-setup.ts',
// Drops E2E_DB_NAME so repeated runs start clean.
globalTeardown: './e2e/global-teardown.ts',
use: {
baseURL, // same value the server binds to
storageState: process.env.E2E_STORAGE_STATE, // never shared between tasks
},
webServer: {
command: 'npm run start:e2e',
url: baseURL,
// Don't attach to a server another task started on this port.
reuseExistingServer: false,
env: {
PORT: String(port),
DATABASE_NAME: process.env.E2E_DB_NAME,
},
timeout: 120_000,
},
});
A Playwright config that gives each atomized task its own port, database name and auth state file, all derived from environment variables. Concurrent tasks then never share a server, data or login state.
How do you keep reports, coverage and retries useful after splitting?
Atomizing changes the shape of your test output. Instead of one run producing one report, you get one report per file, each written by a separate task that may have run on a different agent or come straight from cache. CI dashboards expect a single artifact, so you need an explicit merge step after all tasks finish.
Merging Playwright reports
Configure each atomized task to emit Playwright's blob reporter into a directory unique to that file. A final CI step collects those blobs and combines them with playwright merge-reports into one HTML or JUnit report. Cached tasks matter here. If a task's output directory is not declared in its outputs, a cache hit restores nothing, and that file's results disappear from the merged report even though they passed.
Merging Jest coverage
Jest coverage needs similar planning. Each per-file run writes its own coverage map, and nothing combines them for you. Write each map to its own directory, then merge them with an Istanbul-compatible tool before you generate the final report. Move coverageThreshold checks to the merged result. A global threshold applied to a single file's run measures the wrong thing and will fail or pass for meaningless reasons.
Retries
Retrying an atomized task re-runs one file instead of the whole suite. That is cheap, and cheap retries make flakiness easy to ignore. A file that passes on its second attempt shows up as green. Record retry counts per file, publish them alongside the merged report, and flag files that retry repeatedly so someone owns the fix.
Does splitting e2e tests save time? An illustrative estimate and the alternatives
Retries hide flakiness. Illustrative estimate (assumed numbers, not a benchmark): 120 spec files, 45 s average per file, 20 s per-task startup overhead (browser launch, web server boot), 6 CI agents each running 2 tasks concurrently, compared against one target on one machine with 4 Playwright workers.
- Single target:
N × d / W= 120 × 45 / 4 = 1,350 s (about 22.5 min) - Atomized:
N × (d + o) / (A × p)= 120 × 65 / 12 = 650 s (about 11 min) - Rerun after a change that affects 20 files, with the rest restored from cache: 20 × 65 / 12 ≈ 110 s
Now change one input. If files average 10 s, the atomized run takes 120 × 30 / 12 = 300 s, which matches the single target exactly. The per-task startup overhead cancels the extra parallelism. Atomization pays off when file duration is large compared with startup cost. Neither layout can finish faster than the slowest single file.
The engineering-time gain comes mostly from cheap reruns and shorter feedback loops, not from the first full run. You pay for it upfront by removing shared state between specs, and later by keeping plugin configuration in step with your runner setup.
| Approach | Cache granularity | Parallelism scope | Rerun cost | Maintenance |
|---|---|---|---|---|
| Single target, runner workers | Whole suite | One machine | Full suite | Lowest |
| Playwright sharding | None per shard | Many machines, fixed shard count | Full shard | Low; shards drift out of balance |
| Manual targets in project.json | Per hand-made group | Many machines | Affected group | High; groups go stale |
| Atomizer with distribution | Per file | Many machines, scheduled dynamically | Affected files only | Medium; needs isolated specs |
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to nx atomizer, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.