@codefast/di-testing 0.1.1 → 0.1.2

package/src/test-bed/sociable-builder.ts

@@ -1,148 +0,0 @@
-/** The fluent builder that compiles a unit together with chosen real collaborators. */
-
-import type { Constructor, DependencySlot, InjectOptions } from "@codefast/di";
-import { Container, token } from "@codefast/di";
-
-import { scanSociableDependencies } from "#/discovery/dependency-scanner";
-import { bindMocks } from "#/discovery/mock-binder";
-import { ExposureError } from "#/errors/errors";
-import type { MockFunction } from "#/mocking/mock-factory";
-import type { Spy } from "#/mocking/spy";
-import type { MockOverrideBuilder, PreparedBed } from "#/test-bed/bed-builder";
-import { BedBuilder } from "#/test-bed/bed-builder";
-import type { SociableUnitTestBed } from "#/test-bed/unit-test-bed";
-import { createSociableUnitTestBed, createUnitTestBed } from "#/test-bed/unit-test-bed";
-import type { InjectionIdentifier } from "#/types";
-
-/**
- * A sociable build in progress: expose real collaborators, override the rest, then compile.
- *
- * @remarks Exposure follows class identity: a class-keyed dependency of the unit — or of another
- * exposed class — stays real when exposed. A `Token`-keyed dependency is always mocked, treating
- * tokens as the declared boundary between the logic under test and the outside world.
- *
- * @typeParam Class - The class under test.
- * @typeParam Backend - The spy type the bed's mock factory produces.
- *
- * @since 0.1.0
- */
-export interface SociableTestBedBuilder<Class, Backend extends MockFunction = Spy> {
-  /** Keeps a class-keyed collaborator real; its own dependencies follow the same exposure rules. */
-  expose(target: Constructor): SociableTestBedBuilder<Class, Backend>;
-  /** Replaces the auto-mock for one dependency with a hand-written stub or a concrete value. */
-  mock<Dependency>(
-    identifier: InjectionIdentifier<Dependency>,
-    options?: InjectOptions,
-  ): MockOverrideBuilder<Dependency, SociableTestBedBuilder<Class, Backend>, Backend>;
-  /** Instantiates the unit and its exposed subtree, mocking everything else. */
-  compile(): SociableUnitTestBed<Class, Backend>;
-  /** Async variant for a subtree whose `@postConstruct` is async; otherwise identical to {@link compile}. */
-  compileAsync(): Promise<SociableUnitTestBed<Class, Backend>>;
-}
-
-/** What the sociable prepare step adds to the shared shape: the reachable exposed classes. */
-type PreparedSociableBed = PreparedBed & { readonly realClasses: ReadonlySet<Constructor> };
-
-/**
- * The default {@link SociableTestBedBuilder}, backed by a fresh container per compile.
- *
- * @typeParam Class - The class under test.
- * @typeParam Backend - The spy type the bed's mock factory produces.
- *
- * @since 0.1.0
- */
-export class SociableBuilder<Class, Backend extends MockFunction = Spy>
-  extends BedBuilder<Class, Backend>
-  implements SociableTestBedBuilder<Class, Backend>
-{
-  readonly #exposed = new Set<Constructor>();
-
-  expose(target: Constructor): this {
-    this.#exposed.add(target);
-    return this;
-  }
-
-  compile(): SociableUnitTestBed<Class, Backend> {
-    return this.compileWith(
-      () => this.#prepare(),
-      (unit, prepared) =>
-        createSociableUnitTestBed(
-          createUnitTestBed(unit, prepared.mocks, prepared.container),
-          prepared.container,
-          prepared.realClasses,
-        ),
-    );
-  }
-
-  async compileAsync(): Promise<SociableUnitTestBed<Class, Backend>> {
-    return this.compileWithAsync(
-      () => this.#prepare(),
-      (unit, prepared) =>
-        createSociableUnitTestBed(
-          createUnitTestBed(unit, prepared.mocks, prepared.container),
-          prepared.container,
-          prepared.realClasses,
-        ),
-    );
-  }
-
-  /** Scans across the exposed set, binds mocks for the boundary, and binds every real class. */
-  #prepare(): PreparedSociableBed {
-    if (this.#exposed.has(this.target)) {
-      throw new ExposureError(this.target.name, "the unit under test is already real — expose only its collaborators.");
-    }
-
-    const container = Container.create({ metadataReader: this.reader });
-    const { mockSlots, realClasses, realSlots } = scanSociableDependencies(this.target, this.#exposed, this.reader);
-
-    // An exposed class the unit never reaches is a stale exposure — likely a typo or a refactor.
-    for (const exposedClass of this.#exposed) {
-      if (!realClasses.has(exposedClass)) {
-        throw new ExposureError(
-          exposedClass.name,
-          "the unit never reaches this class through exposed collaborators. Expose the intermediate classes on the path to it, or remove the exposure.",
-        );
-      }
-    }
-
-    const mocks = bindMocks(container, mockSlots, this.overrides, this.mockFactory, this.#exposed);
-
-    const constrainedSlots = new Map<Constructor, Array<DependencySlot>>();
-    for (const slot of realSlots) {
-      const list = constrainedSlots.get(slot.token as Constructor) ?? [];
-      list.push(slot);
-      constrainedSlots.set(slot.token as Constructor, list);
-    }
-
-    // Real collaborators are singletons, so the unit and bed.exposed() see one instance each,
-    // and their @preDestroy hooks run on dispose.
-    const merged = new Map(mocks);
-    for (const realClass of realClasses) {
-      const slots = constrainedSlots.get(realClass);
-      if (slots === undefined) {
-        container.bind(realClass).toSelf().singleton();
-      } else {
-        // A name/tag-constrained slot needs its own binding, and di rejects a self-alias — so the
-        // one real binding lives on a private token, and every slot of the class resolves it
-        // through a factory (an alias would forward the slot's criteria to the private token).
-        const realToken = token<unknown>(`di-testing:real:${realClass.name}`);
-        container.bind(realToken).to(realClass).singleton();
-        container.bind(realClass).toDynamic((context) => context.resolve(realToken));
-        for (const slot of slots) {
-          const builder = container.bind(realClass).toDynamic((context) => context.resolve(realToken));
-          if (slot.name !== undefined) {
-            builder.whenNamed(slot.name);
-          }
-          for (const tag of slot.tags ?? []) {
-            builder.whenTagged(tag);
-          }
-        }
-      }
-      // Sealed entries so mocks.get points at bed.exposed() instead of handing back a fake Mocked.
-      merged.set(realClass, [{ criteria: undefined, value: undefined, kind: "exposed" }]);
-    }
-    container.bind(this.target).toSelf().singleton();
-
-    return { container, mocks: merged, realClasses };
-  }
-}

package/src/test-bed/solitary-builder.ts

@@ -1,70 +0,0 @@
-/** The fluent builder that compiles a solitary unit under test. */
-
-import type { InjectOptions } from "@codefast/di";
-import { Container } from "@codefast/di";
-
-import { scanDependencies } from "#/discovery/dependency-scanner";
-import { bindMocks } from "#/discovery/mock-binder";
-import type { MockFunction } from "#/mocking/mock-factory";
-import type { Spy } from "#/mocking/spy";
-import type { MockOverrideBuilder, PreparedBed } from "#/test-bed/bed-builder";
-import { BedBuilder } from "#/test-bed/bed-builder";
-import type { UnitTestBed } from "#/test-bed/unit-test-bed";
-import { createUnitTestBed } from "#/test-bed/unit-test-bed";
-import type { InjectionIdentifier } from "#/types";
-
-/**
- * A solitary build in progress: register overrides, then compile.
- *
- * @typeParam Class - The class under test.
- * @typeParam Backend - The spy type the bed's mock factory produces.
- *
- * @since 0.1.0
- */
-export interface SolitaryTestBedBuilder<Class, Backend extends MockFunction = Spy> {
-  /** Replaces the auto-mock for one dependency with a hand-written stub or a concrete value. */
-  mock<Dependency>(
-    identifier: InjectionIdentifier<Dependency>,
-    options?: InjectOptions,
-  ): MockOverrideBuilder<Dependency, SolitaryTestBedBuilder<Class, Backend>, Backend>;
-  /** Instantiates the unit with every dependency mocked, running accessor injection and `@postConstruct`. */
-  compile(): UnitTestBed<Class, Backend>;
-  /** Async variant for a unit whose `@postConstruct` is async; otherwise identical to {@link compile}. */
-  compileAsync(): Promise<UnitTestBed<Class, Backend>>;
-}
-
-/**
- * The default {@link SolitaryTestBedBuilder}, backed by a fresh container per compile.
- *
- * @typeParam Class - The class under test.
- * @typeParam Backend - The spy type the bed's mock factory produces.
- *
- * @since 0.1.0
- */
-export class SolitaryBuilder<Class, Backend extends MockFunction = Spy>
-  extends BedBuilder<Class, Backend>
-  implements SolitaryTestBedBuilder<Class, Backend>
-{
-  compile(): UnitTestBed<Class, Backend> {
-    return this.compileWith(
-      () => this.#prepare(),
-      (unit, prepared) => createUnitTestBed(unit, prepared.mocks, prepared.container),
-    );
-  }
-
-  async compileAsync(): Promise<UnitTestBed<Class, Backend>> {
-    return this.compileWithAsync(
-      () => this.#prepare(),
-      (unit, prepared) => createUnitTestBed(unit, prepared.mocks, prepared.container),
-    );
-  }
-
-  /** Builds the container, binds every dependency's mock, and registers the unit as a singleton. */
-  #prepare(): PreparedBed {
-    const container = Container.create({ metadataReader: this.reader });
-    const dependencies = scanDependencies(this.target, this.reader);
-    const mocks = bindMocks(container, dependencies, this.overrides, this.mockFactory);
-    container.bind(this.target).toSelf().singleton();
-    return { container, mocks };
-  }
-}

