test(testcontainers): hoist container boot off the test timer (#4686)

## What

The one-off worker container boot is billed to whichever test resolves
the fixture first. This moves it into a `beforeAll` with its own
timeout.

## Why

vitest runs the fixture chain *inside* the test timer:

```js
// @vitest/runner 4.1.7
setFn(task, withTimeout(...withFixtures(handler)..., timeout, ...))
```

There is no `fixtureTimeout`. So booting Postgres (plus `CREATE
DATABASE`, schema push, ClickHouse and Redis) lands on the first test
and consumes a budget sized for test work.

That is why losing the image pre-pull on fork PRs was fatal rather than
merely slower: the extra ~10s crossed the 60s cap. Since fork time is
roughly internal + 10s and forks exceed 60s, internal runs were already
clearing that cap by under 10s — a latent flake regardless of forks.

## How

`withWarmup` wraps each fixture family and lazily registers a
`beforeAll` on first touch, with its own generous timeout. Registration
is lazy so only files that actually use a family pay for it —
`@internal/testcontainers` is imported by hundreds of test files, many
of which only need Redis. It registers once per file, since `isolate`
gives each file a fresh module registry.

Eight families are wrapped. `isolatedRedisTest`,
`replicationContainerTest` and `postgresAndRedisTest` are deliberately
untouched: they use per-test containers by design, so there is no
one-off boot to hoist.

No test file or CI changes, and it applies to every package using these
fixtures.

## Verification

Proven by mutation. `src/warmup.test.ts` runs container tests under a
deliberately tight cap:

| | Result |
| --- | --- |
| with the warm-up | passes |
| warm-up neutered | fails, `Test timed out` |

It is kept as a regression test — without it, unwrapping a fixture would
break nothing visibly.

`triggerFailedTask.call.test.ts`, one of the five shard casualties,
passes locally in 20.4s.

## Also here

`@internal/testcontainers` had no `test` script, so `turbo run test
--filter "@internal/*"` skipped the package and its existing
`heteroDedicated.test.ts` never ran in CI. Adding the script (matching
the sibling packages') runs both files; verified green through turbo
exactly as CI invokes it.

Author: nicktrn

internal-packages/testcontainers/package.json

@@ -26,6 +26,7 @@
     "tinyexec": "^0.3.0"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --sequence.concurrent=false --no-file-parallelism"
   }
 }

internal-packages/testcontainers/src/index.ts

@@ -314,10 +314,44 @@ const prismaFromContainer = async (
   }
 };
 
