What are cacheable Nx integration tests with Testcontainers, and why are they usually excluded?
A cacheable integration-test target is an Nx target, usually named something like integration-test, that starts a throwaway Postgres container through Testcontainers, applies the project's migrations, runs the test suite against it, and then discards the container. Nx treats the run like any other cacheable task. It hashes the declared inputs, and if that hash matches a previous successful run, it replays the stored terminal output and artifacts instead of executing the tests again.
Most teams leave integration tests uncached for good reasons. The tests typically point at a shared staging database or a long-running local instance whose contents drift over time. A passing run might depend on rows another developer inserted, a migration applied by hand, or a sequence value left over from yesterday. Other sources of nondeterminism include wall-clock time, random ports, test ordering, and network calls to real services. When the outcome depends on state Nx cannot see, a cache hit only replays a result that may no longer be true, which is worse than no cache at all.
The precondition is strict. The test result must be a deterministic function of declared inputs: source files, migrations, test fixtures, the pinned database image, and relevant configuration. Nothing can come from a database that outlives the run.
When that holds, the payoff goes to backend and platform engineers in monorepos where CI spends much of its time rerunning database tests for projects whose code did not change.
How does a Testcontainers-backed Nx target work end to end?
On a cache miss, an Nx target runs the full Postgres container lifecycle. On a hit, it skips every step that involves Docker.
Hash first, then decide
Before anything runs, Nx computes a hash for the target. The hash covers the declared inputs: source files, migration files, test files, relevant config, and any environment variables or runtime values you list. Nx looks that hash up in the local cache first. If a remote cache is configured, it checks there next.
On a hit, Nx replays the recorded terminal output and restores any declared outputs, such as coverage or JUnit reports. The test runner never starts, so no global setup runs, nothing calls Docker, and no image is pulled. A hit costs about the same whether the suite takes ten seconds or ten minutes. That is the main payoff of caching here, because container startup and migrations are often the slowest part of the run.
What happens on a miss
On a miss, Nx invokes the test runner, and the runner's global setup runs before any test file loads. The setup does four things:
- Asks Testcontainers to start a Postgres container from a pinned image. The container's port 5432 is mapped to a random free port on the host, so parallel targets on the same machine don't collide.
- Waits until Postgres accepts connections.
- Applies migrations and loads seed data.
- Writes the resulting connection string into an environment variable before the test workers start.
The tests then read that variable. Global teardown stops and removes the container. Testcontainers' resource reaper acts as a backstop if the process crashes.
The random port and the connection string are deliberately left out of the inputs. They change on every run, so including them would guarantee a miss every time. After a successful run, Nx stores the logs and outputs under the hash, both locally and in the remote cache, so later runs can skip the container entirely.
+----------------------------------+
| Nx hashes declared inputs: src, |
| migrations, tests, config, env |
| (random port + URL excluded) |
+----------------------------------+
|
v
+--------------+ miss +-----------------+
| Local cache |------->| Remote cache |
+--------------+ | (if configured) |
| hit +-----------------+
| | hit | miss
v v |
+-------------------------------+ |
| Replay terminal output, | |
| restore outputs (JUnit, cov) | |
| No runner, no Docker, no pull | |
+-------------------------------+ v
+-----------------------------+
| Runner global setup: |
| 1 start pinned Postgres |
| 5432 -> random host port |
| 2 wait for connections |
| 3 apply migrations + seed |
| 4 export conn string to env |
| Tests run; teardown removes |
| container (reaper backstop) |
+-----------------------------+
|
v store result in local + remote cache
Nx checks the input hash against the local and then the remote cache. A hit replays logs and outputs without touching Docker, and a miss runs the Testcontainers setup, the tests and the teardown, then stores the result in the cache.
How do you define a separate integration-test target with precise named inputs?
Give the integration suite its own target, such as integration-test, next to the existing test target, and set it up in targetDefaults so every project uses the same rules. Unit tests can keep a narrow input set. The integration target needs a dedicated named input, for example integration. It should combine the project's production sources with integration spec files, the migrations directory, seed and fixture files, and the Testcontainers global setup file. Add ^production so that changes in shared libraries, such as a repository layer or a schema package, also invalidate the hash. Set cache: true explicitly, and use dependsOn to build upstream libraries first.
Each input you leave out lets a specific change reuse a stale pass:
| Omitted input | Change that goes unnoticed |
|---|---|
| Migration files | New NOT NULL column breaks inserts |
| Seed/fixture files | Edited fixture invalidates assertions |
| Global setup file | Postgres image tag bumped |
^production |
Shared query builder rewritten |
| Behavioral env vars | Feature flag flips a code path |
Declare only the env inputs that change behavior, such as feature flags or a database configuration value the code reads. Leave out anything that changes on every run, such as the random host port Testcontainers assigns or a CI run ID. Including those values makes every run a cache miss.
Keep a balance between too broad and too narrow. If you point inputs at {workspaceRoot}/** or the whole project root, then README edits and lint config changes will force a full container run. If the inputs are too narrow, real breakage gets cached as a pass. Start with the explicit list above, then add inputs only when you can name the change they would catch.
// nx.json (Nx parses this file with comments allowed)
{
"namedInputs": {
"default": ["{projectRoot}/**/*", "sharedGlobals"],
"sharedGlobals": [],
"production": ["default", "!{projectRoot}/**/*.spec.ts", "!{projectRoot}/test/**/*"],
// Everything that can change an integration result, and nothing else
"integration": [
"production",
"{projectRoot}/src/**/*.int-spec.ts",
"{projectRoot}/migrations/**/*",
"{projectRoot}/test/seed/**/*",
"{projectRoot}/test/fixtures/**/*",
// Pins the Postgres image tag and container config
"{projectRoot}/test/testcontainers.global-setup.ts",
// Behavioral env only. No random host ports or CI run IDs.
{ "env": "FEATURE_LEDGER_V2" },
{ "env": "DB_SCHEMA_NAME" }
]
},
"targetDefaults": {
// Unit tests keep a narrow input set
"test": {
"cache": true,
"inputs": ["default", "^production"]
},
"integration-test": {
"cache": true,
// ^production: changes to shared repository or schema libs invalidate the hash
"inputs": ["integration", "^production"],
// Build upstream libraries before starting containers
"dependsOn": ["^build"]
}
}
}
An nx.json fragment that defines a dedicated integration-test target with its own named input. The input covers sources, integration specs, migrations, seed and fixture files, the Testcontainers setup file and behavioral env vars, plus ^production for shared libraries.
Implementing global setup: pinned Postgres image, migrations and connection strings
Put the image reference in a small config module, for example integration.config.ts, and list that file in the target's inputs. Pin it to an explicit tag such as a full minor version, or better, a digest. Nx computes the hash from the files and values you declare. It does not inspect the image that Docker actually pulls. With a floating tag like latest or a bare major version, the registry can move the tag to a new build while every hashed input stays the same. The next run is then a cache hit, and Nx replays a result that was produced against a different Postgres. Because the reference lives in a hashed file, a deliberate upgrade changes the hash and forces a real run.
The global setup starts the container, then reads the host and mapped port from the running container instead of assuming 5432. Testcontainers assigns a random host port, so parallel targets on the same CI runner don't collide. Next, run migrations once against that database, using the same migration tool and files you ship. The migration directory is already part of the target's inputs. Finally, build the connection string and export it through an environment variable such as DATABASE_URL. Test workers start after global setup and inherit it. The matching global teardown stops the container. Do it explicitly rather than relying on process exit.
On Podman, Colima or Rancher Desktop, Testcontainers may not find the Docker socket on its own. You may need to set DOCKER_HOST, override the socket path with TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE, or disable the Ryuk cleanup container with TESTCONTAINERS_RYUK_DISABLED on rootless setups. Disabling Ryuk makes your explicit teardown the only cleanup, so leftover containers become your responsibility. Keep these variables out of the hash. They change how the container starts, not what the tests assert.
// integration.config.ts (listed in the target's inputs, so changing it changes the hash)
// Pin a full version; pinning a digest (postgres:16.4@sha256:<digest>) is stricter.
export const POSTGRES_IMAGE = 'postgres:16.4';
// global-setup.ts (referenced from vitest.config.ts via test.globalSetup)
import { execFileSync } from 'node:child_process';
import { PostgreSqlContainer, StartedPostgreSqlContainer } from '@testcontainers/postgresql';
import { POSTGRES_IMAGE } from './integration.config';
let container: StartedPostgreSqlContainer | undefined;
export async function setup() {
container = await new PostgreSqlContainer(POSTGRES_IMAGE).start();
// Testcontainers maps 5432 to a random free host port; read it, never assume it.
const host = container.getHost();
const port = container.getMappedPort(5432);
const url = `postgresql://${container.getUsername()}:${container.getPassword()}@${host}:${port}/${container.getDatabase()}`;
// Run the same migrations you ship, once, before any worker starts.
execFileSync('npm', ['run', 'db:migrate'], {
stdio: 'inherit',
env: { ...process.env, DATABASE_URL: url },
});
// Workers are spawned after global setup and inherit this variable.
process.env.DATABASE_URL = url;
}
export async function teardown() {
// Stop explicitly; with Ryuk disabled this is the only cleanup.
await container?.stop();
}
A pinned Postgres image reference in a hashed config file, plus a Vitest global setup that reads the mapped port, runs migrations, exports DATABASE_URL to workers, and stops the container in teardown.
Which isolation strategy should you use: transactions, schemas or truncation?
The isolation strategy decides whether parallel workers can share one database without seeing each other's rows. It also decides whether a cached result reflects real commit behavior.
| Strategy | Parallel workers | Speed | Isolation guarantee |
|---|---|---|---|
| Per-test transaction, rolled back | Safe only if every query uses the test's single connection | Fastest | Strong within one connection. Breaks if code opens its own pool or commits. |
| Schema (or database) per worker | Safe, because each worker has its own namespace | Fast after a one-time migration per worker | Strong, and real commits work |
| Truncation between tests | Unsafe on a shared schema, so it forces serial runs | Slower as the table count grows | Good, but only after cleanup runs |
Rollback is attractive until the code under test uses a connection pool. A second connection cannot see uncommitted rows, so tests fail for reasons production never hits. Truncation allows real commits, but two workers truncating the same tables will corrupt each other's state.
Schema per worker is the usual default:
- Derive the schema name from the runner's worker ID.
- Create the schema in the worker's setup.
- Run migrations against it.
- Pin
search_pathin that worker's connection string.
Tests then commit freely, and cleanup is a single DROP SCHEMA ... CASCADE.
One container or many
A single container started in global setup pays the Postgres startup cost once. Combined with per-worker schemas, it isolates workers well enough for most suites.
A container per worker or per file gives full process-level separation, including server settings and extensions. The cost is one startup per worker or file, which can exceed the test time itself. Reserve this for tests that change server-wide state.
// test/db.ts: per-worker schema helper, imported by integration test files.
// Assumes global setup started one Postgres container and exported DATABASE_URL.
import { Pool } from 'pg';
import { runMigrations } from './migrate'; // your project's migration runner
// Jest sets JEST_WORKER_ID (1, 2, ...) in each worker process.
const workerId = process.env.JEST_WORKER_ID ?? '1';
export const schema = `test_w${workerId}`; // derived, so it is safe to interpolate
export const pool = new Pool({ connectionString: process.env.DATABASE_URL });
// Pin search_path on every pooled connection. Code under test that opens
// extra connections from this pool still lands in this worker's schema.
pool.on('connect', (client) => {
client.query(`SET search_path TO ${schema}`);
});
export async function setupWorkerSchema(): Promise<void> {
// Start from a clean namespace. Other workers' schemas are untouched.
await pool.query(`DROP SCHEMA IF EXISTS ${schema} CASCADE`);
await pool.query(`CREATE SCHEMA ${schema}`);
// Migrations run unqualified, so they create tables in this schema.
await runMigrations(pool);
}
export async function teardownWorkerSchema(): Promise<void> {
// Tests committed real rows. One statement removes all of them.
await pool.query(`DROP SCHEMA IF EXISTS ${schema} CASCADE`);
await pool.end();
}
// In a test file:
// beforeAll(setupWorkerSchema);
// afterAll(teardownWorkerSchema);
A Jest helper that derives a Postgres schema name from the worker ID, creates the schema and migrates it, pins search_path on every pooled connection, and drops the schema with CASCADE when the tests finish, so workers that share one container never see each other's committed rows.
When should you avoid caching integration tests, and what are the alternatives?
Caching assumes that identical inputs produce an identical result. Some suites break that assumption, and a cached pass then stands in for a test that never actually ran.
- Flaky tests. One green run is stored. Every later run with the same inputs replays that pass, so the flakiness disappears from CI until an input changes. Fix or quarantine the test before you cache it.
- Hidden inputs. Calls to external services, reads of the current time, and unseeded randomness all affect the outcome, but Nx cannot hash them. A test that depends on
now()near a month boundary can pass once and stay cached long after it would start failing. - Environment drift across a remote cache. Collation, locale and extension behavior can differ by OS, CPU architecture or container runtime. A result produced on one developer's machine may not hold on a CI runner. Add the relevant environment values to the target's inputs, or restrict remote cache writes to CI.
The usual compromise is to split the suite. Hermetic tests go in a cacheable integration target. Tests with real time or network dependencies go in a sibling target with "cache": false, so CI runs them on every pipeline.
If you drop the cached Testcontainers target entirely, each alternative gives something up:
| Alternative | What it gives up |
|---|---|
| Uncached tests filtered by affected | Reuse across pipelines. Affected projects rerun on every push. |
| Long-lived shared test database | Isolation and reproducibility. State leaks between runs and branches. |
| In-memory or embedded substitute | Postgres fidelity, including types, locking, extensions and SQL dialect. |
| Mocking the data layer | Any check of real queries, migrations or constraints. |
How do you run cacheable integration tests in CI and verify cache behavior?
Docker in CI
The runner needs a reachable Docker daemon. On hosted VM runners this is usually available already. Containerized runners are harder: Docker-in-Docker typically requires privileged mode, and some managed or locked-down environments do not allow it. If privileged containers are disallowed, use a VM-based runner or mount the host's Docker socket, after checking that your security policy permits socket access. Either way, check daemon availability in an early step so the job fails clearly instead of timing out inside test setup.
Parallelism, affected and the shared cache
Each project's global setup starts its own Postgres container. Limit concurrency with nx affected -t integration-test --parallel=2, kept separate from unit-test runs, so the runner doesn't run out of memory or hit container startup timeouts. affected skips projects the change can't reach. A remote or shared cache lets CI and developers reuse each other's results for unchanged hashes.
Debugging unexpected hits and misses
When a hit or miss surprises you, run nx show project <name> and compare the resolved inputs against the files that changed. A miss on every run usually means a volatile input, such as a generated file or an unpinned image tag. A hit after a schema change means the migrations directory is missing from the inputs.
Cost and engineering time
Illustrative estimate. Assume 10 projects, each taking 40 seconds to start a container and migrate and 60 seconds to run tests, and assume a typical change affects two projects. Uncached, the run costs about 1,000 seconds. With affected and caching, it costs about 200. The trade-off is ongoing upkeep: someone has to keep the inputs list matched to what the tests actually read.
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 testcontainers integration tests, 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.