package/src/test-bed/test-bed.ts

@@ -1,64 +0,0 @@
-/** The entry point for building isolated units under test. */
-
-import type { Constructor } from "@codefast/di";
-
-import type { MockFunction } from "#/mocking/mock-factory";
-import type { Spy } from "#/mocking/spy";
-import type { TestBedOptions } from "#/test-bed/bed-builder";
-import { SociableBuilder } from "#/test-bed/sociable-builder";
-import type { SociableTestBedBuilder } from "#/test-bed/sociable-builder";
-import { SolitaryBuilder } from "#/test-bed/solitary-builder";
-import type { SolitaryTestBedBuilder } from "#/test-bed/solitary-builder";
-
-/**
- * The factory surface for building isolated units under test.
- *
- * @since 0.1.0
- */
-export interface TestBedStatic {
-  /**
-   * Begins a solitary test bed for `target`, auto-mocking every dependency it declares.
-   *
-   * @remarks The mock factory's return type becomes `Backend` and types every mock the bed hands
-   * out — pass `{ mockFactory: () => vi.fn() }` and `mocks.get(X).method` carries Vitest's own
-   * mock surface.
-   */
-  solitary<Class, Backend extends MockFunction = Spy>(
-    target: Constructor<Class>,
-    options?: TestBedOptions<Backend>,
-  ): SolitaryTestBedBuilder<Class, Backend>;
-
-  /**
-   * Begins a sociable test bed for `target`: chosen class collaborators stay real, tokens stay mocked.
-   *
-   * @remarks Returns only `expose` — a sociable bed without at least one exposed collaborator is a
-   * solitary bed, so the type steers the first call.
-   */
-  sociable<Class, Backend extends MockFunction = Spy>(
-    target: Constructor<Class>,
-    options?: TestBedOptions<Backend>,
-  ): Pick<SociableTestBedBuilder<Class, Backend>, "expose">;
-}
-
-/**
- * Entry point for auto-mocking a class in isolation from its collaborators.
- *
- * @remarks `solitary` and `sociable` record the target and options only; nothing is instantiated
- * until `compile()`.
- *
- * @since 0.1.0
- */
-export const TestBed: TestBedStatic = {
-  solitary<Class, Backend extends MockFunction = Spy>(
-    target: Constructor<Class>,
-    options?: TestBedOptions<Backend>,
-  ): SolitaryTestBedBuilder<Class, Backend> {
-    return new SolitaryBuilder<Class, Backend>(target, options);
-  },
-  sociable<Class, Backend extends MockFunction = Spy>(
-    target: Constructor<Class>,
-    options?: TestBedOptions<Backend>,
-  ): Pick<SociableTestBedBuilder<Class, Backend>, "expose"> {
-    return new SociableBuilder<Class, Backend>(target, options);
-  },
-};

