@owlmeans/test-integration 0.1.15 → 0.1.16-rc.0

package/agent-meta/instructions/testing-integration.instructions.md

@@ -6,12 +6,17 @@ applyTo: "**/*.test.ts, **/*.spec.ts, **/*.ts"
 # Category C — Integration Tests (env-gated)
 
 - Tests in `<your-package>/tests/*.spec.ts`. Use `bun:test`.
-- No mocks. Connect to real MongoDB / Redis / S3 / Kubernetes via the env values supplied by `<root>/.env`.
-- Open the gate at the top of `tests/context.ts` via `mongoGate()` / `redisGate()` / `s3Gate()` / `kubeGate()`. If `gate.skip`, do **not** register that service in the test context, and have specs self-skip with `gate.reason`.
-- Always `randomNamespace(prefix)` databases / key prefixes / S3 prefixes for parallel safety.
-- Always `registerCleanup(fn)` for resources you provision; call `runCleanups()` in `afterAll`.
+- No mocks. Connect to real PostgreSQL / MongoDB / Redis / S3 / Kubernetes via the env values supplied by `<root>/.env`.
+- Open the gate at the top of `tests/context.ts` via `postgresGate()` / `mongoGate()` / `redisGate()` / `s3Gate()` / `kubeGate()`. If `gate.skip`, do **not** register that service in the test context, and have specs self-skip with `gate.reason`.
+- **Never print a credential.** Pipe it straight into the env var the gate reads.
+- Unit specs (schema compilation, identifiers, error translation) go in the `*-resource` package; specs that build a real `ServerContext` go in the db package that depends on it — the reverse is a devDependency cycle.
+- **One namespace per spec file.** Export a `makeSuite(label)` from `tests/context.ts` that owns a `randomNamespace(`${prefix}_${label}`)` schema/database and its own `teardown()`, called from that file's `afterAll`. The process-global `registerCleanup`/`runCleanups()` queue is only safe in a package with a single spec file: Bun runs every spec file of a package in one process, so the first `afterAll` would drop the namespaces of the files still to come.
+- Capture connections in a `finally`, so a spec asserting a *failed* boot does not leak the pool it opened. Close them *after* the namespace drop.
+- Capability probes go at module scope as a top-level `await` — Bun decides `test` vs `test.skip` synchronously — and default to "not capable" on any error.
+- Never reset module-scope declarations (migration registries, table declarations) inside a shared `boot()` helper; a spec that wants a clean slate calls `resetDeclarations(alias)` itself. Keep migration bodies at module scope so their checksums are stable.
+- `expect(fn).not.toThrow()` treats a **returned** `Error` as thrown — assert the returned value instead.
 - `<root>/.env.example` is the authoritative documentation of every variable. Add a new key there with a comment when you introduce a new gate.
-- Per-package `package.json` script: `"test": "bun test ./tests"`. Long round-trips: bump timeout in a per-package `bunfig.toml`.
+- Per-package `package.json` script: `"test": "bun test ./tests"`; add `"./tests/**/*"` to `tsconfig.json` `exclude` and `@owlmeans/test-integration` + `@types/bun` to devDependencies. Long round-trips: bump timeout in a per-package `bunfig.toml`.
 - Cover `.claude/skills/<pkg>/SKILL.md` and `README.md` cases first.
 - Max 3-4 tests per method/function.
 

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "package": "@owlmeans/test-integration",
-  "version": "0.1.15",
-  "generatedAt": "2026-08-07T17:06:32.900Z",
+  "version": "0.1.16-rc.0",
+  "generatedAt": "2026-08-11T14:02:34.978Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/testing-integration/SKILL.md

@@ -1,74 +1,156 @@
 ---
 name: testing-integration
-description: Category-C integration tests for OwlMeans Common packages that talk to external services (MongoDB, Redis, S3, Kubernetes). Env-gated, no mocks, conditional context provisioning. Auto-invoked when writing tests in mongo*, redis*, kluster, storage*, image-resource, server-api, server-app, queue.
+description: Category-C integration tests for OwlMeans Common packages that talk to external services (PostgreSQL, MongoDB, Redis, S3, Kubernetes). Env-gated, no mocks, per-suite namespaces, conditional context provisioning. Auto-invoked when writing tests in postgres*, mongo*, redis*, kluster, storage*, image-resource, server-api, server-app, queue.
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
 # Integration Tests — Category C
 
