@directive-run/claude-plugin 1.16.0

package/skills/testing-directive-code/testing.md

@@ -0,0 +1,412 @@
+# Testing
+
+> Covers `@directive-run/core/testing` — `createTestSystem`, mock resolvers, assertion helpers, coverage tracker, test observer.
+
+Testing utilities for Directive modules and systems. Import from `@directive-run/core/testing`.
+
+## Decision tree
+
+```
+What are you testing?
+├── A single module in isolation       → createTestSystem({ module })
+├── Multiple modules together           → createTestSystem({ modules: {...} })
+├── A constraint fires correctly        → set facts, system.assertRequirement(type)
+├── A resolver mutates facts            → mocks.resolvers[TYPE], dispatch, await waitForIdle, assertFactSet
+├── A derivation computes correctly     → set facts, read system.derive.x
+├── Async settling with retry/timeouts  → await system.waitForIdle() (uses real timers)
+├── Coverage tracking                    → createCoverageTracker(system)
+└── Observation event capture            → createTestObserver(system)
+```
+
+## Creating a test system
+
+`createTestSystem` takes an options OBJECT — the same shape as `createSystem` — and adds an optional `mocks.resolvers` map keyed by requirement type. There is no separate `createTestSystemFromModules` factory; the same overload handles both single-module (`module:`) and namespaced (`modules:`) systems.
+
+```typescript
+import { createTestSystem } from "@directive-run/core/testing";
+
+// Single module
+const system = createTestSystem({
+  module: counterModule,
+});
+
+// Namespaced (multi-module)
+const system = createTestSystem({
+  modules: { auth: authModule, cart: cartModule },
+});
+
+// With mocks — keyed by requirement type, value is a MockResolverOptions
+const system = createTestSystem({
+  module: userModule,
+  mocks: {
+    resolvers: {
+      FETCH_USER: {
+        resolve: (req, context) => {
+          context.facts.user = { id: req.userId, name: "Test User" };
+        },
+      },
+    },
+  },
+});
+```
+
+A `TestSystem` extends the production `SingleModuleSystem<S>` / `NamespacedSystem<Modules>` with extra fields for observability:
+
+```typescript
+system.waitForIdle(maxWait?);    // wait for all in-flight resolvers (default 5000ms; throws on timeout)
+system.eventHistory;              // every dispatched event
+system.resolverCalls;             // Map<requirementType, Requirement[]>
+system.allRequirements;           // every requirement generated (both resolved and pending)
+system.getFactsHistory();         // FactChangeRecord[] since start / last reset
+system.resetFactsHistory();
+```
+
+## Assertions are METHODS on the test system
+
+Assertion helpers live on the test-system instance, not as top-level imports. `assertFact` / `assertDerivation` / `assertRequirement` as top-level imports do not exist.
+
+```typescript
+system.assertRequirement("FETCH_USER");        // a requirement of this type was generated
+system.assertResolverCalled("FETCH_USER", 1);  // the resolver was called N times
+system.assertFactSet("phase", "loaded");       // the fact was set to a specific value
+system.assertFactChanges("count", 3);          // the fact was changed N times
+```
+
+For derivation assertions, just read the derivation value and use your test framework's expect / equality helpers:
+
+```typescript
+import { expect } from "vitest";
+expect(system.derive.isOverBudget).toBe(true);
+```
+
+## Testing constraints
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { createTestSystem } from "@directive-run/core/testing";
+
+describe("fetchWhenAuth constraint", () => {
+  it("emits FETCH_USER when authenticated without profile", () => {
+    const system = createTestSystem({ module: userModule });
+
+    system.facts.isAuthenticated = true;
+    system.facts.profile = null;
+
+    system.assertRequirement("FETCH_USER");
+  });
+
+  it("does NOT emit when already has a profile", () => {
+    const system = createTestSystem({
+      module: userModule,
+      initialFacts: {
+        isAuthenticated: true,
+        profile: { id: "1", name: "Alice" },
+      },
+    });
+
+    const inspection = system.inspect();
+    const fetchReqs = inspection.unmet.filter((r) => r.type === "FETCH_USER");
+    expect(fetchReqs).toHaveLength(0);
+  });
+});
+```
+
+`SystemInspection` exposes `unmet`, `inflight`, and other typed accessors — there is no flat `inspection.requirements` field. Filter the right list (`unmet` for pending requirements, `inflight` for in-progress).
+
+## Testing resolvers
+
+```typescript
+describe("fetchUser resolver", () => {
+  it("stores fetched user in facts", async () => {
+    const system = createTestSystem({
+      module: userModule,
+      mocks: {
+        resolvers: {
+          FETCH_USER: {
+            resolve: (req, context) => {
+              context.facts.user = { id: req.userId, name: "Mocked User" };
+              context.facts.phase = "loaded";
+            },
+          },
+        },
+      },
+    });
+
+    // Trigger the constraint that emits FETCH_USER
+    system.facts.isAuthenticated = true;
+    system.facts.user = null;
+
+    // Wait for the resolver to finish (default 5s timeout)
+    await system.waitForIdle();
+
+    system.assertFactSet("user", { id: expect.anything(), name: "Mocked User" });
+    system.assertFactSet("phase", "loaded");
+  });
+});
+```
+
+`mocks.resolvers[TYPE]` accepts a `MockResolverOptions` — the most common shape is `{ resolve: (req, context) => {…} }`. You can also pass full mock-resolver behaviors (`onCall`, `respondWith`, etc.) — see `MockResolverOptions` for the full surface.
+
+For programmatic control of when a mock resolves (e.g. holding a request to test loading states), use the `mockResolver(type)` factory:
+
+```typescript
+import { mockResolver } from "@directive-run/core/testing";
+
+const mock = mockResolver("FETCH_USER");
+
+const system = createTestSystem({
+  module: userModule,
+  mocks: {
+    resolvers: { FETCH_USER: { resolve: mock.handler } },
+  },
+});
+
+system.facts.isAuthenticated = true;
+
+// Now mock.pending contains the in-flight request — resolve it manually
+expect(mock.calls).toHaveLength(1);
+mock.pending[0].resolve({ id: "u1", name: "Alice" });
+
+await system.waitForIdle();
+```
+
+## Testing derivations
+
+Set facts, read the derived value via `system.derive`.
+
+```typescript
+describe("isOverBudget derivation", () => {
+  it("recomputes when facts change", () => {
+    const system = createTestSystem({
+      module: budgetModule,
+      initialFacts: { total: 50, budget: 100 },
+    });
+
+    expect(system.derive.isOverBudget).toBe(false);
+
+    system.facts.total = 200;
+
+    expect(system.derive.isOverBudget).toBe(true);
+  });
+});
+```
+
+## Async testing with fake timers
+
+`waitForIdle` uses real timers by default. For tests that depend on retry backoff / TTLs / timers without burning wall-clock seconds, use `createFakeTimers()` (a vitest/jest-compatible controller) or your test framework's fake-timer integration.
+
+```typescript
+import { describe, it, expect, vi } from "vitest";
+import { createTestSystem } from "@directive-run/core/testing";
+
+describe("retry behavior", () => {
+  it("retries on failure with exponential backoff", async () => {
+    vi.useFakeTimers();
+    let attempts = 0;
+
+    const system = createTestSystem({
+      module: myModule,
+      mocks: {
+        resolvers: {
+          FETCH_DATA: {
+            resolve: async (req, context) => {
+              attempts += 1;
+              if (attempts < 3) {
+                throw new Error("Temporary failure");
+              }
+              context.facts.data = "success";
+            },
+          },
+        },
+      },
+    });
+
+    system.facts.needsData = true;
+
+    // Advance through retry delays, then drain
+    await vi.runAllTimersAsync();
+    await system.waitForIdle();
+
+    expect(attempts).toBe(3);
+    system.assertFactSet("data", "success");
+
+    vi.useRealTimers();
+  });
+});
+```
+
+## Microtask flush
+
+For checking intermediate state without fully settling, use `flushMicrotasks()`.
+
+```typescript
+import { flushMicrotasks } from "@directive-run/core/testing";
+
+it("processes intermediate state", async () => {
+  const system = createTestSystem({ module: myModule });
+
+  system.facts.trigger = true;
+
+  // Process one round of microtasks without waiting for resolvers
+  await flushMicrotasks();
+
+  system.assertFactSet("phase", "loading");
+
+  await system.waitForIdle();
+
+  system.assertFactSet("phase", "done");
+});
+```
+
+## Coverage tracking
+
+```typescript
+import { createCoverageTracker } from "@directive-run/core/testing";
+
+const tracker = createCoverageTracker(system);
+
+await tracker.run(async () => {
+  system.facts.userId = 123;
+  await system.waitForIdle();
+});
+
+const coverage = tracker.report();
+// coverage.constraintCoverage   — 0-1
+// coverage.resolverCoverage     — 0-1
+// coverage.effectCoverage       — 0-1
+// coverage.derivationCoverage   — 0-1
+// coverage.constraintsMissed    — Set<string> of ids never triggered
+```
+
+## Test observer
+
+Capture observation events for assertion-based testing:
+
+```typescript
+import { createTestObserver } from "@directive-run/core/testing";
+
+const observer = createTestObserver(system);
+
+system.facts.count = 5;
+await system.waitForIdle();
+
+const evals = observer.ofType("constraint.evaluate");
+expect(evals).toHaveLength(1);
+
+observer.clear();   // reset captured events
+observer.dispose(); // stop capturing
+```
+
+## Anti-patterns
+
+### `createTestSystem(myModule)` (module as positional arg)
+
+```typescript
+// WRONG — createTestSystem takes an options object, not a positional module
+const system = createTestSystem(myModule);
+
+// CORRECT — wrap in { module: ... }
+const system = createTestSystem({ module: myModule });
+```
+
+### `createTestSystemFromModules({ a, b })`
+
+```typescript
+// WRONG — there is no separate factory; the same createTestSystem handles both forms
+const system = createTestSystemFromModules({ auth, cart });
+
+// CORRECT — pass `modules:`
+const system = createTestSystem({ modules: { auth, cart } });
+```
+
+### Importing assertions as top-level helpers
+
+```typescript
+// WRONG — assertFact / assertDerivation / assertRequirement are not top-level exports
+import { assertFact, assertDerivation, assertRequirement } from "@directive-run/core/testing";
+assertRequirement(system, "FETCH_USER");
+assertFact(system, "phase", "loaded");
+
+// CORRECT — they live on the test system instance
+system.assertRequirement("FETCH_USER");
+system.assertFactSet("phase", "loaded");
+
+// For derivation reads, use expect() directly
+expect(system.derive.isOverBudget).toBe(true);
+```
+
+### `mockResolvers: [mockResolver(TYPE, fn)]` (positional array)
+
+```typescript
+// WRONG — mocks are keyed by type, not an array; and mockResolver only takes the type
+const system = createTestSystem(myModule, {
+  mockResolvers: [
+    mockResolver("FETCH_USER", async (req, context) => { /* ... */ }),
+  ],
+});
+
+// CORRECT — mocks.resolvers is a Record<type, MockResolverOptions>
+const system = createTestSystem({
+  module: myModule,
+  mocks: {
+    resolvers: {
+      FETCH_USER: {
+        resolve: async (req, context) => { /* ... */ },
+      },
+    },
+  },
+});
+```
+
+### `inspection.requirements`
+
+```typescript
+// WRONG — SystemInspection has `unmet` and `inflight`, not a flat `requirements`
+inspection.requirements.filter((r) => r.type === "FETCH_USER")
+
+// CORRECT — filter the right list
+inspection.unmet.filter((r) => r.type === "FETCH_USER")     // pending
+inspection.inflight.filter((r) => r.type === "FETCH_USER")  // in-progress
+```
+
+### Calling `system.settle()` instead of `system.waitForIdle()`
+
+`system.settle(maxWait?)` exists on production systems. Test systems inherit it, but the recommended assertion-friendly drain on a `TestSystem` is `waitForIdle` — it shares the same semantics and integrates with the resolver-call tracking used by `assertResolverCalled`.
+
+```typescript
+// FINE — both work, but waitForIdle is the testing-flavored verb
+await system.settle();
+await system.waitForIdle();
+```
+
+### `ctx` instead of `context`
+
+```typescript
+// WRONG
+resolve: (req, ctx) => { ctx.facts.x = 1; }
+
+// CORRECT
+resolve: (req, context) => { context.facts.x = 1; }
+```
+
+## Quick reference
+
+| API | Path | Purpose |
+|---|---|---|
+| `createTestSystem(options)` | `@directive-run/core/testing` | Single overload; pass `module:` or `modules:` |
+| `mockResolver(type)` | `@directive-run/core/testing` | Programmatic mock with `calls` / `pending` / `handler` |
+| `createFakeTimers()` | `@directive-run/core/testing` | Vitest/Jest-compatible timer controller |
+| `flushMicrotasks()` | `@directive-run/core/testing` | Advance one microtask round |
+| `createCoverageTracker(system)` | `@directive-run/core/testing` | `run(fn)` + `report()` for constraint/resolver/effect/derivation hit rate |
+| `createTestObserver(system)` | `@directive-run/core/testing` | Capture observation events for assertions |
+| `system.assertRequirement(type)` | instance method | Assert a requirement was generated |
+| `system.assertResolverCalled(type, n?)` | instance method | Assert a resolver was called |
+| `system.assertFactSet(key, value?)` | instance method | Assert a fact value |
+| `system.assertFactChanges(key, n)` | instance method | Assert the change count for a fact |
+| `system.waitForIdle(maxWait?)` | instance method | Wait for in-flight resolvers (default 5000ms) |
+
+## See also
+
+- [`resolvers.md`](./resolvers.md) — the resolver shape `mocks.resolvers` replaces and the retry/cancel semantics tests need to know about
+- [`core-patterns.md`](./core-patterns.md) — the module shape `createTestSystem({ module })` is testing
+- [`history.md`](./history.md) — recorded snapshots for replay-based testing patterns