@owlmeans/test 0.1.18-rc.7 → 0.1.18-rc.8

package/README.md

@@ -18,7 +18,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.12
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/test",
-  "version": "0.1.18-rc.7",
-  "generatedAt": "2026-09-01T16:28:56.985Z",
+  "version": "0.1.18-rc.8",
+  "generatedAt": "2026-09-04T22:43:25.438Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,6 +8,10 @@ description: Decision matrix for which testing strategy to use per package in th
 
 Every package falls into exactly one of four testing categories. The category drives which `@owlmeans/test*` package(s) the tests depend on, where tests live, and what mocking is allowed.
 
+`@owlmeans/test` is the base every category builds on — env loading, env gates and fixture loading
+(`testing-unit` documents its exports). `@owlmeans/test-auth`, `@owlmeans/test-integration` and
+`@owlmeans/test-ui` each add one category's helpers on top of it.
+
 ## Categories
 
 | Cat | Strategy | Tests location | Runtime | Mocks? | Skill |
@@ -19,28 +23,50 @@ Every package falls into exactly one of four testing categories. The category dr
 
 ## Package → category map
 
-- **A** (~31): `basic-ids`, `context`, `config`, `error`, `flow`, `i18n`, `module`, `route`, `router`, `resource`, `socket`, `state`, `static-resource`, `client-route`, `client-config`, `client-context`, `client-resource`, `client-module`, `client-flow`, `client-socket`, `server-route`, `server-config`, `server-context`, `server-module`, `payment`, `api`, `api-config`, `api-config-client`, `api-config-server`, `web-router`, `web-db`
-- **B** (~13): `auth`, `auth-common`, `basic-keys`, `basic-envelope`, `did`, `client-auth`, `client-did`, `server-auth`, `oidc`, `server-oidc-rp`, `server-oidc-provider`, `web-oidc-rp`, `web-oidc-provider`, `wled`, `client-payment`
-- **C** (~11): `mongo`, `mongo-resource`, `redis`, `redis-resource`, `kluster`, `storage-common`, `storage-resource`, `image-resource`, `server-api`, `server-app`, `queue`, `llm` (live inference providers)
-- **D** (~8): `client`, `client-i18n`, `client-panel`, `client-wl`, `web-client`, `web-flow`, `web-panel`, `web-wl`
-- **None**: `dep-config`, `_tpl`
+All 101 packages, one category each.
+
+- **A** (50): `agent`, `agent-common`, `agent-skills`, `api`, `api-config`, `api-config-client`, `api-config-server`, `astro`, `basic-ids`, `client-config`, `client-context`, `client-entrypoint`, `client-flow`, `client-job`, `client-resource`, `client-route`, `client-socket`, `config`, `consent`, `context`, `create-app`, `entrypoint`, `error`, `flow`, `i18n`, `iam`, `image-resource`, `llm-common`, `mailer`, `payment`, `queue`, `resource`, `route`, `router`, `server-auth-identity`, `server-context`, `server-entrypoint`, `server-iam`, `server-job`, `server-route`, `server-config`, `server-socket`, `server-wl`, `socket`, `state`, `static-resource`, `storage-common`, `web-db`, `web-gtm`, `web-router-react-router`
+- **B** (20): `auth`, `auth-common`, `auth-otp`, `basic-envelope`, `basic-keys`, `client-auth`, `client-did`, `client-iam`, `client-payment`, `did`, `mui-oidc-rp`, `oidc`, `server-auth`, `server-auth-otp`, `server-oidc-provider`, `server-oidc-rp`, `web-auth`, `web-oidc-provider`, `web-oidc-rp`, `wled`
+- **C** (14): `kluster`, `llm` (live inference providers), `mailer-smtp`, `mongo`, `mongo-resource`, `postgres`, `postgres-resource`, `redis`, `redis-queue`, `redis-resource`, `server-api`, `server-app`, `server-mailer-mailgun`, `storage-resource`
+- **D** (11): `client`, `client-i18n`, `client-panel`, `client-wl`, `mui-panel`, `web-client`, `web-consent`, `web-flow`, `web-panel`, `web-router`, `web-wl`
+- **None** (6): `dep-config`, `_tpl`, and the four harness packages themselves — `test`, `test-auth`, `test-integration`, `test-ui`
+
+A **contract** package and its **backend** split across categories. `queue`, `resource`,
+`storage-common` and `image-resource` are A — types, AJV schemas, error classes and declarations,
+with nothing to connect to — while `redis-queue`, `mongo`, `postgres` and `storage-resource` (which
+carries the S3 client) are C. Same for mail: `mailer` is A, `mailer-smtp` and
+`server-mailer-mailgun` are C. The test is what the package's own code does at runtime, not what
+its manifest lists: a package that only declares types, schemas and errors has no gate to write,
+while one whose code issues real commands against the service is C even when it names no driver.
+`redis-resource` imports `ioredis` for types alone and drives the client the db service hands it;
+`mongo-resource` carries its driver as a devDependency, for its specs only. Both are C.
+
+`web-router` is D, not A: it drives the History API, so its routing behaviour is only observable in
+a browser and its specs mount a real harness in chromium. A client-side package stays in A when it
+ships no component at all — `client-config`, `client-context`, `client-entrypoint`, `client-flow`,
+`client-job`, `client-resource`, `client-route`, `client-socket`, `web-db`, `web-gtm` and
+`web-router-react-router` are services, models and adapters, so `bun test` alone covers them.
+
+A new package takes the category its own behaviour implies: an external service it cannot fake ⇒ C,
+a rendered React surface ⇒ D, an authenticated identity it must stand in for ⇒ B, otherwise A.
 
 ## Eight invariants (apply everywhere)
 
