chore: import upstream snapshot with attribution

2026-07-13 13:32:57 +08:00
commit cd420f9332
4811 changed files with 884702 additions and 0 deletions
@@ -0,0 +1,60 @@
+# Fast local testing loop
+
+These tests use real Docker containers (Postgres, ClickHouse, Redis, Electric, MinIO) via testcontainers - never mocks. This guide is the fast inner loop for working on them.
+
+## Prerequisites
+
+- **Docker daemon running.** That's it - testcontainers boots its own containers. You do **not** need `pnpm run docker` (that compose stack is for running the app, and is separate).
+
+## The loop
+
+```bash
+# 1. Build upstream deps once (turbo-caches them; only re-runs when a dep changes)
+pnpm run build --filter @internal/run-engine
+
+# 2. Iterate by running vitest DIRECTLY in the package - not via `turbo run test`
+cd internal-packages/run-engine
+pnpm exec vitest run src/engine/tests/ttl.test.ts        # one file
+pnpm exec vitest src/engine/tests/ttl.test.ts            # watch mode, tightest loop
+pnpm exec vitest run src/engine/tests/ --reporter=verbose # per-test timings
+```
+
+> **Why run vitest directly, not `turbo run test`?** The `test` turbo task is cacheable
+> (`outputs: []`). A second `turbo run test` with no input change replays the cached
+> result in ~0ms instead of executing - useless when you're measuring timing. Run vitest
+> directly (or `turbo run test --force`) so tests actually run.
+
+## Measuring container boot/teardown vs test time
+
+Container lifecycle (boot + migrate + teardown) dominates these suites. To see the split:
+
+```bash
+# JSON timing lines are gated on TESTCONTAINERS_TIMING locally (always on in CI),
+# and need --disableConsoleIntercept so vitest doesn't swallow them.
+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
+node internal-packages/testcontainers/scripts/measure-test-timing.mjs \
+  src/client/client.test.ts --cwd internal-packages/clickhouse --runs 3
+# -> run 1/3  passed=true  wall=10.58s  teardown=0.67s ...
+```