@owlmeans/test 0.1.7 → 0.1.8

package/README.md

@@ -9,3 +9,20 @@ Foundation helpers shared by the OwlMeans test packages and individual package t
 - `loadFixture<T>(relPath)` — JSON fixture loader rooted at the consuming package's `tests/fixtures/`.
 
 Tests must be located at `packages/<pkg>/tests/`, named `*.spec.ts`. See the `testing-overview` skill for the full strategy.
+
+<!-- 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-unit.instructions.md

@@ -0,0 +1,16 @@
+---
+applyTo: "**/*.test.ts, **/*.spec.ts, **/*.ts"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Category A — Unit Tests (no mocks)
+
+- Tests in `<your-package>/tests/*.spec.ts`. Use `bun:test` (`describe`, `test`, `expect`).
+- Build a real context once in `tests/context.ts` and export a helper specs call. No mocks.
+- Sibling packages are imported normally. If you feel the urge to mock one, you're in the wrong category — move to integration instead.
+- Cover `.claude/skills/<pkg>/SKILL.md` and `README.md` cases first.
+- Max 3-4 tests per method/function.
+- Don't test utils, types, or context plumbing.
+- Per-package `package.json` script: `"test": "bun test ./tests"`.
+
+See `.claude/skills/testing-unit/SKILL.md` for the full pattern.

package/agent-meta/manifest.json

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

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

@@ -0,0 +1,55 @@
+---
+name: testing-overview
+description: Decision matrix for which testing strategy to use per package in the OwlMeans Common monorepo (unit no-mocks / unit with auth-mocks / env-gated integration / Playwright acceptance) plus the eight invariants that apply to every package. Auto-invoked when "tests" or "testing" is mentioned.
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Testing Strategy — OwlMeans Common
+
+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.
+
+## Categories
+
+| Cat | Strategy | Tests location | Runtime | Mocks? | Skill |
+|-----|----------|----------------|---------|--------|-------|
+| A | Unit, real sibling-package imports | `tests/*.spec.ts` | `bun test` | None | `testing-unit` |
+| B | Unit with auth/authz mocks | `tests/*.spec.ts` | `bun test` | Only auth/authz, only via `@owlmeans/test-auth` | `testing-auth-unit` |
+| C | Integration, env-gated | `tests/*.spec.ts` | `bun test` | None | `testing-integration` |
+| D | Component-level acceptance, real chromium | `tests/*.spec.ts` | `bun test` (drives Playwright as a library) | None | `testing-ui` |
+
+## 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** (~10): `mongo`, `mongo-resource`, `redis`, `redis-resource`, `kluster`, `storage-common`, `storage-resource`, `image-resource`, `server-api`, `server-app`, `queue`
+- **D** (~8): `client`, `client-i18n`, `client-panel`, `client-wl`, `web-client`, `web-flow`, `web-panel`, `web-wl`
+- **None**: `dep-config`, `_tpl`
+
+## 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.
+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.
+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
+- One-time UI setup: `bunx playwright install chromium` (downloads the browser the `playwright` library drives in category D)
+
+## What to test (always)
+
+Services, components, helpers, and broad domain models that aren't already exposed via a service. Cover the `SKILL.md` use cases first, then the `README.md` examples, then any non-trivial invariants documented in code comments.
+
+## What NOT to test
+
+- Utils (`src/utils/*` or `src/utils.ts`) — internal package implementation.
+- Type-only files (`src/types.ts`).
+- Context plumbing — already covered by `@owlmeans/context`.
+- Anything you'd need to mock a sibling OwlMeans package to test.

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

@@ -0,0 +1,82 @@
+---
+name: testing-unit
+description: Category-A unit tests for OwlMeans Common packages — no mocks, real sibling-package imports, services/components/helpers focus. Auto-invoked when writing tests in non-auth, non-integration, non-UI packages.
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# 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`, `module`, `route`, `resource`, …) and platform-agnostic services (`api`, `state`, `flow`, `i18n`, `client-flow`, `client-socket`, `server-route`, `server-context`, `web-router`, `web-db`, …).
+
+## Layout
+
+```
+<your-package>/
+├── src/...
+├── tests/
+│   ├── context.ts          # one real context, shared across specs
+│   ├── <area>.spec.ts      # *.spec.ts only
+│   └── fixtures/           # JSON fixtures, optional
+```
+
+## `tests/context.ts` — single source of truth
+
+Build a real context exactly the way the package's `SKILL.md` documents downstream apps building it. No mocks. Sibling packages are imported normally.
+
+```ts
+import { AppType, Layer, makeBasicContext } from '@owlmeans/context'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+
+export const makeTestCtx = (overrides: Partial<BasicConfig> = {}): BasicContext<BasicConfig> =>
+  makeBasicContext({
+    ready: false,
+    service: '<pkg>-tests',
+    layer: Layer.Service,
+    type: AppType.Backend,
+    ...overrides,
+  })
+```
+
+Specs import `makeTestCtx()` (or whatever helper fits) and never call `makeBasicContext` directly. This keeps the wiring centralised so a context-shape change only touches one file per package.
+
+## Spec shape
+
+```ts
+import { describe, expect, test } from 'bun:test'
+import { makeTestCtx } from './context.js'
+
+describe('<package> — <area>', () => {
+  test('does the thing the SKILL.md documents', () => {
+    const ctx = makeTestCtx()
+    /* exercise the real public API */
+  })
+})
+```
+
+Use `bun:test`'s `describe`/`test`/`expect`. No `vi.mock`, no `jest.mock`, no test doubles.
+
+## Rules
+
+- **Max 3-4 tests per method/function.** Cover the happy path, the documented edge cases, and at most one invariant.
+- **Test services, components, helpers, broad domain models.** Test domain models only when the model has functionality the service facade does not expose.
+- **Skip utils** (`src/utils/*`) — they are internal.
+- **Skip types** (`src/types.ts`).
+- **Cover `SKILL.md` and `README.md` first.** Tests are executable docs of the documented use cases.
+- **No mocks.** If a test seems to need one, the package likely belongs in category C (integration) or the test is asking the wrong question.
+- Cross-package imports are normal `import` statements; the workspace links resolve them.
+
+## Wiring `bun test`
+
+Per-package `package.json`:
+
+```json
+"scripts": {
+  "test": "bun test ./tests"
+}
+```
+
+`bun:test` is built-in — no devDeps to add. The root `bun run test` script runs every package's `test` script via workspace filters.
+
+## When auth shows up
+
+If a category-A package starts to need an authenticated identity to exercise a behaviour, that behaviour belongs in a different package — the auth-aware sibling. Don't reach for `@owlmeans/test-auth` here. Move the test to category B (and possibly the implementation) instead of dragging an auth dep into a low-layer package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/test",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,10 +21,10 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.7"
+    "@owlmeans/context": "^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"