package/src/test-bed/unit-test-bed.ts

@@ -1,161 +0,0 @@
-/// <reference lib="esnext.disposable" />
-
-/** The compiled result of a test bed: the real unit plus handles to its mocks. */
-
-import type { Constructor, Container, DependencyKey, InjectOptions, TokenValue } from "@codefast/di";
-import { tokenName } from "@codefast/di";
-
-import type { BoundMock } from "#/discovery/mock-binder";
-import { criteriaEquals, normalizeCriteria } from "#/discovery/mock-binder";
-import { ExposureError, SealedDependencyError, UndeclaredDependencyError } from "#/errors/errors";
-import type { Mocked } from "#/mocking/auto-mock";
-import { MOCK_RESET } from "#/mocking/auto-mock";
-import type { MockFunction } from "#/mocking/mock-factory";
-import type { Spy } from "#/mocking/spy";
-
-/**
- * A lookup from a dependency's token or class to the mock the unit was built with.
- *
- * @typeParam Backend - The spy type the bed's mock factory produces.
- *
- * @since 0.1.0
- */
-export interface UnitReference<Backend extends MockFunction = Spy> {
-  /**
-   * Retrieves the mock bound for one of the unit's dependencies, typed to that dependency's value.
-   *
-   * @remarks Pass `options` (a name or tags) to address one slot of a token injected several ways.
-   * Only auto-mocks and `.stub` seeds come back — a value supplied with `.using()`, `.absent()`, or
-   * `.usingAll()` is sealed, and an exposed class is real, so neither has a mock surface for the
-   * `Mocked` type to describe.
-   *
-   * @throws UndeclaredDependencyError When the identifier or slot is not one of the unit's dependencies.
-   * @throws SealedDependencyError When the dependency was supplied as a sealed value or exposed.
-   */
-  get<Identifier extends DependencyKey>(
-    identifier: Identifier,
-    options?: InjectOptions,
-  ): Mocked<TokenValue<Identifier>, Backend>;
-}
-
-/**
- * A compiled unit: the real class under test, plus a handle to every mock it received.
- *
- * @remarks Implements `AsyncDisposable`, so `await using bed = TestBed.solitary(X).compile()` runs
- * the unit's `@preDestroy` hooks and disposes the backing container at the end of the block.
- *
- * @typeParam Class - The class under test.
- * @typeParam Backend - The spy type the bed's mock factory produces.
- *
- * @since 0.1.0
- */
-export interface UnitTestBed<Class, Backend extends MockFunction = Spy> extends AsyncDisposable {
-  readonly unit: Class;
-  readonly mocks: UnitReference<Backend>;
-  /** Clears the call history and configured behaviour of every auto-mock and stub the bed created. */
-  resetMocks(this: void): void;
-  /** Runs the unit's `@preDestroy` hooks and disposes the backing container. */
-  dispose(this: void): Promise<void>;
-}
-
-/**
- * A sociable bed: the solitary surface plus access to the real collaborators it exposed.
- *
- * @typeParam Class - The class under test.
- * @typeParam Backend - The spy type the bed's mock factory produces.
- *
- * @since 0.1.0
- */
-export interface SociableUnitTestBed<Class, Backend extends MockFunction = Spy> extends UnitTestBed<Class, Backend> {
-  /**
-   * Returns the real instance of an exposed collaborator — the one the unit was actually built with.
-   *
-   * @throws ExposureError When the class was not exposed.
-   */
-  exposed<Real>(target: Constructor<Real>): Real;
-}
-
-/**
- * Wraps a compiled bed with access to its exposed real collaborators.
- *
- * @since 0.1.0
- */
-export function createSociableUnitTestBed<Class, Backend extends MockFunction = Spy>(
-  bed: UnitTestBed<Class, Backend>,
-  container: Container,
-  exposedClasses: ReadonlySet<Constructor>,
-): SociableUnitTestBed<Class, Backend> {
-  // Copied member by member, so a future bed with accessor or prototype members cannot be dropped
-  // silently by a spread.
-  return {
-    unit: bed.unit,
-    mocks: bed.mocks,
-    resetMocks: bed.resetMocks,
-    dispose: bed.dispose,
-    [Symbol.asyncDispose]: bed[Symbol.asyncDispose],
-    exposed<Real>(target: Constructor<Real>): Real {
-      if (!exposedClasses.has(target)) {
-        throw new ExposureError(target.name, "the class was not exposed. Add .expose(Class) before compile().");
-      }
-      // Exposed classes are singletons the unit's construction already instantiated.
-      return container.resolve(target);
-    },
-  };
-}
-
-/**
- * Assembles a {@link UnitTestBed} around an instantiated unit and its bound mock entries.
- *
- * @since 0.1.0
- */
-export function createUnitTestBed<Class, Backend extends MockFunction = Spy>(
-  unit: Class,
-  entries: ReadonlyMap<DependencyKey, ReadonlyArray<BoundMock>>,
-  container: Container,
-): UnitTestBed<Class, Backend> {
-  const mocks: UnitReference<Backend> = {
-    get<Identifier extends DependencyKey>(
-      identifier: Identifier,
-      options?: InjectOptions,
-    ): Mocked<TokenValue<Identifier>, Backend> {
-      const bound = entries.get(identifier);
-      if (bound === undefined) {
-        throw new UndeclaredDependencyError(tokenName(identifier));
-      }
-      const criteria = normalizeCriteria(options);
-      const entry =
-        criteria === undefined
-          ? (bound.find((candidate) => candidate.criteria === undefined) ?? (bound.length === 1 ? bound[0] : undefined))
-          : bound.find((candidate) => candidate.criteria !== undefined && criteriaEquals(candidate.criteria, criteria));
-      if (entry === undefined) {
-        throw new UndeclaredDependencyError(tokenName(identifier), "no such slot");
-      }
-      if (entry.kind !== "auto" && entry.kind !== "stub") {
-        throw new SealedDependencyError(tokenName(identifier), entry.kind);
-      }
-      return entry.value as Mocked<TokenValue<Identifier>, Backend>;
-    },
-  };
-
-  const resetMocks = (): void => {
-    for (const bound of entries.values()) {
-      for (const entry of bound) {
-        if (entry.kind === "auto" || entry.kind === "stub") {
-          (entry.value as { [MOCK_RESET]?: () => void })[MOCK_RESET]?.();
-        }
-      }
-    }
-  };
-
-  const dispose = async (): Promise<void> => {
-    await container.dispose();
-  };
-
-  return {
-    unit,
-    mocks,
-    resetMocks,
-    dispose,
-    [Symbol.asyncDispose]: dispose,
-  };
-}

package/src/types.ts

@@ -1,15 +0,0 @@
-/** Shared vocabulary the test bed keys its dependencies by. */
-
-import type { Constructor, Token } from "@codefast/di";
-
-/**
- * A token or class constructor used to identify one of the unit's dependencies.
- *
- * @remarks The value-typed counterpart of di's own `DependencyKey`: it carries `Value` so
- * `mocks.get()` can map an identifier back to the mock type it produced.
- *
- * @typeParam Value - The value type the identified dependency resolves to.
- *
- * @since 0.1.0
- */
-export type InjectionIdentifier<Value> = Token<Value> | Constructor<Value>;