@fluojs/testing 1.0.0-beta.1

package/dist/conformance/platform-conformance.js

@@ -0,0 +1,193 @@
+const DEFAULT_FORBIDDEN_KEY_PATTERNS = [/secret/i, /password/i, /token/i, /credential/i, /api[-_]?key/i];
+const DEFAULT_REQUIRED_FIX_HINT_SEVERITIES = ['error'];
+function isRecord(value) {
+  return typeof value === 'object' && value !== null;
+}
+function normalizeForComparison(value) {
+  if (Array.isArray(value)) {
+    return value.map(entry => normalizeForComparison(entry));
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+  const normalizedEntries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, entry]) => [key, normalizeForComparison(entry)]);
+  return Object.fromEntries(normalizedEntries);
+}
+function defaultCompare(left, right) {
+  return JSON.stringify(normalizeForComparison(left)) === JSON.stringify(normalizeForComparison(right));
+}
+function toErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function captureOutcome(action) {
+  try {
+    await action();
+    return {
+      ok: true
+    };
+  } catch (error) {
+    return {
+      message: toErrorMessage(error),
+      ok: false
+    };
+  }
+}
+function collectForbiddenKeyPaths(value, patterns, allowPatterns, currentPath, violations) {
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => {
+      collectForbiddenKeyPaths(entry, patterns, allowPatterns, `${currentPath}[${index}]`, violations);
+    });
+    return;
+  }
+  if (!isRecord(value)) {
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    const nextPath = currentPath.length > 0 ? `${currentPath}.${key}` : key;
+    const isForbidden = patterns.some(pattern => pattern.test(key));
+    const isAllowed = allowPatterns.some(pattern => pattern.test(nextPath));
+    if (isForbidden && !isAllowed) {
+      violations.push(nextPath);
+    }
+    collectForbiddenKeyPaths(entry, patterns, allowPatterns, nextPath, violations);
+  }
+}
+export class PlatformConformanceHarness {
+  constructor(options) {
+    this.options = options;
+  }
+  async assertValidationHasNoLongLivedSideEffects() {
+    const component = this.options.createComponent();
+    const beforeState = component.state();
+    const beforeEffects = this.options.captureValidationSideEffects ? await this.options.captureValidationSideEffects(component) : undefined;
+    await component.validate();
+    const afterState = component.state();
+    if (beforeState !== afterState) {
+      throw new Error(`validate() must not transition component state. Expected "${beforeState}" but received "${afterState}".`);
+    }
+    if (!this.options.captureValidationSideEffects) {
+      return;
+    }
+    const compare = this.options.snapshot?.compare ?? defaultCompare;
+    const afterEffects = await this.options.captureValidationSideEffects(component);
+    if (!compare(beforeEffects, afterEffects)) {
+      throw new Error('validate() introduced long-lived side effects.');
+    }
+  }
+  async assertStartIsDeterministic() {
+    const component = this.options.createComponent();
+    const compare = this.options.snapshot?.compare ?? defaultCompare;
+    const firstStart = await captureOutcome(() => component.start());
+    const firstSnapshot = component.snapshot();
+    const secondStart = await captureOutcome(() => component.start());
+    const secondSnapshot = component.snapshot();
+    if (firstStart.ok !== secondStart.ok) {
+      throw new Error('start() is not deterministic: first and second calls had different outcomes.');
+    }
+    if (!firstStart.ok && !secondStart.ok && firstStart.message !== secondStart.message) {
+      throw new Error('start() rejection messages changed across duplicate calls.');
+    }
+    if (firstStart.ok && secondStart.ok && !compare(firstSnapshot, secondSnapshot)) {
+      throw new Error('start() is not idempotent: duplicate calls changed component snapshot output.');
+    }
+    await captureOutcome(() => component.stop());
+  }
+  async assertStopIsIdempotent() {
+    const component = this.options.createComponent();
+    const compare = this.options.snapshot?.compare ?? defaultCompare;
+    const startOutcome = await captureOutcome(() => component.start());
+    if (!startOutcome.ok) {
+      throw new Error(`stop() idempotency check requires a startable component: ${startOutcome.message}`);
+    }
+    const firstStop = await captureOutcome(() => component.stop());
+    if (!firstStop.ok) {
+      throw new Error(`first stop() call failed: ${firstStop.message}`);
+    }
+    const firstState = component.state();
+    const firstSnapshot = component.snapshot();
+    const secondStop = await captureOutcome(() => component.stop());
+    if (!secondStop.ok) {
+      throw new Error(`stop() is not idempotent: second call failed with "${secondStop.message}".`);
+    }
+    const secondState = component.state();
+    const secondSnapshot = component.snapshot();
+    if (firstState !== secondState) {
+      throw new Error(`stop() changed state across duplicate calls (${firstState} -> ${secondState}).`);
+    }
+    if (!compare(firstSnapshot, secondSnapshot)) {
+      throw new Error('stop() is not idempotent: duplicate calls changed component snapshot output.');
+    }
+  }
+  async assertSnapshotSafeInDegradedAndFailedStates() {
+    const scenarios = this.options.scenarios;
+    if (!scenarios) {
+      throw new Error('Conformance scenarios are required. Provide degraded and failed snapshot scenarios.');
+    }
+    for (const scenario of [scenarios.degraded, scenarios.failed]) {
+      const component = scenario.createComponent();
+      await scenario.enterState(component);
+      if (scenario.expectedState !== undefined && component.state() !== scenario.expectedState) {
+        throw new Error(`Scenario "${scenario.name}" expected state "${scenario.expectedState}" but received "${component.state()}".`);
+      }
+      try {
+        component.snapshot();
+      } catch (error) {
+        throw new Error(`snapshot() must be safe in "${scenario.name}" state: ${toErrorMessage(error)}`);
+      } finally {
+        await captureOutcome(() => component.stop());
+      }
+    }
+  }
+  async assertStableDiagnostics() {
+    const component = this.options.createComponent();
+    const validation = await component.validate();
+    const diagnostics = [...validation.issues, ...(validation.warnings ?? [])];
+    if (this.options.diagnostics?.collect) {
+      const extra = await this.options.diagnostics.collect(component, validation);
+      diagnostics.push(...extra);
+    }
+    const requiredFixHintSeverities = this.options.diagnostics?.requireFixHintForSeverities ?? DEFAULT_REQUIRED_FIX_HINT_SEVERITIES;
+    for (const issue of diagnostics) {
+      if (issue.code.trim().length === 0) {
+        throw new Error('Diagnostics must provide a stable non-empty code.');
+      }
+      if (requiredFixHintSeverities.includes(issue.severity) && (!issue.fixHint || issue.fixHint.trim().length === 0)) {
+        throw new Error(`Diagnostic ${issue.code} (${issue.severity}) must provide a fixHint.`);
+      }
+    }
+    const expectedCodes = this.options.diagnostics?.expectedCodes;
+    if (!expectedCodes) {
+      return;
+    }
+    const normalizeCodes = codes => [...new Set(codes)].sort();
+    const actualCodes = normalizeCodes(diagnostics.map(diagnostic => diagnostic.code));
+    const normalizedExpectedCodes = normalizeCodes(expectedCodes);
+    if (!defaultCompare(actualCodes, normalizedExpectedCodes)) {
+      throw new Error(`Diagnostic code set changed. Expected [${normalizedExpectedCodes.join(', ')}] but received [${actualCodes.join(', ')}].`);
+    }
+  }
+  async assertSnapshotSanitized() {
+    const component = this.options.createComponent();
+    const snapshot = component.snapshot();
+    const sanitize = this.options.snapshot?.sanitize;
+    const candidate = sanitize ? sanitize(snapshot) : snapshot;
+    const forbiddenPatterns = this.options.snapshot?.forbiddenKeyPatterns ?? DEFAULT_FORBIDDEN_KEY_PATTERNS;
+    const allowPatterns = this.options.snapshot?.allowKeyPatterns ?? [];
+    const violations = [];
+    collectForbiddenKeyPaths(candidate, forbiddenPatterns, allowPatterns, '', violations);
+    if (violations.length > 0) {
+      throw new Error(`snapshot() contains unsanitized keys: ${violations.join(', ')}`);
+    }
+  }
+  async assertAll() {
+    await this.assertValidationHasNoLongLivedSideEffects();
+    await this.assertStartIsDeterministic();
+    await this.assertStopIsIdempotent();
+    await this.assertSnapshotSafeInDegradedAndFailedStates();
+    await this.assertStableDiagnostics();
+    await this.assertSnapshotSanitized();
+  }
+}
+export function createPlatformConformanceHarness(options) {
+  return new PlatformConformanceHarness(options);
+}