-Category C applies to packages that integrate with external services: `mongo`, `mongo-resource`, `redis`, `redis-resource`, `kluster`, `storage-common`, `storage-resource`, `image-resource`, `server-api`, `server-app`, `queue`, `llm` (live inference providers). These tests **never** mock the external service. They run only when the corresponding env vars are set, and they self-skip cleanly when those variables are missing.
+Category C applies to packages that integrate with external services: `postgres`,
+`postgres-resource`, `mongo`, `mongo-resource`, `redis`, `redis-resource`, `kluster`,
+`storage-common`, `storage-resource`, `image-resource`, `server-api`, `server-app`, `queue`,
+`llm` (live inference providers). These tests **never** mock the external service. They run
+only when the corresponding env vars are set, and they self-skip cleanly when those variables
+are missing.
 
 ## Helpers from `@owlmeans/test-integration`
 
 | Helper | Purpose |
 |---|---|
-| `mongoGate()`, `redisGate()`, `s3Gate()`, `kubeGate()` | Read env, return `{ skip, reason?, env }`. |
-| `randomNamespace(prefix, len?)` | DB / key / object-prefix namespacing for parallel-safe runs. |
-| `registerCleanup(fn)` + `runCleanups()` | LIFO cleanup queue for `afterAll`. |
+| `postgresGate()`, `mongoGate()`, `redisGate()`, `s3Gate()`, `kubeGate()` | Read env, return `{ skip, reason?, env }`. |
+| `randomNamespace(prefix, len?)` | Schema / DB / key / object-prefix namespacing for parallel-safe runs. |
+| `registerCleanup(fn)` + `runCleanups()` | Process-global LIFO queue. **Single-spec-file packages only** — see below. |
 
-The driver libraries (`mongodb`, `ioredis`, `@aws-sdk/client-s3`, `@kubernetes/client-node`) stay where they already live — in the consuming integration packages — and are imported directly in those packages' `tests/`.
+The driver libraries (`pg`, `mongodb`, `ioredis`, `@aws-sdk/client-s3`,
+`@kubernetes/client-node`) stay where they already live — in the consuming integration
+packages — and are imported directly in those packages' `tests/`.
 
 ## Env contract
 
-`/.env.example` documents every required variable, grouped by service, with comments. The single `.env` at the monorepo root supplies real values for local runs. CI sets them via secrets. **Empty value = skip** — never a failure.
+`/.env.example` documents every required variable, grouped by service, with comments. The
+single `.env` at the monorepo root supplies real values for local runs. CI sets them via
+secrets. **Empty value = skip** — never a failure.
 
 When a required variable is empty:
 1. The corresponding gate reports `skip: true`.
 2. The per-package `tests/context.ts` does **not** register the dependent service in the real context.
 3. Specs that touch that service self-skip with the reason printed.
 