-export const postgresTest = test.extend<PostgresTestContext>({
-  postgresContainer: clonedPostgresContainer,
-  prisma: prismaFromContainer,
-});
+const CONTAINER_WARMUP_TIMEOUT_MS = 300_000;
+
+type WarmableTestApi = {
+  beforeAll: (fn: (context: any) => Promise<void>, timeout?: number) => void;
+};
+
+const withWarmup = <T extends WarmableTestApi>(
+  api: T,
+  warmUp: (context: any) => Promise<void>
+): T => {
+  const register = () => {
+    api.beforeAll(warmUp, CONTAINER_WARMUP_TIMEOUT_MS);
+  };
+
+  return new Proxy(api, {
+    apply(target, thisArg, args) {
+      register();
+      return Reflect.apply(target as unknown as (...a: unknown[]) => unknown, thisArg, args);
+    },
+    get(target, prop, receiver) {
+      if (prop !== "then") {
+        // awaiting the module is not use
+        register();
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  }) as T;
+};
+
+export const postgresTest = withWarmup(
+  test.extend<PostgresTestContext>({
+    postgresContainer: clonedPostgresContainer,
+    prisma: prismaFromContainer,
+  }),
+  async () => {
+    await getWorkerPostgresContainer();
+  }
+);
 
 type HeteroPostgresTestContext = {
   // PG14 (legacy / control-plane DB analog)
@@ -609,11 +643,16 @@ type RedisTestContext = {
 
 // Worker-scoped redis (boots once, FLUSHALL between tests). Use isolatedRedisTest for tests that run
 // background redis work (redis-worker Workers, BatchQueue) past the test body - see its note + README.
-export const redisTest = test.extend<RedisTestContext>({
-  redisContainer: [bootWorkerRedis, { scope: "worker" }],
-  resetRedis: [flushRedis, { auto: true }],
-  redisOptions,
-});
+export const redisTest = withWarmup(
+  test.extend<RedisTestContext>({
+    redisContainer: [bootWorkerRedis, { scope: "worker" }],
+    resetRedis: [flushRedis, { auto: true }],
+    redisOptions,
+  }),
+  async ({ redisContainer }) => {
+    void redisContainer;
+  }
+);
 
 // Per-test redis for tests with background redis work (redis-worker Workers, BatchQueue) that can
 // outlive the test body - a shared redis would let leaked work hit a closed connection / next test
@@ -723,11 +762,16 @@ const scopedClickhouseClient = async (
   }
 };
 
-export const clickhouseTest = test.extend<ClickhouseTestContext>({
-  clickhouseContainer: [bootWorkerClickhouse, { scope: "worker" }],
-  resetClickhouse: [truncateClickhouseFixture, { auto: true }],
-  clickhouseClient: scopedClickhouseClient,
-});
+export const clickhouseTest = withWarmup(
+  test.extend<ClickhouseTestContext>({
+    clickhouseContainer: [bootWorkerClickhouse, { scope: "worker" }],
+    resetClickhouse: [truncateClickhouseFixture, { auto: true }],
+    clickhouseClient: scopedClickhouseClient,
+  }),
+  async ({ clickhouseContainer }) => {
+    void clickhouseContainer;
+  }
+);
 
 // NOTE: per-test containers (not worker-scoped) - the replication package does logical replication
 // (slots/publications/REPLICA IDENTITY), which doesn't play nicely with a shared container +
@@ -755,17 +799,24 @@ type ContainerTestContext = {
 // The workhorse fixture (~36 files). Postgres (template-clone), Redis (FLUSHALL) and ClickHouse
 // (truncate) all boot once per worker - no per-test container boots. Use containerTestWithIsolatedRedis
 // for tests that run background redis work (BatchQueue, redis-worker Workers) past the test body.
-export const containerTest = test.extend<ContainerTestContext>({
-  postgresContainer: clonedPostgresContainer,
-  prisma: prismaFromContainer,
-  schemaOnlyPrisma: schemaOnlyPrismaFixture,
-  redisContainer: [bootWorkerRedis, { scope: "worker" }],
-  resetRedis: [flushRedis, { auto: true }],
-  redisOptions,
-  clickhouseContainer: [bootWorkerClickhouse, { scope: "worker" }],
-  resetClickhouse: [truncateClickhouseFixture, { auto: true }],
-  clickhouseClient: scopedClickhouseClient,
-});
+export const containerTest = withWarmup(
+  test.extend<ContainerTestContext>({
+    postgresContainer: clonedPostgresContainer,
+    prisma: prismaFromContainer,
+    schemaOnlyPrisma: schemaOnlyPrismaFixture,
+    redisContainer: [bootWorkerRedis, { scope: "worker" }],
+    resetRedis: [flushRedis, { auto: true }],
+    redisOptions,
+    clickhouseContainer: [bootWorkerClickhouse, { scope: "worker" }],
+    resetClickhouse: [truncateClickhouseFixture, { auto: true }],
+    clickhouseClient: scopedClickhouseClient,
+  }),
+  async ({ redisContainer, clickhouseContainer }) => {
+    void redisContainer;
+    void clickhouseContainer;
+    await getWorkerPostgresContainer();
+  }
+);
 
 type ContainerWithIsolatedRedisContext = {
   network: StartedNetwork;
@@ -780,16 +831,22 @@ type ContainerWithIsolatedRedisContext = {
 
 // Same as containerTest but Redis is PER-TEST - for tests whose background redis work (BatchQueue,
 // Workers) outlives the test body and would otherwise hit a closed/shared connection.
-export const containerTestWithIsolatedRedis = test.extend<ContainerWithIsolatedRedisContext>({
-  network,
-  postgresContainer: clonedPostgresContainer,
-  prisma: prismaFromContainer,
-  redisContainer,
-  redisOptions,
-  clickhouseContainer: [bootWorkerClickhouse, { scope: "worker" }],
-  resetClickhouse: [truncateClickhouseFixture, { auto: true }],
-  clickhouseClient: scopedClickhouseClient,
-});
+export const containerTestWithIsolatedRedis = withWarmup(
+  test.extend<ContainerWithIsolatedRedisContext>({
+    network,
+    postgresContainer: clonedPostgresContainer,
+    prisma: prismaFromContainer,
+    redisContainer,
+    redisOptions,
+    clickhouseContainer: [bootWorkerClickhouse, { scope: "worker" }],
+    resetClickhouse: [truncateClickhouseFixture, { auto: true }],
+    clickhouseClient: scopedClickhouseClient,
+  }),
+  async ({ clickhouseContainer }) => {
+    void clickhouseContainer;
+    await getWorkerPostgresContainer();
+  }
+);
 
 type ContainerWithIsolatedRedisNoClickhouseContext = {
   network: StartedNetwork;
@@ -801,14 +858,18 @@ type ContainerWithIsolatedRedisNoClickhouseContext = {
 
 // Like containerTestWithIsolatedRedis (template-clone Postgres + per-test Redis) but with no
 // ClickHouse - for suites that touch Postgres + Redis but never ClickHouse, avoiding its boot+migrate.
-export const containerTestWithIsolatedRedisNoClickhouse =
+export const containerTestWithIsolatedRedisNoClickhouse = withWarmup(
   test.extend<ContainerWithIsolatedRedisNoClickhouseContext>({
     network,
     postgresContainer: clonedPostgresContainer,
     prisma: prismaFromContainer,
     redisContainer,
     redisOptions,
-  });
+  }),
+  async () => {
+    await getWorkerPostgresContainer();
+  }
+);
 
 // For tests that exercise the Postgres -> ClickHouse logical-replication pipeline (WAL slots,
 // publications, REPLICA IDENTITY). These need a dedicated Postgres per test - the worker-scoped +
@@ -887,11 +948,16 @@ type MinioTestContext = {
   minioConfig: MinIOConnectionConfig;
 };
 
-export const minioTest = test.extend<MinioTestContext>({
-  minioContainer: [bootWorkerMinio, { scope: "worker" }],
-  resetMinio: [minioReset, { auto: true }],
-  minioConfig,
-});
+export const minioTest = withWarmup(
+  test.extend<MinioTestContext>({
+    minioContainer: [bootWorkerMinio, { scope: "worker" }],
+    resetMinio: [minioReset, { auto: true }],
+    minioConfig,
+  }),
+  async ({ minioContainer }) => {
+    void minioContainer;
+  }
+);
 
 type PostgresAndMinioTestContext = {
   postgresContainer: StartedPostgreSqlContainer;
@@ -901,10 +967,16 @@ type PostgresAndMinioTestContext = {
   minioConfig: MinIOConnectionConfig;
 };
 
-export const postgresAndMinioTest = test.extend<PostgresAndMinioTestContext>({
-  postgresContainer: clonedPostgresContainer,
-  prisma: prismaFromContainer,
-  minioContainer: [bootWorkerMinio, { scope: "worker" }],
-  resetMinio: [minioReset, { auto: true }],
-  minioConfig,
-});
+export const postgresAndMinioTest = withWarmup(
+  test.extend<PostgresAndMinioTestContext>({
+    postgresContainer: clonedPostgresContainer,
+    prisma: prismaFromContainer,
+    minioContainer: [bootWorkerMinio, { scope: "worker" }],
+    resetMinio: [minioReset, { auto: true }],
+    minioConfig,
+  }),
+  async ({ minioContainer }) => {
+    void minioContainer;
+    await getWorkerPostgresContainer();
+  }
+);

internal-packages/testcontainers/src/warmup.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, vi } from "vitest";
+import { clickhouseTest, containerTest } from "./index";
+
+vi.setConfig({ testTimeout: 10_000 });
+
+describe.skip("a skipped suite that touches the fixture first", () => {
+  containerTest("never runs", async ({ prisma }) => {
+    expect(prisma).toBeDefined();
+  });
+});
+
+describe("container fixture warmup", () => {
+  containerTest("the first test is not billed for the container boot", async ({ prisma }) => {
+    const rows = await prisma.$queryRawUnsafe<Array<{ ok: number }>>("SELECT 1 as ok");
+
+    expect(rows[0]?.ok).toBe(1);
+  });
+
+  containerTest("later tests still get a working fixture", async ({ prisma }) => {
+    const rows = await prisma.$queryRawUnsafe<Array<{ ok: number }>>("SELECT 2 as ok");
+
+    expect(rows[0]?.ok).toBe(2);
+  });
+});
+
+describe("worker-scoped fixtures are warmed too", () => {
+  clickhouseTest("clickhouse is up before the first test", async ({ clickhouseClient }) => {
+    const rs = await clickhouseClient.query({ query: "SELECT 1 AS ok", format: "JSONEachRow" });
+    const rows = await rs.json<{ ok: number }>();
+
+    expect(rows[0]?.ok).toBe(1);
+  });
+});