wehub-resource-sync
79 lines
4.1 KiB
Markdown
79 lines
4.1 KiB
Markdown
# Test containers
|
|
|
|
Vitest utilities for writing tests against real Postgres, Prisma, Redis and ClickHouse - we don't mock
|
|
(see the root `CLAUDE.md`), we boot containers. Also exposes a duration-weighted shard sequencer for
|
|
splitting slow suites across CI shards.
|
|
|
|
## Choosing a fixture
|
|
|
|
Most tests share one set of containers per vitest worker (booted once, reset between tests) - this is
|
|
much faster than a container per test. Reach for an isolated variant only when a test needs it.
|
|
|
|
| Fixture | Postgres | Redis | ClickHouse | Use for |
|
|
| -------------------------------- | -------------- | -------- | ---------- | --------------------------------------- |
|
|
| `redisTest` | - | shared | - | redis-only tests |
|
|
| `postgresTest` | shared (clone) | - | - | db-only tests |
|
|
| `containerTest` | shared (clone) | shared | shared | the default - needs all three |
|
|
| `isolatedRedisTest` | - | per-test | - | background redis work (see below) |
|
|
| `containerTestWithIsolatedRedis` | shared (clone) | per-test | shared | background redis work + db/clickhouse |
|
|
| `replicationContainerTest` | per-test | per-test | shared | Postgres→ClickHouse logical replication |
|
|
|
|
"shared (clone)" = one Postgres per worker with a template database; each test gets a fast `CREATE
|
|
DATABASE ... TEMPLATE` clone, so schema isn't re-pushed per test.
|
|
|
|
### The background-work gotcha
|
|
|
|
If a test spawns work that **outlives the test body** - a `RunEngine`, a `redis-worker` Worker, a
|
|
`BatchQueue` - and that work isn't fully drained before the test ends, you **must** use an isolated
|
|
redis fixture (`isolatedRedisTest` / `containerTestWithIsolatedRedis`).
|
|
|
|
On the shared fixture, the leaked background loop keeps polling the one worker-scoped redis after the
|
|
test's clients close, bleeding into the next test. The symptom is an intermittent `"Connection is
|
|
closed"` error or a test that hangs until its timeout. `FLUSHALL` between tests does **not** fix this -
|
|
it clears data, not live connections/loops, so per-test key prefixes won't help either. A plain
|
|
db/redis test with no lingering background work is fine on the shared fixtures.
|
|
|
|
## Sharding (`./sequencer`)
|
|
|
|
CI splits the slow suites with `vitest --shard=i/N`. `DurationShardingSequencer` replaces vitest's
|
|
default file-count split with a duration-weighted one: it reads `test-timings.json` at the repo root
|
|
(`{ "<repo-relative path>": <ms> }`) and greedily bin-packs files so each shard does roughly equal
|
|
_work_, not an equal _number of files_. The packing is deterministic, so every shard computes the same
|
|
bins and runs each file exactly once.
|
|
|
|
Configs opt in via:
|
|
|
|
```ts
|
|
import { DurationShardingSequencer } from "@internal/testcontainers/sequencer";
|
|
// in defineConfig:
|
|
test: {
|
|
sequence: {
|
|
sequencer: DurationShardingSequencer,
|
|
},
|
|
}
|
|
```
|
|
|
|
### Adding tests - nothing to do
|
|
|
|
New test files are discovered by vitest's glob and sharded automatically. A file with no entry in
|
|
`test-timings.json` is given the **median** duration as a fallback, so it's still placed on exactly one
|
|
shard - correctness never depends on the timings being present or current.
|
|
|
|
What the timings affect is **balance**. A new heavy test estimated at the median can be under-weighted
|
|
and land on an already-full shard, making that shard slower. There's headroom between the current
|
|
makespan and the CI budget to absorb this, so it tolerates drift - but if a shard creeps toward the
|
|
budget, refresh the timings.
|
|
|
|
### Refreshing `test-timings.json`
|
|
|
|
Measure each shard with the JSON reporter and write per-file `endTime - startTime` (ms), keyed by
|
|
repo-relative path, back into `test-timings.json`. Set `GITHUB_ACTIONS=true` so suites that
|
|
`skipIf(CI)` are excluded, matching what actually runs on CI:
|
|
|
|
```bash
|
|
GITHUB_ACTIONS=true pnpm exec vitest run --reporter=json --outputFile=/tmp/run.json
|
|
```
|
|
|
|
Stale entries for deleted/renamed files are harmless (they're simply ignored). This is a periodic
|
|
chore, not a per-PR one.
|