-## `tests/context.ts` pattern
+**Never print a credential.** Pipe it straight from its source into the env var the gate
+reads — the value must never reach a log, a report, or a committed file:
+
+```bash
+POSTGRES_URL="$(<build it from the secret file, without echoing>)" bun test ./tests
+```
+
+## Where the specs live
+
+A resource package (`*-resource`) owns the `Resource<T>` contract; the db package
+(`@owlmeans/postgres`, `@owlmeans/mongo`) implements the service that backs it and therefore
+**depends on** the resource package.
+
+- **Unit specs** — schema compilation, identifier derivation, placeholder resolution, error
+  translation — live in the **resource** package. No gate, no service.
+- **Integration specs** that build a real `ServerContext` live in the **db** package. Putting
+  them in the resource package would need a devDependency on its own dependent, which is a
+  cycle and risks breaking `publish.ts`'s topological batching.
+
+## Per-suite namespaces, not the global cleanup queue
+
+Bun runs **every spec file of a package in one process** with one shared module registry. A
+process-global `registerCleanup`/`runCleanups()` therefore misfires: the first file to reach
+`afterAll` drops the namespaces of the files still to come. Use `registerCleanup` only in a
+package with a single spec file.
+
+Give each spec file its own namespace and its own teardown instead:
 
 ```ts
-import { mongoGate, randomNamespace, registerCleanup } from '@owlmeans/test-integration'
-
-let cached: { gate: ReturnType<typeof mongoGate>, dbName: string } | null = null
-
-export const getTestEnv = () => {
-  if (cached != null) return cached
-  const gate = mongoGate()
-  const dbName = randomNamespace(process.env.MONGO_TEST_DB_PREFIX ?? 'omt')
-  cached = { gate, dbName }
-  if (!gate.skip) {
-    registerCleanup(async () => {
-      const { MongoClient } = await import('mongodb')
-      const client = new MongoClient(gate.env.MONGO_URL!)
-      try { await client.connect(); await client.db(dbName).dropDatabase() }
-      finally { await client.close() }
-    })
+// tests/context.ts
+export const gate: IntegrationGate<PostgresEnv> = postgresGate()
+
+export const makeSuite = (label: string): PgSuite => {
+  const prefix = process.env.POSTGRES_TEST_DB_PREFIX ?? 'omt'
+  const schema = randomNamespace(`${prefix}_${label}`)
+  const pools: Pool[] = []
+
+  const boot = async (opts: BootOptions = {}): Promise<Booted> => {
+    const cfg: ServerConfig = config('pg-test', { dbs: [{ service: 'postgres', schema, /* … */ }] })
+    const context = makeServerContext(cfg) as ServerContext<ServerConfig>
+    appendPostgres(context)
+    for (const resource of opts.resources ?? []) context.registerResource(resource as never)
+    context.configure()
+    const pg = context.service<PostgresService>('postgres')
+    try {
+      await context.init()
+    } finally {
+      collect(pg)   // in `finally`: a spec asserting a *failed* boot still opened a pool
+    }
+
+    return { context, pg }
   }
-  return cached
+
+  const teardown = async (): Promise<void> => {
+    if (gate.skip) return
+    await raw(async pool => { await pool.query(`DROP SCHEMA IF EXISTS "${schema}" CASCADE`) })
+      .catch(error => console.error(`postgres test teardown (${schema}):`, error))
+    /** After the drop — a pool still holding the schema open makes CASCADE wait. */
+    while (pools.length > 0) await pools.pop()?.end().catch(() => undefined)
+  }
+
+  return { schema, boot, collect, teardown }
 }
 ```
 
+`makeSuite('sync')`, `makeSuite('migration')` … one call per spec file, each with
+`afterAll(async () => { await suite.teardown() })`.
+
+## Capability probes must be top-level `await`
+
+Bun decides `test` vs `test.skip` **synchronously**, so a suite cannot await its own probe. A
+probe that needs a round trip goes at module scope in `tests/context.ts`, guarded by the gate
+and defaulting to "not capable" on any error:
+
+```ts
+export const capabilities: PgCapabilities = gate.skip
+  ? { bootstrap: false }
+  : await raw(async pool => { /* SELECT rolsuper, rolcreaterole, rolcreatedb … */ })
+      .catch(() => ({ bootstrap: false }))
+```
+
+Specs then branch on it once, at the top: `const it = gate.skip || !capabilities.bootstrap ? test.skip : test`.
+
+## Module-scope declarations survive a context switch
+
+Migration registries and table declarations are keyed by resource **alias** at module scope so
+they outlive `reinitializeContext`. That means they also outlive a `boot()` — deliberately.
+Never reset them inside a shared `boot()` helper: a `.migration()` registered before the boot
+would be silently dropped. A spec that wants a clean slate calls `resetDeclarations(alias)`
+itself, which is what a spec simulating a restarted process should have to say out loud.
+
+Migration bodies belong at **module scope**, not inside the spec callback: the checksum
+fingerprints the function's source text, and a body closed over a loop variable fingerprints
+the wrapper instead.
+
 ## Spec shape
 
 ```ts
 import { afterAll, describe, expect, test } from 'bun:test'
-import { runCleanups } from '@owlmeans/test-integration'
-import { getTestEnv } from './context.js'
-
-const env = getTestEnv()
+import { gate, makeSuite } from './context.js'
 
-afterAll(async () => { await runCleanups() })
+const suite = makeSuite('crud')
+const it = gate.skip ? test.skip : test
 
 describe('@owlmeans/<pkg> — <feature>', () => {
-  if (env.gate.skip) {
-    test.skip(env.gate.reason ?? '<svc> gate closed', () => {})
+  if (gate.skip) {
+    test.skip(gate.reason ?? '<svc> gate closed', () => {})
+
     return
   }
-  test('round-trips a record via the real <svc>', async () => {
-    /* connect, exercise, assert */
+
+  afterAll(async () => { await suite.teardown() })
+
+  it('round-trips a record through a real context', async () => {
+    /* boot, exercise, assert */
   })
 })
 ```