-1. **Tests live next to `src/` in `<your-package>/tests/`**, named `*.spec.ts`. They are outside `rootDir: ./src/` so `tsc -b` already excludes them.
+1. **Tests live next to `src/` in `<your-package>/tests/`**, named `*.spec.ts`. They sit outside `rootDir: ./src/`, so the package `tsconfig.json` must list `"./tests/**/*"` in `exclude` — otherwise `tsc -b` tries to compile them and fails on the rootDir boundary.
 2. **One real context per package**, set up in `tests/context.ts`. It builds a real `BasicContext` / server / client context (whatever the package documents in its `SKILL.md`), provisions real sibling-package services and resources, and exports a single helper specs import.
 3. **Cross-package imports are real.** No mocks for sibling packages. Auth/authz is the only mockable boundary, only in category B, only via `@owlmeans/test-auth`.
 4. **Don't test context wiring** in every package. Trust `@owlmeans/context`'s own tests.
 5. **Don't test utils. Don't test types.** Max 3-4 tests per method/function.
 6. **Cover the package's `SKILL.md` and `README.md` cases first.** Those are the documented consumption surfaces — tests validate them as executable specs before reaching for internal coverage.
-7. **Env-gated provisioning** for category C: if a required env var is empty, neither the dependent service is provisioned in the test context nor are the specs that need it executed. Specs self-skip with a printed reason — never fail.
+7. **Env-gated provisioning** whenever a spec needs something the machine may not have: if a required env var is empty, neither the dependent service is provisioned in the test context nor are the specs that need it executed. Specs self-skip with a printed reason — never fail. Gates come from one of two places: `@owlmeans/test-integration` ships a ready-made one for each service it covers (PostgreSQL, MongoDB, Redis, S3, Kubernetes, SMTP), and a package whose provider is outside that set declares its own with `makeGates` from `@owlmeans/test` — `llm` does exactly that for its inference providers, and Mailgun's HTTP API needs the same. Both produce identical skip behaviour.
 8. **No new mocks.** If a test seems to need a mock that isn't auth/authz, the test belongs in category C (and the package belongs in category C) — write an integration test, not a fake.
 
 ## Running tests
 
 - All packages from root: `bun run test`
 - One package: `cd <your-package> && bun test ./tests` — same line for every category
-- Integration tests: `MONGO_URL=... bun run test` — empty values skip cleanly
+- Gated tests: `MONGO_URL=... bun run test`, or put the values in the repo-root `.env` that
+  `loadEnv` picks up. Empty values skip cleanly; a missing `.env` is not an error
 - One-time UI setup: `bunx playwright install chromium` (downloads the browser the `playwright` library drives in category D)
 
 ## What to test (always)

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

@@ -6,7 +6,54 @@ description: Category-A unit tests for OwlMeans Common packages — no mocks, re
 
 # Unit Tests — Category A (no mocks)
 
