@alloy-di/testing 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 The Alloy DI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @alloy-di/testing
+
+Runner-neutral test-container utilities for [Alloy DI](https://alloy-di.dev), with thin
+adapters for popular test runners.
+
+- `@alloy-di/testing` — the runner-neutral core (`createTestContainer`, mocking types). Requires
+  you to supply a `mockFn` when using `autoMock`.
+- `@alloy-di/testing/vitest` — wires `vi.fn` from Vitest.
+- `@alloy-di/testing/jest` — wires `jest.fn` from `@jest/globals`.
+- `@alloy-di/testing/node` — wires `mock.fn()` from `node:test`.
+
+## Usage
+
+```ts
+import { createTestContainer } from "@alloy-di/testing/vitest";
+
+const test = createTestContainer({
+  autoMock: true,
+  target: UserService,
+  providers,
+});
+
+afterEach(() => test.restore());
+```
+
+Or let the adapter manage cleanup for you:
+
+```ts
+import { setupAlloyTesting } from "@alloy-di/testing/vitest";
+
+const alloyTesting = setupAlloyTesting(); // registers afterEach once
+
+const test = alloyTesting.createTestContainer({
+  autoMock: true,
+  target: UserService,
+  providers,
+});
+```
+
+Importing an adapter never registers test hooks on its own — only `setupAlloyTesting()` does.
+
+## Migration from `alloy-di/test`
+
+`alloy-di/test` was removed in `alloy-di` 2.0. Replace:
+
+```ts
+import { createTestContainer } from "alloy-di/test";
+```
+
+with:
+
+```ts
+import { createTestContainer } from "@alloy-di/testing/vitest";
+```
+
+The API is identical — only the import specifier changes.

package/dist/adapters/jest.d.ts

@@ -0,0 +1,40 @@
+import { GenericSpy, MockFnFactory, MockOf } from "../lib/mocking.js";
+import { CreateTestContainerOptions, FactoryOverrideSpec, OverrideSpec, TestContainerHandle, TestScopeHierarchy } from "../lib/core.js";
+import { createToken } from "../index.js";
+import { Mock } from "jest-mock";
+
+//#region src/adapters/jest.d.ts
+/** A Jest spy, as produced by `jest.fn()`. */
+type JestSpy = Mock;
+/** Options accepted by the Jest adapter (the `mockFn`/`resetFn` bindings are supplied for you). */
+type JestTestContainerOptions = Omit<CreateTestContainerOptions<JestSpy>, "mockFn" | "resetFn">;
+/**
+ * Create a test container wired to Jest spies (`jest.fn`). Does not register
+ * any cleanup hooks — call `handle.restore()` yourself, or use
+ * {@link setupAlloyTesting} for automatic cleanup.
+ */
+declare function createTestContainer(opts?: JestTestContainerOptions | OverrideSpec): TestContainerHandle<JestSpy> & {
+  getMock<T>(ctor: import("alloy-di/runtime").Newable<T>): MockOf<T, JestSpy> | undefined;
+  getMocks<T extends readonly import("alloy-di/runtime").Newable<unknown>[]>(ctors: T): { [K in keyof T]: T[K] extends import("alloy-di/runtime").Newable<infer I> ? MockOf<I, JestSpy> | undefined : never };
+  provideToken<T>(token: import("alloy-di/runtime").Token<T>, value: T): void;
+  provideFactory<T>(token: import("alloy-di/runtime").Token<T>, factory: import("alloy-di/runtime").FactoryFn<T>, options?: {
+    lifecycle?: import("alloy-di/runtime").ServiceScope;
+  }): void;
+  overrideFactory<T>(token: import("alloy-di/runtime").Token<T>, factory: import("alloy-di/runtime").FactoryFn<T>, options?: {
+    lifecycle?: import("alloy-di/runtime").ServiceScope;
+  }): void;
+  createScope(scopeName: import("alloy-di/runtime").ServiceScope): import("alloy-di/scopes").Scope;
+  spyOf<T>(ctor: import("alloy-di/runtime").Newable<T>, method: Extract<keyof T, string>): JestSpy | undefined;
+  clearMockSpies(): void;
+};
+type JestTestContainer = ReturnType<typeof createTestContainer>;
+/**
+ * Register a Jest `afterEach` hook that restores and clears every container
+ * created through the returned `createTestContainer`. Call this once per test
+ * file (or in a shared setup file).
+ */
+declare function setupAlloyTesting(): {
+  createTestContainer(opts?: JestTestContainerOptions | OverrideSpec): JestTestContainer;
+};
+//#endregion
+export { type CreateTestContainerOptions, type FactoryOverrideSpec, type GenericSpy, JestSpy, JestTestContainer, JestTestContainerOptions, type MockFnFactory, type MockOf, type OverrideSpec, type TestContainerHandle, type TestScopeHierarchy, createTestContainer, createToken, setupAlloyTesting };

package/dist/adapters/jest.js

@@ -0,0 +1,43 @@
+import { createTestContainer as createTestContainer$1 } from "../lib/core.js";
+import { createToken } from "../index.js";
+import { afterEach, jest } from "@jest/globals";
+//#region src/adapters/jest.ts
+const binding = {
+	mockFn: () => jest.fn(),
+	resetFn: (spy) => {
+		spy.mockReset();
+	}
+};
+/**
+* Create a test container wired to Jest spies (`jest.fn`). Does not register
+* any cleanup hooks — call `handle.restore()` yourself, or use
+* {@link setupAlloyTesting} for automatic cleanup.
+*/
+function createTestContainer(opts) {
+	return createTestContainer$1({
+		...opts,
+		...binding
+	});
+}
+/**
+* Register a Jest `afterEach` hook that restores and clears every container
+* created through the returned `createTestContainer`. Call this once per test
+* file (or in a shared setup file).
+*/
+function setupAlloyTesting() {
+	const handles = /* @__PURE__ */ new Set();
+	afterEach(() => {
+		for (const handle of [...handles].toReversed()) {
+			handle.clearMockSpies();
+			handle.restore();
+		}
+		handles.clear();
+	});
+	return { createTestContainer(opts) {
+		const handle = createTestContainer(opts);
+		handles.add(handle);
+		return handle;
+	} };
+}
+//#endregion
+export { createTestContainer, createToken, setupAlloyTesting };

package/dist/adapters/node.d.ts

@@ -0,0 +1,40 @@
+import { GenericSpy, MockFnFactory, MockOf } from "../lib/mocking.js";
+import { CreateTestContainerOptions, FactoryOverrideSpec, OverrideSpec, TestContainerHandle, TestScopeHierarchy } from "../lib/core.js";
+import { createToken } from "../index.js";
+import { mock } from "node:test";
+
+//#region src/adapters/node.d.ts
+/** A `node:test` mock function, as produced by `mock.fn()`. */
+type NodeSpy = ReturnType<typeof mock.fn>;
+/** Options accepted by the node:test adapter (the `mockFn`/`resetFn` bindings are supplied for you). */
+type NodeTestContainerOptions = Omit<CreateTestContainerOptions<NodeSpy>, "mockFn" | "resetFn">;
+/**
+ * Create a test container wired to `node:test` mocks (`mock.fn()`). Does not
+ * register any cleanup hooks — call `handle.restore()` yourself, or use
+ * {@link setupAlloyTesting} for automatic cleanup.
+ */
+declare function createTestContainer(opts?: NodeTestContainerOptions | OverrideSpec): TestContainerHandle<import("node:test").Mock<Function>> & {
+  getMock<T>(ctor: import("alloy-di/runtime").Newable<T>): MockOf<T, import("node:test").Mock<Function>> | undefined;
+  getMocks<T extends readonly import("alloy-di/runtime").Newable<unknown>[]>(ctors: T): { [K in keyof T]: T[K] extends import("alloy-di/runtime").Newable<infer I> ? MockOf<I, import("node:test").Mock<Function>> | undefined : never };
+  provideToken<T>(token: import("alloy-di/runtime").Token<T>, value: T): void;
+  provideFactory<T>(token: import("alloy-di/runtime").Token<T>, factory: import("alloy-di/runtime").FactoryFn<T>, options?: {
+    lifecycle?: import("alloy-di/runtime").ServiceScope;
+  }): void;
+  overrideFactory<T>(token: import("alloy-di/runtime").Token<T>, factory: import("alloy-di/runtime").FactoryFn<T>, options?: {
+    lifecycle?: import("alloy-di/runtime").ServiceScope;
+  }): void;
+  createScope(scopeName: import("alloy-di/runtime").ServiceScope): import("alloy-di/scopes").Scope;
+  spyOf<T>(ctor: import("alloy-di/runtime").Newable<T>, method: Extract<keyof T, string>): import("node:test").Mock<Function> | undefined;
+  clearMockSpies(): void;
+};
+type NodeTestContainer = ReturnType<typeof createTestContainer>;
+/**
+ * Register a `node:test` `afterEach` hook that restores and clears every
+ * container created through the returned `createTestContainer`. Call this once
+ * per test file (or in a shared setup file).
+ */
+declare function setupAlloyTesting(): {
+  createTestContainer(opts?: NodeTestContainerOptions | OverrideSpec): NodeTestContainer;
+};
+//#endregion
+export { type CreateTestContainerOptions, type FactoryOverrideSpec, type GenericSpy, type MockFnFactory, type MockOf, NodeSpy, NodeTestContainer, NodeTestContainerOptions, type OverrideSpec, type TestContainerHandle, type TestScopeHierarchy, createTestContainer, createToken, setupAlloyTesting };

package/dist/adapters/node.js

@@ -0,0 +1,43 @@
+import { createTestContainer as createTestContainer$1 } from "../lib/core.js";
+import { createToken } from "../index.js";
+import { afterEach, mock } from "node:test";
+//#region src/adapters/node.ts
+const binding = {
+	mockFn: () => mock.fn(),
+	resetFn: (spy) => {
+		spy.mock.resetCalls();
+	}
+};
+/**
+* Create a test container wired to `node:test` mocks (`mock.fn()`). Does not
+* register any cleanup hooks — call `handle.restore()` yourself, or use
+* {@link setupAlloyTesting} for automatic cleanup.
+*/
+function createTestContainer(opts) {
+	return createTestContainer$1({
+		...opts,
+		...binding
+	});
+}
+/**
+* Register a `node:test` `afterEach` hook that restores and clears every
+* container created through the returned `createTestContainer`. Call this once
+* per test file (or in a shared setup file).
+*/
+function setupAlloyTesting() {
+	const handles = /* @__PURE__ */ new Set();
+	afterEach(() => {
+		for (const handle of [...handles].toReversed()) {
+			handle.clearMockSpies();
+			handle.restore();
+		}
+		handles.clear();
+	});
+	return { createTestContainer(opts) {
+		const handle = createTestContainer(opts);
+		handles.add(handle);
+		return handle;
+	} };
+}
+//#endregion
+export { createTestContainer, createToken, setupAlloyTesting };

package/dist/adapters/vitest.d.ts

@@ -0,0 +1,40 @@
+import { GenericSpy, MockFnFactory, MockOf } from "../lib/mocking.js";
+import { CreateTestContainerOptions, FactoryOverrideSpec, OverrideSpec, TestContainerHandle, TestScopeHierarchy } from "../lib/core.js";
+import { createToken } from "../index.js";
+import { Mock } from "vitest";
+
+//#region src/adapters/vitest.d.ts
+/** A Vitest spy, as produced by `vi.fn()`. */
+type VitestSpy = Mock;
+/** Options accepted by the Vitest adapter (the `mockFn`/`resetFn` bindings are supplied for you). */
+type VitestTestContainerOptions = Omit<CreateTestContainerOptions<VitestSpy>, "mockFn" | "resetFn">;
+/**
+ * Create a test container wired to Vitest spies (`vi.fn`). Does not register
+ * any cleanup hooks — call `handle.restore()` yourself, or use
+ * {@link setupAlloyTesting} for automatic cleanup.
+ */
+declare function createTestContainer(opts?: VitestTestContainerOptions | OverrideSpec): TestContainerHandle<VitestSpy> & {
+  getMock<T>(ctor: import("alloy-di/runtime").Newable<T>): MockOf<T, VitestSpy> | undefined;
+  getMocks<T extends readonly import("alloy-di/runtime").Newable<unknown>[]>(ctors: T): { [K in keyof T]: T[K] extends import("alloy-di/runtime").Newable<infer I> ? MockOf<I, VitestSpy> | undefined : never };
+  provideToken<T>(token: import("alloy-di/runtime").Token<T>, value: T): void;
+  provideFactory<T>(token: import("alloy-di/runtime").Token<T>, factory: import("alloy-di/runtime").FactoryFn<T>, options?: {
+    lifecycle?: import("alloy-di/runtime").ServiceScope;
+  }): void;
+  overrideFactory<T>(token: import("alloy-di/runtime").Token<T>, factory: import("alloy-di/runtime").FactoryFn<T>, options?: {
+    lifecycle?: import("alloy-di/runtime").ServiceScope;
+  }): void;
+  createScope(scopeName: import("alloy-di/runtime").ServiceScope): import("alloy-di/scopes").Scope;
+  spyOf<T>(ctor: import("alloy-di/runtime").Newable<T>, method: Extract<keyof T, string>): VitestSpy | undefined;
+  clearMockSpies(): void;
+};
+type VitestTestContainer = ReturnType<typeof createTestContainer>;
+/**
+ * Register a Vitest `afterEach` hook that restores and clears every container
+ * created through the returned `createTestContainer`. Call this once per test
+ * file (or in a shared setup file).
+ */
+declare function setupAlloyTesting(): {
+  createTestContainer(opts?: VitestTestContainerOptions | OverrideSpec): VitestTestContainer;
+};
+//#endregion
+export { type CreateTestContainerOptions, type FactoryOverrideSpec, type GenericSpy, type MockFnFactory, type MockOf, type OverrideSpec, type TestContainerHandle, type TestScopeHierarchy, VitestSpy, VitestTestContainer, VitestTestContainerOptions, createTestContainer, createToken, setupAlloyTesting };

package/dist/adapters/vitest.js

@@ -0,0 +1,43 @@
+import { createTestContainer as createTestContainer$1 } from "../lib/core.js";
+import { createToken } from "../index.js";
+import { afterEach, vi } from "vitest";
+//#region src/adapters/vitest.ts
+const binding = {
+	mockFn: () => vi.fn(),
+	resetFn: (spy) => {
+		spy.mockReset();
+	}
+};
+/**
+* Create a test container wired to Vitest spies (`vi.fn`). Does not register
+* any cleanup hooks — call `handle.restore()` yourself, or use
+* {@link setupAlloyTesting} for automatic cleanup.
+*/
+function createTestContainer(opts) {
+	return createTestContainer$1({
+		...opts,
+		...binding
+	});
+}
+/**
+* Register a Vitest `afterEach` hook that restores and clears every container
+* created through the returned `createTestContainer`. Call this once per test
+* file (or in a shared setup file).
+*/
+function setupAlloyTesting() {
+	const handles = /* @__PURE__ */ new Set();
+	afterEach(() => {
+		for (const handle of [...handles].toReversed()) {
+			handle.clearMockSpies();
+			handle.restore();
+		}
+		handles.clear();
+	});
+	return { createTestContainer(opts) {
+		const handle = createTestContainer(opts);
+		handles.add(handle);
+		return handle;
+	} };
+}
+//#endregion
+export { createTestContainer, createToken, setupAlloyTesting };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { GenericSpy, MockFnFactory, MockOf } from "./lib/mocking.js";
+import { CreateTestContainerOptions, FactoryOverrideSpec, OverrideSpec, TestContainerHandle, TestScopeHierarchy, createTestContainer } from "./lib/core.js";
+import { createToken } from "alloy-di/runtime";
+export { type CreateTestContainerOptions, type FactoryOverrideSpec, type GenericSpy, type MockFnFactory, type MockOf, type OverrideSpec, type TestContainerHandle, type TestScopeHierarchy, createTestContainer, createToken };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { createTestContainer } from "./lib/core.js";
+import { createToken } from "alloy-di/runtime";
+export { createTestContainer, createToken };

package/dist/lib/core.d.ts

@@ -0,0 +1,93 @@
+import { GenericSpy, MockFnFactory, MockOf } from "./mocking.js";
+import { Container, FactoryFn, Newable, ProviderDefinitions, ServiceIdentifier, ServiceScope, Token } from "alloy-di/runtime";
+import { Scope } from "alloy-di/scopes";
+
+//#region src/lib/core.d.ts
+type FactoryOverrideSpec<T = unknown> = [token: Token<T>, factory: FactoryFn<T>, options?: {
+  lifecycle?: ServiceScope;
+}];
+type TestScopeHierarchy = Record<string, {
+  parent?: ServiceScope;
+}>;
+interface OverrideSpec {
+  /** Class constructor instance overrides */
+  instances?: Array<[Newable<unknown>, unknown]>;
+  /** Token value overrides */
+  tokens?: Array<[Token<unknown>, unknown]>;
+  /**
+   * Token factory overrides. These are explicit token-keyed overrides and are
+   * not affected by autoMock, which only mocks class constructor dependencies.
+   * Token value overrides still take precedence for the same token.
+   */
+  factories?: FactoryOverrideSpec[];
+}
+interface CreateTestContainerOptions<S = GenericSpy> {
+  overrides?: OverrideSpec;
+  autoMock?: boolean;
+  target?: Newable<unknown>;
+  providers?: ProviderDefinitions | ProviderDefinitions[];
+  /** Custom scope hierarchy for tests, matching alloy({ scopes }) shape. */
+  scopes?: TestScopeHierarchy;
+  /**
+   * Factory used to create spies for auto-mocked methods. Required when
+   * `autoMock` is enabled. Runner adapters (e.g. `@alloy-di/testing/vitest`)
+   * pre-wire this to the runner's mock function.
+   */
+  mockFn?: MockFnFactory<S>;
+  /**
+   * Resets a single spy created by `mockFn`. Used by `clearMockSpies()`.
+   * Runner adapters pre-wire this to the runner's reset semantics.
+   */
+  resetFn?: (spy: S) => void;
+}
+interface TestContainerHandle<S = GenericSpy> {
+  container: Container;
+  get<T>(target: Newable<T> | ServiceIdentifier<T>): Promise<T>;
+  getIdentifier?<T>(ctor: Newable<T>): ServiceIdentifier<T>;
+  /** Retrieve a token value via a synthetic classless access */
+  getToken<T>(token: Token<T>): T;
+  /** Provide a token value into the container */
+  provideToken?<T>(token: Token<T>, value: T): void;
+  /** Provide a token factory into the container */
+  provideFactory?<T>(token: Token<T>, factory: FactoryFn<T>, options?: {
+    lifecycle?: ServiceScope;
+  }): void;
+  /** Alias for provideFactory when replacing an existing test factory. */
+  overrideFactory?<T>(token: Token<T>, factory: FactoryFn<T>, options?: {
+    lifecycle?: ServiceScope;
+  }): void;
+  /** Create a scope under the test container. */
+  createScope?(scopeName: ServiceScope): Scope;
+  /** Placeholder restore hook (future phases may implement overlay stacks). */
+  restore(): void;
+  /** Retrieve a single class mock (if autoMock enabled). */
+  getMock?<T>(ctor: Newable<T>): MockOf<T, S> | undefined;
+  /** Retrieve multiple class mocks preserving tuple order. */
+  getMocks?<T extends readonly Newable<unknown>[]>(ctors: T): { [K in keyof T]: T[K] extends Newable<infer I> ? MockOf<I, S> | undefined : never };
+  /** Convenience: get a specific method spy from a mock. */
+  spyOf?<T>(ctor: Newable<T>, method: Extract<keyof T, string>): S | undefined;
+  /** Convenience: reset all mock spies (requires a `resetFn` binding). */
+  clearMockSpies?(): void;
+}
+/**
+ * Create a test-focused container with manual overrides.
+ * - Auto-mocking, when enabled, only mocks class constructor dependencies and
+ *   requires a `mockFn` binding (supplied directly or by a runner adapter).
+ * - Token factories are explicit overrides and are applied after provider blocks.
+ */
+declare function createTestContainer<S = GenericSpy>(opts?: CreateTestContainerOptions<S> | OverrideSpec): TestContainerHandle<S> & {
+  getMock<T>(ctor: Newable<T>): MockOf<T, S> | undefined;
+  getMocks<T extends readonly Newable<unknown>[]>(ctors: T): { [K in keyof T]: T[K] extends Newable<infer I> ? MockOf<I, S> | undefined : never };
+  provideToken<T>(token: Token<T>, value: T): void;
+  provideFactory<T>(token: Token<T>, factory: FactoryFn<T>, options?: {
+    lifecycle?: ServiceScope;
+  }): void;
+  overrideFactory<T>(token: Token<T>, factory: FactoryFn<T>, options?: {
+    lifecycle?: ServiceScope;
+  }): void;
+  createScope(scopeName: ServiceScope): Scope;
+  spyOf<T>(ctor: Newable<T>, method: Extract<keyof T, string>): S | undefined;
+  clearMockSpies(): void;
+};
+//#endregion
+export { CreateTestContainerOptions, FactoryOverrideSpec, OverrideSpec, TestContainerHandle, TestScopeHierarchy, createTestContainer };

package/dist/lib/core.js

@@ -0,0 +1,85 @@
+import { restoreRegistry, snapshotRegistry } from "./registry.js";
+import { applyAutoMocks } from "./mocking.js";
+import { Container, applyProviders } from "alloy-di/runtime";
+import { createScope } from "alloy-di/scopes";
+//#region src/lib/core.ts
+function normalizeScopeHierarchy(scopes) {
+	const hierarchy = {};
+	for (const [scopeName, config] of Object.entries(scopes)) hierarchy[scopeName] = config.parent ?? "singleton";
+	return hierarchy;
+}
+/**
+* Create a test-focused container with manual overrides.
+* - Auto-mocking, when enabled, only mocks class constructor dependencies and
+*   requires a `mockFn` binding (supplied directly or by a runner adapter).
+* - Token factories are explicit overrides and are applied after provider blocks.
+*/
+function createTestContainer(opts) {
+	const isLegacy = !!opts && !("autoMock" in opts) && !("target" in opts) && !("overrides" in opts) && !("providers" in opts) && !("scopes" in opts);
+	const normalizedOpts = isLegacy ? { overrides: opts } : opts ?? {};
+	const overrides = normalizedOpts.overrides ?? (isLegacy ? opts : void 0);
+	const container = new Container();
+	const snapshot = snapshotRegistry();
+	if (normalizedOpts.scopes) container._registerScopeHierarchy(normalizeScopeHierarchy(normalizedOpts.scopes));
+	if (normalizedOpts.providers) applyProviders(container, normalizedOpts.providers);
+	for (const [tok, factory, options] of overrides?.factories ?? []) container.provideFactory(tok, factory, options);
+	for (const [tok, value] of overrides?.tokens ?? []) container.provideValue(tok, value);
+	const overriddenCtors = new Set(overrides?.instances?.map(([c]) => c) ?? []);
+	for (const [ctor, instance] of overrides?.instances ?? []) container.overrideInstance(ctor, instance);
+	const resetFn = normalizedOpts.resetFn;
+	let mocks;
+	let lazyPatches;
+	if (normalizedOpts.autoMock && normalizedOpts.target) {
+		if (!normalizedOpts.mockFn) throw new Error("createTestContainer: `autoMock` requires a `mockFn` factory. Use a runner adapter (e.g. `@alloy-di/testing/vitest`) or pass `mockFn` explicitly.");
+		const auto = applyAutoMocks({
+			target: normalizedOpts.target,
+			container,
+			overridesCtors: overriddenCtors,
+			mockFn: normalizedOpts.mockFn
+		});
+		mocks = auto.mocks;
+		lazyPatches = auto.lazyPatches;
+	}
+	return {
+		container,
+		get: (target) => typeof target === "symbol" ? container.getByIdentifier(target) : container.get(target),
+		getIdentifier: (ctor) => container.getIdentifier(ctor),
+		getToken: (token) => {
+			return container.getToken(token);
+		},
+		provideToken: (token, value) => {
+			container.provideValue(token, value);
+		},
+		provideFactory: (token, factory, options) => {
+			container.provideFactory(token, factory, options);
+		},
+		overrideFactory: (token, factory, options) => {
+			container.provideFactory(token, factory, options);
+		},
+		createScope: (scopeName) => {
+			return createScope(container, scopeName);
+		},
+		getMock: (ctor) => {
+			return mocks?.get(ctor) ?? void 0;
+		},
+		getMocks: (ctors) => {
+			return ctors.map((c) => mocks?.get(c));
+		},
+		spyOf: (ctor, method) => {
+			return (mocks?.get(ctor))?.spies[method];
+		},
+		clearMockSpies: () => {
+			if (!mocks || !resetFn) return;
+			for (const [, m] of mocks) {
+				const spies = m.spies;
+				for (const key of Object.keys(spies)) resetFn(spies[key]);
+			}
+		},
+		restore: () => {
+			for (const patch of lazyPatches ?? []) patch.lazy.importer = patch.originalImporter;
+			restoreRegistry(snapshot);
+		}
+	};
+}
+//#endregion
+export { createTestContainer };

package/dist/lib/mocking.d.ts

@@ -0,0 +1,23 @@
+import { Container, Newable } from "alloy-di/runtime";
+
+//#region src/lib/mocking.d.ts
+type MethodKeys<T> = { [K in keyof T]: T[K] extends ((...args: any[]) => any) ? K : never }[keyof T];
+/**
+ * The minimal shape the runner-neutral core relies on for a spy. Runner
+ * adapters supply richer spy types (e.g. Vitest's `Mock`) which flow through
+ * the generic `S` parameter, so callers keep full runner-specific typing.
+ */
+type GenericSpy = ((...args: any[]) => any) & {
+  mock?: {
+    calls: any[][];
+  };
+};
+/** Factory that produces a fresh spy function (e.g. `vi.fn`, `jest.fn`). */
+type MockFnFactory<S = GenericSpy> = () => S;
+/** Typed mock shape returned for class auto-mocking. */
+type MockOf<T, S = GenericSpy> = Partial<T> & {
+  /** Map of method name -> spy function */spies: Record<Extract<MethodKeys<T>, string>, S>; /** Original constructor reference for introspection */
+  __target: Newable<T>;
+};
+//#endregion
+export { GenericSpy, MockFnFactory, MockOf };

package/dist/lib/mocking.js

@@ -0,0 +1,105 @@
+import { getRawDependencies } from "./registry.js";
+import { isConstructor, isLazy } from "alloy-di/runtime";
+//#region src/lib/mocking.ts
+/** Create a lightweight auto-mock instance for a class constructor. */
+function mockClass(ctor, mockFn) {
+	const proto = ctor.prototype;
+	const spies = {};
+	const mockObj = {
+		spies,
+		__target: ctor
+	};
+	for (const key of Object.getOwnPropertyNames(proto)) {
+		if (key === "constructor") continue;
+		if (typeof proto[key] === "function") {
+			const fn = mockFn();
+			spies[key] = fn;
+			mockObj[key] = fn;
+		}
+	}
+	return {
+		target: ctor,
+		mock: mockObj
+	};
+}
+function collectDependencyGraph(target) {
+	const constructors = /* @__PURE__ */ new Set();
+	const lazyDependencies = [];
+	const queue = [target];
+	const visited = /* @__PURE__ */ new Set();
+	while (queue.length) {
+		const current = queue.shift();
+		if (!current || visited.has(current)) continue;
+		visited.add(current);
+		constructors.add(current);
+		const deps = getRawDependencies(current);
+		for (const dep of deps) {
+			if (isLazy(dep)) {
+				lazyDependencies.push({ lazy: dep });
+				continue;
+			}
+			if (isConstructor(dep)) queue.push(dep);
+		}
+	}
+	return {
+		constructors,
+		lazyDependencies
+	};
+}
+function createMocksForConstructors(constructors, target, overrides, mockFn) {
+	const mocks = /* @__PURE__ */ new Map();
+	for (const ctor of constructors) {
+		if (ctor === target) continue;
+		if (overrides.has(ctor)) continue;
+		const classMock = mockClass(ctor, mockFn);
+		mocks.set(ctor, classMock.mock);
+	}
+	return mocks;
+}
+function applyMocksToContainer(container, mocks) {
+	for (const [ctor, mock] of mocks.entries()) container.overrideInstance(ctor, mock);
+}
+function patchLazyDependencies(lazyDeps, mocks, overrides, mockFn) {
+	const patches = [];
+	for (const { lazy } of lazyDeps) {
+		const originalImporter = lazy.importer;
+		lazy.importer = async () => {
+			const realCtor = await originalImporter();
+			let mockObj = mocks.get(realCtor);
+			if (!overrides.has(realCtor) && !mockObj) {
+				mockObj = mockClass(realCtor, mockFn).mock;
+				mocks.set(realCtor, mockObj);
+			}
+			if (!mockObj) return realCtor;
+			return buildMockCtorFrom(realCtor, mockObj);
+		};
+		patches.push({
+			lazy,
+			originalImporter
+		});
+	}
+	return patches;
+}
+/** Traverse dependency graph (deep) and create class mocks, including lazy deps. */
+function applyAutoMocks(options) {
+	const { target, container, overridesCtors, mockFn } = options;
+	const graph = collectDependencyGraph(target);
+	const mocks = createMocksForConstructors(graph.constructors, target, overridesCtors, mockFn);
+	applyMocksToContainer(container, mocks);
+	return {
+		mocks,
+		lazyPatches: patchLazyDependencies(graph.lazyDependencies, mocks, overridesCtors, mockFn)
+	};
+}
+/** Build a class constructor that exposes spies from a mock object via prototype methods */
+function buildMockCtorFrom(realCtor, mock) {
+	function MockCtor() {}
+	const proto = realCtor.prototype;
+	for (const key of Object.getOwnPropertyNames(proto)) {
+		if (key === "constructor") continue;
+		if (typeof proto[key] === "function" && key in mock.spies) MockCtor.prototype[key] = mock.spies[key];
+	}
+	return MockCtor;
+}
+//#endregion
+export { applyAutoMocks };

package/dist/lib/registry.js

@@ -0,0 +1,17 @@
+import { dependenciesRegistry } from "alloy-di/runtime";
+//#region src/lib/registry.ts
+/** Take a deep(ish) snapshot of current dependency registry state. */
+function snapshotRegistry() {
+	return new Map(dependenciesRegistry);
+}
+/** Restore dependency registry from a prior snapshot. */
+function restoreRegistry(snapshot) {
+	dependenciesRegistry.clear();
+	for (const [k, v] of snapshot.entries()) dependenciesRegistry.set(k, v);
+}
+/** Get raw declared dependencies including constructors, Lazy and Tokens */
+function getRawDependencies(target) {
+	return (dependenciesRegistry.get(target)?.dependencies ?? (() => []))();
+}
+//#endregion
+export { getRawDependencies, restoreRegistry, snapshotRegistry };

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@alloy-di/testing",
+  "version": "0.1.0",
+  "description": "Runner-neutral test-container utilities for Alloy DI, with Vitest, Jest, and node:test adapters",
+  "keywords": [
+    "dependency-injection",
+    "di",
+    "jest",
+    "mocking",
+    "testing",
+    "typescript",
+    "vitest"
+  ],
+  "homepage": "https://alloy-di.dev",
+  "license": "MIT",
+  "author": "Mikael Selander",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ciddan/alloy-di/tree/main/packages/testing"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vitest": {
+      "types": "./dist/adapters/vitest.d.ts",
+      "import": "./dist/adapters/vitest.js"
+    },
+    "./jest": {
+      "types": "./dist/adapters/jest.d.ts",
+      "import": "./dist/adapters/jest.js"
+    },
+    "./node": {
+      "types": "./dist/adapters/node.d.ts",
+      "import": "./dist/adapters/node.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.26.0",
+    "@babel/preset-env": "^7.26.0",
+    "@babel/preset-typescript": "^7.26.0",
+    "@jest/globals": "^30.0.0",
+    "babel-jest": "^30.0.0",
+    "jest": "^30.0.0",
+    "jest-mock": "^30.0.0",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.1.0",
+    "rolldown-plugin-dts": "^0.25.2",
+    "tsx": "^4.22.4",
+    "vitest": "^4.1.8",
+    "alloy-di": "1.5.0"
+  },
+  "peerDependencies": {
+    "@jest/globals": ">=29.0.0",
+    "alloy-di": ">=1.5.0",
+    "typescript": ">=5.0.0",
+    "vitest": ">=4.0.14 <5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@jest/globals": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c",
+    "dev": "rolldown -c rolldown.config.ts --watch",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint --fix --type-aware --config ./.oxlintrc.json .",
+    "lint:check": "oxlint --type-aware --config ./.oxlintrc.json .",
+    "test": "vitest --run && pnpm test:node && pnpm test:jest",
+    "test:vitest": "vitest --run",
+    "test:node": "node --import tsx --test src/runner-tests/*.node.test.ts",
+    "test:jest": "node --experimental-vm-modules node_modules/jest/bin/jest.js --config jest.config.mjs",
+    "test:cover": "vitest --run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc -b . --noEmit"
+  }
+}