@@ -83,22 +165,43 @@ Per-package `package.json`:
 }
 ```
 
-The Bun runtime auto-loads `<root>/.env` when the test command runs from a workspace package. If you need to override, `bun test --env-file=../../.env` works. Long-running specs may need a higher timeout — set it locally in a per-package `bunfig.toml`:
+Add `"./tests/**/*"` to the package's `tsconfig.json` `exclude` so `tsc -b` never compiles
+specs into `build/`, and declare `@owlmeans/test-integration` plus `@types/bun` as
+devDependencies.
+
+The Bun runtime auto-loads `<root>/.env` when the test command runs from a workspace package.
+If you need to override, `bun test --env-file=../../.env` works. Long-running specs may need a
+higher timeout — set it locally in a per-package `bunfig.toml`:
 
 ```toml
 [test]
 timeout = 60000
 ```
 
+## Bun assertion gotcha
+
+`expect(fn).not.toThrow()` reports a **returned** `Error` as a thrown one. Every error
+*translator* returns an `Error`, so this is the wrong assertion for them — assert the returned
+value instead, which also proves the call returned:
+
+```ts
+expect(pgErrorToResourceError(circular)).toBe(circular)   // not: expect(() => …).not.toThrow()
+```
+
 ## Rules
 
 - **No mocks.** The whole point of category C is to exercise the real driver against a real service.
-- **Always namespace.** Use `randomNamespace(prefix)` for DBs, key prefixes, and S3 object prefixes so parallel runs don't collide.
-- **Always clean up.** `registerCleanup(fn)` + `runCleanups()` in `afterAll`. A failing cleanup is logged, not raised — failure must show up in the test, not the teardown.
+- **Always namespace, per suite.** `randomNamespace(`${prefix}_${label}`)` for schemas, DBs, key
+  prefixes, and S3 object prefixes, so neither parallel runs nor sibling spec files collide.
+- **Always clean up, in the suite that provisioned it.** A failing cleanup is logged, not
+  raised — failure must show up in the test, not the teardown. Verify afterwards that the
+  service holds no leftovers matching the prefix.
 - **Cover SKILL.md cases first.**
 - **Max 3-4 tests per method/function.**
 - **CI runs C only when secrets are set.** Locally, an empty `.env` produces a clean skip.
 
 ## When the env is partially populated
 
-Each gate fails closed. A test that needs both `S3_KEY` and `S3_SECRET` does not run if only one is set — `s3Gate()` reports `skip: true`. This is intentional: a half-configured environment must not produce false positives or partial coverage.
+Each gate fails closed. A test that needs both `S3_KEY` and `S3_SECRET` does not run if only
+one is set — `s3Gate()` reports `skip: true`. This is intentional: a half-configured
+environment must not produce false positives or partial coverage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/test-integration",
-  "version": "0.1.15",
+  "version": "0.1.16-rc.0",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,10 +21,10 @@
     }
   },
   "dependencies": {
-    "@owlmeans/test": "^0.1.15"
+    "@owlmeans/test": "^0.1.16-rc.0"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "^0.1.15",
+    "@owlmeans/dep-config": "^0.1.16-rc.0",
     "@types/bun": "^1.3.14",
     "nodemon": "^3.1.14",
     "typescript": "^6.0.3"