-Apply this skill when adding tests to packages in category A (see `testing-overview`). The list includes core abstractions (`context`, `config`, `error`, `entrypoint`, `route`, `resource`, …) and platform-agnostic services (`api`, `state`, `flow`, `i18n`, `client-flow`, `client-socket`, `server-route`, `server-context`, `web-router`, `web-db`, …).
+**Install:** `"@owlmeans/test": "^0.1.18-rc.8"` in `devDependencies`
+
+Apply this skill when adding tests to packages in category A (see `testing-overview`). The list includes core abstractions (`context`, `config`, `error`, `entrypoint`, `route`, `resource`, …) and platform-agnostic services (`api`, `state`, `flow`, `i18n`, `client-flow`, `client-socket`, `client-job`, `server-route`, `server-context`, `web-db`, …).
+
+`@owlmeans/test` is also the base of the other three harness packages, so its exports below are
+available in every category.
+
+## Helpers from `@owlmeans/test`
+
+| Helper | Purpose |
+|---|---|
+| `loadEnv({ force?, file? })` | Read a `.env` into `process.env`, once per process. Never overwrites a variable already set to a non-empty value; a missing file is not an error. The root is found by walking up for a `bun.lock`, or for a `package.json` sitting beside a directory named `packages` — a workspace shaped any other way must pass `file` explicitly. |
+| `hasEnv(key)` | `loadEnv()`, then true when the variable is set and non-empty. |
+| `requireEnv(keys)` | `EnvGate` — `{ ok: true }` when every key is populated, otherwise `{ skip: true, reason }` naming the missing ones. |
+| `makeGates(spec)` | Frozen `{ name: EnvGate }` built from `{ name: [envKey, …] }`. One call in `tests/context.ts` is the whole suite's availability map. |
+| `isSkip(gate)` | Type guard narrowing an `EnvGate` to the skip branch, so `gate.reason` is readable. |
+| `loadFixture<T>(relPath)` | Parse a JSON fixture from the package's own `tests/` directory — `bun test` sets `process.cwd()` to the package root, so the path is `tests/`-relative. |
+| Types: `EnvGate`, `EnvOk`, `EnvSkip`, `GateSpec`, `Gates<S>` | The gate shapes, for typing a suite's exported map. |
+
+### Gating a spec
+
+A category-A package needs nothing external, so most specs never gate. When one does — a live
+provider, an optional local binary — declare every gate in `tests/context.ts` and let each spec
+choose its own `test` at module scope:
+
+```ts
+// tests/context.ts
+import { makeGates } from '@owlmeans/test'
+
+export const gates = makeGates({
+  openrouter: ['OPENROUTER_SECRET'],
+  anthropic: ['ANTHROPIC_SECRET'],
+})
+```
+
+```ts
+// tests/<area>.spec.ts
+import { test } from 'bun:test'
+import { isSkip } from '@owlmeans/test'
+import { gates } from './context.js'
+
+const gate = gates.openrouter
+const it = isSkip(gate) ? test.skip : test
+// `isSkip(gate) ? gate.reason : ''` names the missing variables in the skip title.
+```
+
+Bun decides `test` vs `test.skip` **synchronously**, so the decision has to be a value already in
+hand — never an `await` inside the suite. An empty variable is a printed skip, never a failure.
 
 ## Layout
 
@@ -16,7 +63,7 @@ Apply this skill when adding tests to packages in category A (see `testing-overv
 ├── tests/
 │   ├── context.ts          # one real context, shared across specs
 │   ├── <area>.spec.ts      # *.spec.ts only
-│   └── fixtures/           # JSON fixtures, optional
+│   └── fixtures/           # JSON fixtures, read with loadFixture('fixtures/<name>.json')
 ```
 
 ## `tests/context.ts` — single source of truth
@@ -79,7 +126,10 @@ Per-package `package.json`:
 }
 ```
 
-`bun:test` is built-in — no devDeps to add. The root `bun run test` script runs every package's `test` script via workspace filters.
+`bun:test` is built-in, so `@types/bun` is the only devDep a plain category-A package needs; add
+`@owlmeans/test` when a spec actually uses a helper above. Add `"./tests/**/*"` to the package's
+`tsconfig.json` `exclude` so `tsc -b` never compiles specs into `build/`. The root `bun run test`
+script runs every package's `test` script via workspace filters.
 
 ## When auth shows up
 

package/build/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,IAAI,CAAA;CACT;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,OAAO,CAAA;AAkCrC,eAAO,MAAM,OAAO,GAAI,OAAO;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,IAanE,CAAA;AAED,eAAO,MAAM,MAAM,GAAI,KAAK,MAAM,KAAG,OAIpC,CAAA;AAED,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,EAAE,KAAG,OAK3C,CAAA"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,IAAI,CAAA;CACT;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,OAAO,CAAA;AAkCrC,eAAO,MAAM,OAAO,UAAW;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,IAanE,CAAA;AAED,eAAO,MAAM,MAAM,QAAS,MAAM,KAAG,OAIpC,CAAA;AAED,eAAO,MAAM,UAAU,SAAU,MAAM,EAAE,KAAG,OAK3C,CAAA"}

package/build/fixtures.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../src/fixtures.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,GAAG,OAAO,EAAE,SAAS,MAAM,KAAG,CAI1D,CAAA"}
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../src/fixtures.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,GAAG,OAAO,WAAW,MAAM,KAAG,CAI1D,CAAA"}

package/build/gates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAEvC,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAE/C,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,QAAQ,IAAI;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO;CAAE,CAAA;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,QAAQ,EAAE,MAAM,CAAC,KAAG,KAAK,CAAC,CAAC,CAM9D,CAAA;AAED,eAAO,MAAM,MAAM,GAAI,MAAM,OAAO,KAAG,IAAI,IAAI;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAClC,CAAA"}
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAEvC,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAE/C,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,QAAQ,IAAI;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO;CAAE,CAAA;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,QAAQ,QAAQ,CAAC,KAAG,KAAK,CAAC,CAAC,CAM9D,CAAA;AAED,eAAO,MAAM,MAAM,SAAU,OAAO,KAAG,IAAI,IAAI;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAClC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/test",
-  "version": "0.1.18-rc.7",
+  "version": "0.1.18-rc.8",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,7 +21,7 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.18-rc.7"
+    "@owlmeans/context": "^0.1.18-rc.8"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "^0.1.18-rc.6",