@noego/testing 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,94 @@
+# @noego/testing
+
+The canonical shared owner of NoEgo test composition and method control:
+`testIoc` real-IoC environments plus the lowercase `test.*` behavior, watch,
+inspection, and expectation language. Built on `@noego/ioc`'s production seams
+— real containers, real lifetimes, real scopes. A fake container is never the
+production-equivalent testing foundation.
+
+```ts
+import { testIoc, test } from '@noego/testing';
+
+const env = await testIoc()
+  .methods({
+    ProjectRepository: {
+      save: test.once(test.returns(project)),
+    },
+  })
+  .build();
+
+const service = await env.get(ProjectService);
+service.create('demo');
+
+await env.verify();
+await env.dispose();
+```
+
+## The builder is a persistent immutable value
+
+Every fluent call returns a new derived builder; the parent stays reusable.
+Non-conflicting writes are order-insensitive; the last write to the same
+effective identity wins on that derived branch. `.build()` is non-consuming
+and every build creates fresh runtime, watch, and expectation state — parallel
+environments never share state.
+
+```ts
+const base = testIoc()
+  .classes(new Map([[ProjectRepository, MemoryProjectRepository]]))
+  .values({ FeatureFlags: testFlags });
+
+const admin = base.values({ CurrentUser: adminUser });
+const guest = base.values({ CurrentUser: guestUser });
+```
+
+Configuration surfaces:
+
+| Call | Identity space | Meaning |
+|---|---|---|
+| `.use(preset)` | ordered overlay | apply an `ApplicationModule` or another builder as reusable composition |
+| `.classes({...})` | IoC class token | replace the implementation behind a class token (lifetime validation stays real) |
+| `.functions({...})` | IoC provider key | replace a factory/provider registration (configured lifetime preserved) |
+| `.values({...})` | IoC value token | provide/replace value registrations |
+| `.methods({...})` | token + method | install `test.*` behavior/observation descriptors |
+
+Plain-object keys are matched by token name; pass a `Map` to key by the
+class/token itself. Unknown string keys fail with the known tokens listed.
+
+## `test.*`
+
+```ts
+test.returns(value)   // replace the result            (auto-watches)
+test.throws(error)    // throw/reject                  (auto-watches)
+test.original()       // call the real implementation  (auto-watches)
+test.calls([...])     // one behavior per invocation; overflow fails immediately
+
+test.watch()          // keep original behavior, record calls
+test.inspect(env, Token, 'method')  // read the recorded history
+
+test.once()           // exactly one call (original behavior)
+test.once(behavior)   // exactly one call with the supplied behavior
+test.times(n, b?)     // exactly n calls
+test.never()          // zero calls; first invocation fails, original skipped
+```
+
+Every installed descriptor automatically watches its method; only watched
+methods are inspectable. Over-calls fail at invocation time; under-calls are
+finalized by `await env.verify()` (a repeatable snapshot that aggregates every
+unsatisfied expectation). A raw wrapper function
+(`(original) => (...args) => ...`) is installed as-is and is **not** watched.
+
+## Environment
+
+`build()` returns `{ root, get, instance, extend, verify, dispose }`. `extend()`
+creates a real child scope (method configuration and watches apply there too);
+`dispose()` disposes the whole environment through `@noego/ioc`'s scope
+disposal — including disposable objects registered via `.values()`.
+
+## 0.1.x → 0.2.0
+
+The old generic runtime-mirror doubles (ManualClock, ManualScheduler,
+ScriptedFetchClient, ScriptedProcessRunner, memory stores, RecordingEventBus,
+recording sinks, contract suites, LeakDetector) are retired along with the
+`@noego/runtime` dependency, per the NoEgo runtime/testing deprecation plan.
+Pin `0.1.x` if you still need them; boundary-specific helpers move to their
+natural production owners.