package/dist/http.d.ts

@@ -0,0 +1,73 @@
+import type { Dispatcher, Middleware } from '@fluojs/http';
+/**
+ * Principal payload used by testing request helpers.
+ */
+export interface TestPrincipal {
+    subject?: string;
+    issuer?: string;
+    audience?: string | string[];
+    roles?: string[];
+    scopes?: string[];
+    claims?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Minimal request input shape accepted by testing request helpers.
+ */
+export interface TestRequest {
+    method?: string;
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, string | string[]>;
+    principal?: TestPrincipal;
+}
+/**
+ * Normalized test request shape used internally by dispatch helpers.
+ */
+export interface TestRequestWithOptions extends TestRequest {
+    principal?: TestPrincipal;
+}
+/**
+ * Serialized test response returned by helper dispatch calls.
+ */
+export interface TestResponse {
+    status: number;
+    body: unknown;
+    headers: Record<string, string | string[]>;
+}
+/**
+ * Fluent builder for constructing and dispatching test requests.
+ */
+export interface RequestBuilder {
+    method(value: string): RequestBuilder;
+    path(value: string): RequestBuilder;
+    body(value: unknown): RequestBuilder;
+    header(name: string, value: string): RequestBuilder;
+    query(key: string, value: string | string[]): RequestBuilder;
+    principal(value: TestPrincipal): RequestBuilder;
+    send(): Promise<TestResponse>;
+}
+/**
+ * Creates a fluent request builder around a dispatcher.
+ *
+ * @param dispatcher Dispatcher that should execute the synthetic request.
+ * @param request Initial request state for the fluent builder.
+ * @returns A builder that can mutate the request before dispatching it.
+ */
+export declare function createRequestBuilder(dispatcher: Dispatcher, request: TestRequestWithOptions): RequestBuilder;
+/**
+ * Middleware that maps test-request principal data into `RequestContext.principal`.
+ *
+ * @returns Middleware that injects synthetic principal data before the next handler runs.
+ */
+export declare function createTestRequestContextMiddleware(): Middleware;
+/**
+ * Dispatches one synthetic request through a Fluo dispatcher and captures the serialized response.
+ *
+ * @param dispatcher Dispatcher that should handle the request.
+ * @param req Normalized synthetic request payload.
+ * @returns The captured status, body, and headers produced by the dispatcher.
+ */
+export declare function makeRequest(dispatcher: Dispatcher, req: TestRequestWithOptions): Promise<TestResponse>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAmD,UAAU,EAAa,MAAM,cAAc,CAAC;AAEvH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACzD,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC;IACtC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC;IACpC,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAAC;IACrC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC;IACpD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,cAAc,CAAC;IAC7D,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CAAC;IAChD,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;CAC/B;AA2ED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,sBAAsB,GAAG,cAAc,CAqD5G;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,IAAI,UAAU,CAa/D;AAuFD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC,CAO5G"}

package/dist/http.js

@@ -0,0 +1,239 @@
+/**
+ * Principal payload used by testing request helpers.
+ */
+
+/**
+ * Minimal request input shape accepted by testing request helpers.
+ */
+
+/**
+ * Normalized test request shape used internally by dispatch helpers.
+ */
+
+/**
+ * Serialized test response returned by helper dispatch calls.
+ */
+
+/**
+ * Fluent builder for constructing and dispatching test requests.
+ */
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null;
+}
+function toRecord(value) {
+  if (isRecord(value)) {
+    return value;
+  }
+  return {};
+}
+function normalizePrincipal(principal) {
+  if (!principal) {
+    return undefined;
+  }
+  const {
+    subject,
+    issuer,
+    audience,
+    roles,
+    scopes,
+    claims: principalClaims,
+    ...additionalClaims
+  } = principal;
+  const subjectValue = typeof subject === 'string' ? subject : typeof additionalClaims.id === 'string' ? String(additionalClaims.id) : 'test';
+  const normalizedClaims = {
+    subject: subjectValue,
+    audience,
+    claims: {
+      ...toRecord(principalClaims),
+      ...additionalClaims
+    }
+  };
+  if (issuer !== undefined) {
+    normalizedClaims.issuer = issuer;
+  }
+  if (roles !== undefined) {
+    normalizedClaims.roles = roles;
+  }
+  if (scopes !== undefined) {
+    normalizedClaims.scopes = scopes;
+  }
+  return normalizedClaims;
+}
+
+/**
+ * Creates a fluent request builder around a dispatcher.
+ *
+ * @param dispatcher Dispatcher that should execute the synthetic request.
+ * @param request Initial request state for the fluent builder.
+ * @returns A builder that can mutate the request before dispatching it.
+ */
+export function createRequestBuilder(dispatcher, request) {
+  let current = {
+    method: request.method,
+    path: request.path,
+    body: request.body,
+    headers: request.headers ? {
+      ...request.headers
+    } : undefined,
+    query: request.query ? {
+      ...request.query
+    } : undefined,
+    principal: request.principal
+  };
+  return {
+    method(value) {
+      current = {
+        ...current,
+        method: value
+      };
+      return this;
+    },
+    path(value) {
+      current = {
+        ...current,
+        path: value
+      };
+      return this;
+    },
+    body(value) {
+      current = {
+        ...current,
+        body: value
+      };
+      return this;
+    },
+    header(name, value) {
+      current = {
+        ...current,
+        headers: {
+          ...(current.headers ?? {}),
+          [name]: value
+        }
+      };
+      return this;
+    },
+    query(key, value) {
+      current = {
+        ...current,
+        query: {
+          ...(current.query ?? {}),
+          [key]: value
+        }
+      };
+      return this;
+    },
+    principal(value) {
+      current = {
+        ...current,
+        principal: value
+      };
+      return this;
+    },
+    async send() {
+      return makeRequest(dispatcher, current);
+    }
+  };
+}
+
+/**
+ * Middleware that maps test-request principal data into `RequestContext.principal`.
+ *
+ * @returns Middleware that injects synthetic principal data before the next handler runs.
+ */
+export function createTestRequestContextMiddleware() {
+  return {
+    async handle(context, next) {
+      const request = context.request;
+      const principal = normalizePrincipal(request.principal);
+      if (principal !== undefined) {
+        context.requestContext.principal = principal;
+      }
+      await next();
+    }
+  };
+}
+function buildFrameworkRequest(req) {
+  const method = (req.method ?? 'GET').toUpperCase();
+  const queryString = req.query ? `?${new URLSearchParams(Object.entries(req.query).flatMap(([key, value]) => Array.isArray(value) ? value.map(v => [key, v]) : [[key, value]])).toString()}` : '';
+  return {
+    method,
+    path: req.path,
+    url: req.path + queryString,
+    headers: req.headers ?? {},
+    query: req.query ?? {},
+    cookies: {},
+    params: {},
+    body: req.body,
+    raw: req,
+    principal: req.principal
+  };
+}
+function buildFrameworkResponse() {
+  const result = {
+    status: 200,
+    body: undefined,
+    headers: {}
+  };
+  const mergeHeaderValue = (current, incoming) => {
+    const nextValues = Array.isArray(incoming) ? incoming : [incoming];
+    if (current === undefined) {
+      return nextValues.length === 1 ? nextValues[0] : [...nextValues];
+    }
+    const currentValues = Array.isArray(current) ? current : [current];
+    const merged = [...currentValues, ...nextValues];
+    return merged.length === 1 ? merged[0] : merged;
+  };
+  const response = {
+    statusCode: undefined,
+    headers: {},
+    committed: false,
+    setStatus(code) {
+      result.status = code;
+      this.statusCode = code;
+      this.statusSet = true;
+    },
+    setHeader(name, value) {
+      const lowerName = name.toLowerCase();
+      const responseHeaders = this.headers;
+      if (lowerName === 'set-cookie') {
+        result.headers[name] = mergeHeaderValue(result.headers[name], value);
+        responseHeaders[name] = mergeHeaderValue(responseHeaders[name], value);
+        return;
+      }
+      result.headers[name] = value;
+      responseHeaders[name] = value;
+    },
+    redirect(status, location) {
+      this.setStatus(status);
+      this.setHeader('location', location);
+      this.committed = true;
+    },
+    async send(body) {
+      result.body = body;
+      this.committed = true;
+    },
+    statusSet: false
+  };
+  return {
+    response,
+    result
+  };
+}
+
+/**
+ * Dispatches one synthetic request through a Fluo dispatcher and captures the serialized response.
+ *
+ * @param dispatcher Dispatcher that should handle the request.
+ * @param req Normalized synthetic request payload.
+ * @returns The captured status, body, and headers produced by the dispatcher.
+ */
+export async function makeRequest(dispatcher, req) {
+  const frameworkRequest = buildFrameworkRequest(req);
+  const {
+    response,
+    result
+  } = buildFrameworkResponse();
+  await dispatcher.dispatch(frameworkRequest, response);
+  return result;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './app.js';
+export { Test, createTestingModule, extractModuleProviders, extractModuleControllers, extractModuleImports } from './module.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAChI,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './app.js';
+export { Test, createTestingModule, extractModuleProviders, extractModuleControllers, extractModuleImports } from './module.js';
+export * from './types.js';

package/dist/mock.d.ts

@@ -0,0 +1,26 @@
+import type { Mock } from 'vitest';
+import type { Token } from '@fluojs/core';
+import type { ValueProvider } from '@fluojs/di';
+import type { DeepMocked } from './types.js';
+export type MockedMethods<T> = {
+    [K in keyof T]: T[K] extends (...args: never[]) => unknown ? Mock<T[K]> : T[K];
+};
+/**
+ * Creates a proxy mock object with optional strict missing-property checks.
+ */
+export declare function createMock<T extends object>(partial?: Partial<MockedMethods<T>>, options?: {
+    strict?: boolean;
+}): MockedMethods<T>;
+/**
+ * Casts a function to a strongly typed Vitest mock.
+ */
+export declare function asMock<T extends (...args: never[]) => unknown>(fn: T): Mock<T>;
+/**
+ * Creates a deep mock by replacing prototype methods with `vi.fn()` spies.
+ */
+export declare function createDeepMock<T extends object>(type: new (...args: unknown[]) => T): DeepMocked<T>;
+/**
+ * Creates a `useValue` provider for overriding a token in tests.
+ */
+export declare function mockToken<T>(token: Token<T>, partial?: Partial<T>): ValueProvider<T>;
+//# sourceMappingURL=mock.d.ts.map

package/dist/mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../src/mock.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEnC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;KAC5B,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAC/E,CAAC;AAEF;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,OAAO,GAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAM,EACvC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,aAAa,CAAC,CAAC,CAAC,CAsBlB;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAE9E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAkBnG;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,OAAO,CAAC,CAAC,CAAM,GAAG,aAAa,CAAC,CAAC,CAAC,CAExF"}

package/dist/mock.js

@@ -0,0 +1,60 @@
+import { vi } from 'vitest';
+/**
+ * Creates a proxy mock object with optional strict missing-property checks.
+ */
+export function createMock(partial = {}, options = {}) {
+  const autoMocks = new Map();
+  return new Proxy({
+    ...partial
+  }, {
+    get(target, prop, receiver) {
+      if (Reflect.has(target, prop)) {
+        return Reflect.get(target, prop, receiver);
+      }
+      if (options.strict) {
+        throw new Error(`createMock: strict mode — property "${String(prop)}" is not declared in the partial mock. Add it to the partial or disable strict mode.`);
+      }
+      if (!autoMocks.has(prop)) {
+        autoMocks.set(prop, vi.fn());
+      }
+      return autoMocks.get(prop);
+    }
+  });
+}
+
+/**
+ * Casts a function to a strongly typed Vitest mock.
+ */
+export function asMock(fn) {
+  return vi.mocked(fn);
+}
+
+/**
+ * Creates a deep mock by replacing prototype methods with `vi.fn()` spies.
+ */
+export function createDeepMock(type) {
+  const spies = {};
+  let proto = type.prototype;
+  while (proto !== null && proto !== Object.prototype) {
+    for (const key of Reflect.ownKeys(proto)) {
+      if (key === 'constructor') continue;
+      if (key in spies) continue;
+      const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+      if (descriptor && typeof descriptor.value === 'function') {
+        spies[key] = vi.fn();
+      }
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+  return spies;
+}
+
+/**
+ * Creates a `useValue` provider for overriding a token in tests.
+ */
+export function mockToken(token, partial = {}) {
+  return {
+    provide: token,
+    useValue: partial
+  };
+}

package/dist/module.d.ts

@@ -0,0 +1,45 @@
+import { type ClassType, type Provider } from '@fluojs/di';
+import type { ModuleType } from '@fluojs/runtime';
+import type { TestingModuleBuilder, TestingModuleOptions } from './types.js';
+/**
+ * Returns providers declared on a module metadata definition.
+ *
+ * @param moduleType Module type whose `providers` metadata should be inspected.
+ * @returns The declared provider list, or an empty array when the module has none.
+ */
+export declare function extractModuleProviders(moduleType: ModuleType): Provider[];
+/**
+ * Returns controllers declared on a module metadata definition.
+ *
+ * @param moduleType Module type whose `controllers` metadata should be inspected.
+ * @returns The declared controller list, or an empty array when the module has none.
+ */
+export declare function extractModuleControllers(moduleType: ModuleType): ClassType[];
+/**
+ * Returns imported modules declared on a module metadata definition.
+ *
+ * @param moduleType Module type whose `imports` metadata should be inspected.
+ * @returns The declared import list, or an empty array when the module has none.
+ */
+export declare function extractModuleImports(moduleType: ModuleType): ModuleType[];
+/**
+ * Creates a fluent testing-module builder for overriding providers and compiling a test graph.
+ *
+ * @param options Bootstrap options plus the root module that should be compiled for the test.
+ * @returns A builder that supports provider and module overrides before compilation.
+ *
+ * @example
+ * ```ts
+ * const module = await createTestingModule({ rootModule: AppModule })
+ *   .overrideProvider(USER_REPOSITORY, fakeUserRepository)
+ *   .compile();
+ * ```
+ */
+export declare function createTestingModule(options: TestingModuleOptions): TestingModuleBuilder;
+/**
+ * Namespace-style access point for `createTestingModule(...)`.
+ */
+export declare const Test: {
+    createTestingModule: typeof createTestingModule;
+};
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,SAAS,EAId,KAAK,QAAQ,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAqC,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMrF,OAAO,KAAK,EAA2B,oBAAoB,EAAE,oBAAoB,EAAoB,MAAM,YAAY,CAAC;AAExH;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,UAAU,GAAG,QAAQ,EAAE,CAQzE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,EAAE,CAQ5E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,EAAE,CAQzE;AAiaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CAEvF;AAED;;GAEG;AACH,eAAO,MAAM,IAAI;;CAEhB,CAAC"}