test(testcontainers): add opt-in CI-resource-limit mode for local flake repro

Author: nicktrn

internal-packages/testcontainers/TESTING.md

@@ -34,6 +34,23 @@ Container lifecycle (boot + migrate + teardown) dominates these suites. To see t
 TESTCONTAINERS_TIMING=1 pnpm exec vitest run <file> --disableConsoleIntercept
 ```
 
+## Approximating the 2-core CI runner locally (flake repro)
+
+To reproduce CI-like CPU pressure on a beefy local machine - useful when a test only flakes under
+the 2-core CI runner:
+
+```bash
+# cap each testcontainer's CPU/mem (TESTCONTAINERS_CPU = cores, TESTCONTAINERS_MEMORY_GB = GB),
+# and pin the test runner to 2 cores. Off unless the env vars are set.
+TESTCONTAINERS_CPU=2 TESTCONTAINERS_MEMORY_GB=2 taskset -c 0,1 pnpm exec vitest run <file>
+```
+
+Note: in practice the scoped tests here are latency/IO/sleep-bound, not CPU-bound, so this changes
+timings little - the original CI slowness was per-test container *boots*, which worker-scoping removed.
+Keep it for the cases that genuinely starve on CPU (e.g. timing races against a worker poll).
+
+## Timing harness
+
 Or use the harness, which aggregates the split for you:
 
 ```bash

internal-packages/testcontainers/src/index.ts

@@ -12,6 +12,7 @@ import {
   postgresUriWithDatabase,
   pushDatabaseSchema,
   useContainer,
+  withCiResourceLimits,
   withContainerSetup,
 } from "./utils";
 import { getTaskMetadata, logCleanup, logSetup } from "./logs";
@@ -147,7 +148,9 @@ let workerPostgresContainer: Promise<StartedPostgreSqlContainer> | undefined;
 const getWorkerPostgresContainer = () => {
   if (!workerPostgresContainer) {
     workerPostgresContainer = (async () => {
-      const container = await new PostgreSqlContainer("docker.io/postgres:14")
+      const container = await withCiResourceLimits(
+        new PostgreSqlContainer("docker.io/postgres:14")
+      )
         .withCommand(["-c", "listen_addresses=*", "-c", "wal_level=logical"])
         .start();
       await pushDatabaseSchema(
@@ -358,7 +361,7 @@ type ClickhouseTestContext = {
 
 // Boot + migrate clickhouse once per worker.
 const bootWorkerClickhouse = async ({}, use: Use<StartedClickHouseContainer>) => {
-  const container = await new ClickHouseContainer().start();
+  const container = await withCiResourceLimits(new ClickHouseContainer()).start();
   const client = createClient({ url: container.getConnectionUrl() });
   await client.ping();
   await runClickhouseMigrations(client, clickhouseMigrationsPath);
@@ -469,7 +472,7 @@ export const containerWithElectricAndRedisTest = test.extend<ContainerWithElectr
 
 // Boot minio once per worker; reset the bucket per test (auto fixture).
 const bootWorkerMinio = async ({}, use: Use<StartedMinIOContainer>) => {
-  const container = await new MinIOContainer().start();
+  const container = await withCiResourceLimits(new MinIOContainer()).start();
   try {
     await use(container);
   } finally {

internal-packages/testcontainers/src/utils.ts

@@ -46,8 +46,26 @@ export async function pushDatabaseSchema(databaseUrl: string) {
   );
 }
 
+/**
+ * Caps each container's CPU/memory to approximate the 2-core CI runner locally (for timing + flake
+ * reproduction). Set TESTCONTAINERS_CPU (cores per container, e.g. "2") and/or
+ * TESTCONTAINERS_MEMORY_GB (GB per container). Pair with running the runner under `taskset -c 0,1`.
+ * No-op when neither is set. (testcontainers v11 has no cpuset pinning, only this quota cap.)
+ */
+export function withCiResourceLimits<T extends GenericContainer>(container: T): T {
+  const cpu = process.env.TESTCONTAINERS_CPU;
+  const memory = process.env.TESTCONTAINERS_MEMORY_GB;
+  if (!cpu && !memory) {
+    return container;
+  }
+  return container.withResourcesQuota({
+    ...(cpu ? { cpu: Number(cpu) } : {}),
+    ...(memory ? { memory: Number(memory) } : {}),
+  });
+}
+
 export async function createPostgresContainer(network: StartedNetwork) {
-  const container = await new PostgreSqlContainer("docker.io/postgres:14")
+  const container = await withCiResourceLimits(new PostgreSqlContainer("docker.io/postgres:14"))
     .withNetwork(network)
     .withNetworkAliases("database")
     .withCommand(["-c", "listen_addresses=*", "-c", "wal_level=logical"])
@@ -59,7 +77,9 @@ export async function createPostgresContainer(network: StartedNetwork) {
 }
 
 export async function createClickHouseContainer(network: StartedNetwork) {
-  const container = await new ClickHouseContainer().withNetwork(network).start();
+  const container = await withCiResourceLimits(new ClickHouseContainer())
+    .withNetwork(network)
+    .start();
 
   const client = createClient({
     url: container.getConnectionUrl(),
@@ -86,7 +106,7 @@ export async function createRedisContainer({
   port?: number;
   network?: StartedNetwork;
 }) {
-  let container = new RedisContainer("redis:7.2")
+  let container = withCiResourceLimits(new RedisContainer("redis:7.2"))
     .withExposedPorts(port ?? 6379)
     .withStartupTimeout(120_000); // 2 minutes
 
@@ -167,8 +187,10 @@ export async function createElectricContainer(
     network.getName()
   )}:5432/${postgresContainer.getDatabase()}?sslmode=disable`;
 
-  const container = await new GenericContainer(
-    "electricsql/electric:1.2.4@sha256:20da3d0b0e74926c5623392db67fd56698b9e374c4aeb6cb5cadeb8fea171c36"
+  const container = await withCiResourceLimits(
+    new GenericContainer(
+      "electricsql/electric:1.2.4@sha256:20da3d0b0e74926c5623392db67fd56698b9e374c4aeb6cb5cadeb8fea171c36"
+    )
   )
     .withExposedPorts(3000)
     .withNetwork(network)
@@ -185,7 +207,7 @@ export async function createElectricContainer(
 }
 
 export async function createMinIOContainer(network: StartedNetwork) {
-  const container = await new MinIOContainer()
+  const container = await withCiResourceLimits(new MinIOContainer())
     .withNetwork(network)
     .withNetworkAliases("minio")
     .start();