@navios/core 0.7.1 → 0.9.0

package/src/testing/testing-module.mts

@@ -1,15 +1,21 @@
-import type { ClassType, ClassTypeWithInstance, InjectionToken } from '@navios/di'
-import type { NaviosModule } from '../interfaces/index.mjs'
-import type { NaviosApplicationOptions } from '../navios.application.mjs'
+import type {
+  ClassType,
+  ClassTypeWithInstance,
+  InjectionToken,
+  ScopedContainer,
+} from '@navios/di'
 
 import { TestContainer } from '@navios/di/testing'
 
+import type { NaviosModule } from '../interfaces/index.mjs'
+import type { NaviosApplicationOptions } from '../navios.application.mjs'
+
 import { NaviosApplication } from '../navios.application.mjs'
 import { NaviosFactory } from '../navios.factory.mjs'
 
 /**
  * Configuration for overriding a provider in the testing module.
- * 
+ *
  * @typeParam T - The type of the provider being overridden
  */
 export interface TestingModuleOverride<T = any> {
@@ -29,68 +35,139 @@ export interface TestingModuleOverride<T = any> {
 
 /**
  * Options for creating a testing module.
- * 
+ *
  * Extends NaviosApplicationOptions but excludes the container option,
  * as TestingModule manages its own TestContainer.
  */
-export interface TestingModuleOptions
-  extends Omit<NaviosApplicationOptions, 'container'> {
+export interface TestingModuleOptions extends Omit<
+  NaviosApplicationOptions,
+  'container'
+> {
   /**
    * Initial provider overrides to apply when creating the testing module.
-   * 
+   *
    * You can also use `overrideProvider()` method for a fluent API.
    */
   overrides?: TestingModuleOverride[]
+  /**
+   * Container to use for the testing module.
+   * If not provided, a new TestContainer will be created.
+   */
+  container?: TestContainer
 }
 
 /**
  * A testing-optimized wrapper around NaviosApplication.
  * Provides utilities for setting up test environments with mock dependencies.
+ *
+ * When `init()` is called, a request scope is automatically started.
+ * This means `get()` calls will resolve request-scoped services correctly,
+ * simulating a real HTTP request context.
+ *
+ * @example
+ * ```typescript
+ * const module = await TestingModule.create(AppModule)
+ *   .overrideProvider(DatabaseService)
+ *   .useValue(mockDatabase)
+ *   .init()
+ *
+ * const userService = await module.get(UserService)
+ * // ... run tests ...
+ *
+ * await module.close()
+ * ```
  */
 export class TestingModule {
   private app: NaviosApplication | null = null
+  private scopedContainer: ScopedContainer | null = null
+  private requestId = `test-request-${Date.now()}-${Math.random().toString(36).slice(2)}`
 
-  constructor(
+  private constructor(
     private readonly appModule: ClassTypeWithInstance<NaviosModule>,
     private readonly container: TestContainer,
     private readonly options: TestingModuleOptions,
   ) {}
 
   /**
-   * Compiles the testing module and returns the NaviosApplication.
-   * Call this after setting up all overrides.
+   * Creates a new TestingModule for the given app module.
+   * This is the main entry point for setting up integration tests.
+   *
+   * @example
+   * ```typescript
+   * const module = await TestingModule.create(AppModule)
+   *   .overrideProvider(DatabaseService)
+   *   .useValue(mockDatabase)
+   *   .init()
+   * ```
    */
-  async compile(): Promise<NaviosApplication> {
-    this.app = await NaviosFactory.create(this.appModule, {
-      ...this.options,
-      container: this.container,
-    })
-    return this.app
+  static create(
+    appModule: ClassTypeWithInstance<NaviosModule>,
+    options: TestingModuleOptions = { adapter: [] },
+  ): TestingModule {
+    const container =
+      options.container ??
+      new TestContainer({
+        parentRegistry: options.registry,
+      })
+
+    // Apply initial overrides if provided
+    if (options.overrides) {
+      for (const override of options.overrides) {
+        if (override.useValue !== undefined) {
+          container.bind(override.token as any).toValue(override.useValue)
+        } else if (override.useClass) {
+          container.bind(override.token as any).toClass(override.useClass)
+        }
+      }
+    }
+
+    return new TestingModule(appModule, container, options)
   }
 
   /**
-   * Initializes the application (loads modules, sets up HTTP if configured).
-   * This is equivalent to calling app.init() on the compiled application.
+   * Compiles the testing module without initializing it.
+   * Call this if you need to access the app before initialization.
+   *
+   * @returns this for chaining
    */
-  async init(): Promise<NaviosApplication> {
+  async compile(): Promise<this> {
     if (!this.app) {
-      await this.compile()
+      this.app = await NaviosFactory.create(this.appModule, {
+        ...this.options,
+        container: this.container,
+      })
     }
-    await this.app!.init()
-    return this.app!
+    return this
   }
 
   /**
-   * Gets the underlying TestContainer for direct manipulation.
+   * Initializes the application and starts a request scope.
+   *
+   * This is equivalent to calling `compile()` followed by `app.init()`,
+   * plus starting a request context for proper request-scoped service resolution.
+   *
+   * @returns this for chaining
    */
-  getContainer(): TestContainer {
-    return this.container
+  async init(): Promise<this> {
+    if (!this.app) {
+      await this.compile()
+    }
+    await this.app!.init()
+
+    // Begin a request scope so get() can resolve request-scoped services
+    this.scopedContainer = this.container.beginRequest(this.requestId, {
+      testingModule: true,
+    })
+
+    return this
   }
 
   /**
-   * Gets the compiled application. Throws if not yet compiled.
+   * Gets the compiled application.
+   *
+   * @throws Error if the module has not been compiled yet
    */
-  getApplication(): NaviosApplication {
+  getApp(): NaviosApplication {
     if (!this.app) {
       throw new Error(
         'TestingModule not compiled. Call compile() or init() first.',
@@ -100,7 +177,28 @@ export class TestingModule {
   }
 
   /**
-   * Override a provider with a mock value.
+   * Gets the underlying TestContainer for direct manipulation.
+   */
+  getContainer(): TestContainer {
+    return this.container
+  }
+
+  /**
+   * Gets the scoped container for the current test request.
+   * Only available after calling `init()`.
+   *
+   * @throws Error if init() has not been called
+   */
+  getScopedContainer(): ScopedContainer {
+    if (!this.scopedContainer) {
+      throw new Error('No scoped container available. Call init() first.')
+    }
+    return this.scopedContainer
+  }
+
+  /**
+   * Override a provider with a mock value or class.
+   * Must be called before `compile()` or `init()`.
    */
   overrideProvider<T>(token: ClassType | InjectionToken<T, any>): {
     useValue: (value: T) => TestingModule
@@ -120,112 +218,176 @@ export class TestingModule {
 
   /**
    * Gets an instance from the container.
+   *
+   * If `init()` has been called, this uses the scoped container
+   * which properly resolves request-scoped services.
+   *
+   * If only `compile()` was called, this uses the root container
+   * and request-scoped services will throw.
    */
-  async get<T>(token: ClassTypeWithInstance<T> | InjectionToken<T, any>): Promise<T> {
+  async get<T>(
+    token: ClassTypeWithInstance<T> | InjectionToken<T, any>,
+  ): Promise<T> {
+    // Use scoped container if available (after init)
+    if (this.scopedContainer) {
+      return this.scopedContainer.get(token as any)
+    }
+    // Fall back to root container (after compile only)
     return this.container.get(token as any)
   }
 
   /**
-   * Disposes the testing module and cleans up resources.
+   * Disposes the testing module and cleans up all resources.
+   *
+   * This will:
+   * 1. End the request scope (if started)
+   * 2. Close the application (if initialized)
+   * 3. Dispose the container
    */
   async close(): Promise<void> {
+    // End the request scope first
+    if (this.scopedContainer) {
+      await this.scopedContainer.endRequest()
+      this.scopedContainer = null
+    }
+
+    // Close the app
     if (this.app) {
       await this.app.close()
+      this.app = null
     }
+
+    // Dispose the container
     await this.container.dispose()
   }
-}
 
-/**
- * Fluent builder interface for TestingModule.
- * 
- * Provides a chainable API for configuring and using a testing module.
- */
-export interface TestingModuleBuilder {
+  // ===========================================================================
+  // ASSERTION HELPERS (delegated to TestContainer)
+  // ===========================================================================
+
   /**
-   * Override a provider with a mock value or class.
-   * 
-   * @param token - The injection token or class to override
-   * @returns An object with `useValue` and `useClass` methods for chaining
-   * 
-   * @example
-   * ```typescript
-   * const testingModule = await createTestingModule(AppModule)
-   *   .overrideProvider(DatabaseService)
-   *   .useValue(mockDatabaseService)
-   *   .compile()
-   * ```
+   * Asserts that a service has been resolved at least once.
    */
-  overrideProvider<T>(token: ClassType | InjectionToken<T, any>): {
-    useValue: (value: T) => TestingModuleBuilder
-    useClass: (target: ClassType) => TestingModuleBuilder
+  expectResolved(token: ClassType | InjectionToken<any, any>): void {
+    this.container.expectResolved(token)
   }
 
   /**
-   * Compiles the testing module and returns the NaviosApplication.
-   * 
-   * This creates the application instance but does not initialize it.
-   * Call `init()` if you need the application to be fully initialized.
+   * Asserts that a service has NOT been resolved.
    */
-  compile(): Promise<NaviosApplication>
+  expectNotResolved(token: ClassType | InjectionToken<any, any>): void {
+    this.container.expectNotResolved(token)
+  }
 
   /**
-   * Initializes the application (loads modules, sets up HTTP if configured).
-   * 
-   * This is equivalent to calling `compile()` followed by `app.init()`.
+   * Asserts that a service is registered as singleton scope.
    */
-  init(): Promise<NaviosApplication>
+  expectSingleton(token: ClassType | InjectionToken<any, any>): void {
+    this.container.expectSingleton(token)
+  }
 
   /**
-   * Gets the underlying TestContainer for direct manipulation.
+   * Asserts that a service is registered as transient scope.
    */
-  getContainer(): TestContainer
+  expectTransient(token: ClassType | InjectionToken<any, any>): void {
+    this.container.expectTransient(token)
+  }
 
   /**
-   * Gets an instance from the container.
-   * 
-   * @typeParam T - The type of the instance to retrieve
-   * @param token - The injection token or class
-   * @returns The resolved instance
+   * Asserts that a service is registered as request scope.
+   */
+  expectRequestScoped(token: ClassType | InjectionToken<any, any>): void {
+    this.container.expectRequestScoped(token)
+  }
+
+  /**
+   * Asserts that a method was called on a service.
+   * Note: You must use `recordMethodCall()` in your mocks for this to work.
+   */
+  expectCalled(
+    token: ClassType | InjectionToken<any, any>,
+    method: string,
+  ): void {
+    this.container.expectCalled(token, method)
+  }
+
+  /**
+   * Asserts that a method was called with specific arguments.
+   * Note: You must use `recordMethodCall()` in your mocks for this to work.
+   */
+  expectCalledWith(
+    token: ClassType | InjectionToken<any, any>,
+    method: string,
+    expectedArgs: unknown[],
+  ): void {
+    this.container.expectCalledWith(token, method, expectedArgs)
+  }
+
+  /**
+   * Asserts that a method was called a specific number of times.
+   * Note: You must use `recordMethodCall()` in your mocks for this to work.
+   */
+  expectCallCount(
+    token: ClassType | InjectionToken<any, any>,
+    method: string,
+    count: number,
+  ): void {
+    this.container.expectCallCount(token, method, count)
+  }
+
+  /**
+   * Records a method call for tracking.
+   * Call this from your mock implementations to enable call assertions.
+   */
+  recordMethodCall(
+    token: ClassType | InjectionToken<any, any>,
+    method: string,
+    args: unknown[],
+    result?: unknown,
+    error?: Error,
+  ): void {
+    this.container.recordMethodCall(token, method, args, result, error)
+  }
+
+  /**
+   * Gets all recorded method calls for a service.
    */
-  get<T>(token: ClassTypeWithInstance<T> | InjectionToken<T, any>): Promise<T>
+  getMethodCalls(token: ClassType | InjectionToken<any, any>) {
+    return this.container.getMethodCalls(token)
+  }
 
   /**
-   * Disposes the testing module and cleans up resources.
+   * Gets the dependency graph for debugging or snapshot testing.
    */
-  close(): Promise<void>
+  getDependencyGraph() {
+    return this.container.getDependencyGraph()
+  }
+
+  /**
+   * Gets a simplified dependency graph showing only token relationships.
+   */
+  getSimplifiedDependencyGraph() {
+    return this.container.getSimplifiedDependencyGraph()
+  }
 }
 
 /**
  * Creates a testing module for the given app module.
- * This is the main entry point for setting up tests.
+ *
+ * @deprecated Use `TestingModule.create()` instead.
  *
  * @example
  * ```typescript
- * const testingModule = await createTestingModule(AppModule, {
- *   adapter: [],
- * })
- *   .overrideProvider(DatabaseService)
- *   .useValue(mockDatabaseService)
- *   .compile()
+ * // Old way (deprecated)
+ * const module = createTestingModule(AppModule)
+ *
+ * // New way
+ * const module = TestingModule.create(AppModule)
  * ```
  */
 export function createTestingModule(
   appModule: ClassTypeWithInstance<NaviosModule>,
   options: TestingModuleOptions = { adapter: [] },
 ): TestingModule {
-  const container = new TestContainer()
-
-  // Apply initial overrides if provided
-  if (options.overrides) {
-    for (const override of options.overrides) {
-      if (override.useValue !== undefined) {
-        container.bind(override.token as any).toValue(override.useValue)
-      } else if (override.useClass) {
-        container.bind(override.token as any).toClass(override.useClass)
-      }
-    }
-  }
-
-  return new TestingModule(appModule, container, options)
+  return TestingModule.create(appModule, options)
 }