@owlmeans/test 0.1.18-rc.35 → 0.1.18-rc.36

package/README.md

@@ -1,14 +1,130 @@
 # @owlmeans/test
 
-Foundation helpers shared by the OwlMeans test packages and individual package test suites.
+Foundation helpers shared by the OwlMeans test packages and individual package test suites: the
+repo-root `.env` loader, environment gates that let a spec self-skip with a printed reason, and a
+JSON fixture loader. Every package's `tests/` uses it directly or through one of the harness
+packages built on it. It holds no auth mocks, no service gates and no browser driver — those are
+`@owlmeans/test-auth` (category B), `@owlmeans/test-integration` (category C) and
+`@owlmeans/test-ui` (category D). Tests run on `bun:test`; this package adds no runner. The
+package's skills are `testing-overview` (which category a package is in) and `testing-unit`.
 
-- `envHelper.loadEnv(opts?)` — locate `<monorepo-root>/.env`, parse it, merge into `process.env` (idempotent; no-op when Bun already loaded the file via `--env-file`).
-- `envHelper.requireEnv(keys)` — returns `{ ok: true }` or `{ skip: true, reason }` so callers can `test.skip(...)` when an integration variable is missing.
-- `envHelper.hasEnv(key)` — boolean shorthand for conditional service provisioning in `tests/context.ts`.
-- `makeGates(spec)` — builds a frozen record of `{ <name>: { skip, reason } }` so a per-package `tests/context.ts` exposes one source of truth and individual specs can self-skip.
-- `loadFixture<T>(relPath)` — JSON fixture loader rooted at the consuming package's `tests/fixtures/`.
+## Installation
 
