@owlmeans/test-integration 0.1.7 → 0.1.8

package/README.md

@@ -9,3 +9,20 @@ Helpers exported here:
 - `registerCleanup(fn)` + `runCleanups()` — opt-in `afterAll` cleanup queue.
 
 Specs do not call services through these helpers — they consume the per-package real test context built in `tests/context.ts` and only check `gates.<svc>.skip` to self-skip when the dependency is missing. See `testing-integration` skill for the full pattern.
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded Claude Code skills and GitHub Copilot instructions under
+`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
+agent-skills installer to place them into your project's native locations
+(`.claude/skills/` and `.github/instructions/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

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

@@ -0,0 +1,18 @@
+---
+applyTo: "**/*.test.ts, **/*.spec.ts, **/*.ts"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# 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`.
+- `<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`.
+- Cover `.claude/skills/<pkg>/SKILL.md` and `README.md` cases first.
+- Max 3-4 tests per method/function.
+
+See `.claude/skills/testing-integration/SKILL.md` for the full pattern.

package/agent-meta/manifest.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "package": "@owlmeans/test-integration",
+  "version": "0.1.8",
+  "generatedAt": "2026-06-11T16:30:27.166Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "testing-integration",
+      "category": "package-specific",
+      "file": "skills/testing-integration/SKILL.md",
+      "canonicalPath": ".claude/skills/testing-integration/SKILL.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "testing-integration",
+      "category": "package-specific",
+      "file": "instructions/testing-integration.instructions.md",
+      "canonicalPath": ".github/instructions/testing-integration.instructions.md"
+    }
+  ]
+}

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

@@ -0,0 +1,104 @@
+---
+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.
+---
+<!-- 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`. 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`. |
+
+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/`.
+
+## 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.
+
+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
+
+```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() }
+    })
+  }
+  return cached
+}
+```
+
+## 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()
+
+afterAll(async () => { await runCleanups() })
+
+describe('@owlmeans/<pkg> — <feature>', () => {
+  if (env.gate.skip) {
+    test.skip(env.gate.reason ?? '<svc> gate closed', () => {})
+    return
+  }
+  test('round-trips a record via the real <svc>', async () => {
+    /* connect, exercise, assert */
+  })
+})
+```
+
+## Wiring `bun test`
+
+Per-package `package.json`:
+
+```json
+"scripts": {
+  "test": "bun test ./tests"
+}
+```
+
+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
+```
+
+## 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.
+- **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/test-integration",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,10 +21,10 @@
     }
   },
   "dependencies": {
-    "@owlmeans/test": "^0.1.7"
+    "@owlmeans/test": "^0.1.8"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "^0.1.7",
+    "@owlmeans/dep-config": "^0.1.8",
     "@types/bun": "^1.3.0",
     "nodemon": "^3.1.11",
     "typescript": "^6.0.2"