-Tests must be located at `packages/<pkg>/tests/`, named `*.spec.ts`. See the `testing-overview` skill for the full strategy.
+```bash
+bun add -d @owlmeans/test@^0.1.18-rc.36
+```
+
+## Concepts
+
+- **Env file** — `<monorepo-root>/.env`, found by walking up from `process.cwd()` to a directory
+  holding `bun.lock`, or a `package.json` beside a `packages/` directory. Merged into `process.env`
+  once per process; a variable already set to a non-empty value wins. A missing file is not an error.
+- **Gate** — `EnvGate`: `{ ok: true }` when every required variable is set, otherwise
+  `{ skip: true, reason }` naming the missing ones.
+- **Gate map** — `makeGates({ name: [envKey, …] })`, a frozen record built once in a suite's
+  `tests/context.ts`; specs read it to choose `test` or `test.skip`.
+- **Fixture** — a JSON file under the consuming package's `tests/`, read relative to it.
+
+## Usage
+
+### Declare the suite's gates
+
+```typescript
+// tests/context.ts
+import { makeGates } from '@owlmeans/test'
+
+export const gates = makeGates({
+  openrouter: ['OPENROUTER_SECRET'],
+  anthropic: ['ANTHROPIC_SECRET'],
+})
+```
+
+### Self-skip a spec
+
+Bun picks `test` or `test.skip` synchronously, so decide from the gate at module scope:
+
+```typescript
+// tests/inference.spec.ts
+import { describe, expect, 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
+
+describe('llm — openrouter', () => {
+  it(`answers a prompt${isSkip(gate) ? ` (${gate.reason})` : ''}`, async () => {
+    /* exercise the real provider */
+  })
+})
+```
+
+### Read the environment directly
+
+```typescript
+import { envHelper } from '@owlmeans/test'
+
+envHelper.loadEnv()                                  // idempotent; `{ force: true }` re-reads
+envHelper.loadEnv({ file: '/path/to/other/.env' })   // a workspace shaped differently
+
+if (envHelper.hasEnv('MONGO_URL')) {
+  /* provision the optional service in tests/context.ts */
+}
+
+const gate = envHelper.requireEnv(['SMTP_HOST', 'SMTP_PORT'])
+```
+
+### Load a fixture
+
+```typescript
+import { loadFixture } from '@owlmeans/test'
+
+const profile = loadFixture<ProfileRecord>('fixtures/profile.json') // <package>/tests/fixtures/profile.json
+```
+
+## API
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `envHelper` (`createEnvHelper()`) | helper | The env loader and gates below |
+| `envHelper.loadEnv(opts?)` | member | Locate `<monorepo-root>/.env`, parse it, merge into `process.env` (idempotent; no-op for variables Bun already loaded via `--env-file`) |
+| `envHelper.hasEnv(key)` | member | `loadEnv()`, then whether the variable is set and non-empty |
+| `envHelper.requireEnv(keys)` | member | `{ ok: true }` or `{ skip: true, reason }` so callers can `test.skip(...)` when an integration variable is missing |
+| `makeGates(spec)` | function | Frozen record of `{ <name>: EnvGate }` — one source of truth in `tests/context.ts` |
+| `isSkip(gate)` | function | Type guard narrowing an `EnvGate` to `{ skip: true, reason }` |
+| `loadFixture<T>(relPath)` | function | JSON fixture loader rooted at the consuming package's `tests/` |
+
+| Type | Purpose |
+|---|---|
+| `EnvGate`, `EnvOk`, `EnvSkip` | Gate outcome union and its branches |
+| `GateSpec`, `Gates<S>` | `{ name: string[] }` input and the frozen gate map it produces |
+| `LoadEnvOptions` | `{ force?, file? }` |
+| `EnvHelper` | The helper's interface |
+
+## Test layout
+
+Tests are located at `packages/<pkg>/tests/`, named `*.spec.ts`, and run with `bun test ./tests`
+from the package root. List `"./tests/**/*"` in the package `tsconfig.json` `exclude` so `tsc -b`
+never compiles specs. One real context per package lives in `tests/context.ts`; specs import its
+helper instead of building contexts themselves.
+
+## Common pitfalls
+
+- Awaiting anything before choosing `test` / `test.skip` — the choice must be a value already in hand.
+- A missing variable must skip, never fail; do not throw from a gate.
+- `loadFixture` resolves against `process.cwd()`, which `bun test` sets to the package root; running
+  specs from another directory breaks the path.
+- A workspace without `bun.lock` and without a `packages/` directory beside its `package.json` is not
+  found by `loadEnv` — pass `file` explicitly.
+- Do not add mocks here; auth mocks belong in `@owlmeans/test-auth`, and anything else is an
+  integration test.
+
+## Related packages
+
+- [`@owlmeans/test-auth`](../test-auth) — auth/authz mocks for category-B unit tests
+- [`@owlmeans/test-integration`](../test-integration) — service gates, namespaces and cleanup for category-C tests
+- [`@owlmeans/test-ui`](../test-ui) — Playwright-driven component acceptance for category D
+- [`@owlmeans/context`](../context) — the real context a suite's `tests/context.ts` builds
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -18,7 +134,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@^0.1.18-rc.49
+npx @owlmeans/agent-skills@^0.1.18-rc.52
 ```
 
 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.35",
-  "generatedAt": "2026-10-05T21:03:06.380Z",
+  "version": "0.1.18-rc.36",
+  "generatedAt": "2026-10-08T21:27:54.292Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -31,9 +31,9 @@ New auth mocks belong in `@owlmeans/test-auth`, never in a package's own `tests/
 
 ## Package → category map
 
-All 101 packages, one category each.
+All 103 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`
+- **A** (52): `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`, `common-inquiry`, `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-inquiry`, `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** (15): `kluster`, `llm` (live inference providers), `mailer-smtp`, `mongo`, `mongo-resource`, `planning-postgres`, `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`
@@ -52,8 +52,8 @@ while one whose code issues real commands against the service is C even when it
 `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.
+`client-job`, `client-resource`, `client-route`, `client-socket`, `web-db`, `web-gtm`, `web-inquiry`
+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.

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

@@ -6,7 +6,7 @@ description: Category-A unit tests for OwlMeans Common packages — no mocks, re
 
 # Unit Tests — Category A (no mocks)
 
-**Install:** `"@owlmeans/test": "^0.1.18-rc.35"` in `devDependencies`
+**Install:** `"@owlmeans/test": "^0.1.18-rc.36"` 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`, …).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/test",
-  "version": "0.1.18-rc.35",
+  "version": "0.1.18-rc.36",
   "license": "MIT",
   "type": "module",
   "scripts": {