@onebun/core 0.2.9 → 0.2.11

package/src/testing/docs-examples.test.ts

@@ -0,0 +1,280 @@
+/**
+ * Documentation Examples Tests for @onebun/core testing utilities
+ *
+ * This file tests code examples from:
+ * - docs/testing.md
+ */
+
+import {
+  describe,
+  expect,
+  it,
+} from 'bun:test';
+
+import type { CompiledTestingModule } from './testing-module';
+
+import {
+  Controller,
+  Get,
+  Param,
+} from '../decorators/decorators';
+import { Controller as BaseController } from '../module/controller';
+import { BaseService, Service } from '../module/service';
+
+import { createTestController, createTestService } from './service-helpers';
+import {
+  createMockConfig,
+  createMockLogger,
+  useFakeTimers,
+} from './test-utils';
+import { TestingModule } from './testing-module';
+
+// ============================================================================
+// Test fixtures
+// ============================================================================
+
+@Service()
+class UserService extends BaseService {
+  findById(id: string): { id: string; name: string } {
+    return { id, name: `User ${id}` };
+  }
+}
+
+@Service()
+class ServiceWithConfig extends BaseService {
+  getDbUrl(): unknown {
+    return this.config.get('database.url');
+  }
+}
+
+@Service()
+class ServiceWithDeps extends BaseService {
+  constructor(private readonly repo: { find: () => string }) {
+    super();
+  }
+
+  getData(): string {
+    return this.repo.find();
+  }
+}
+
+@Controller('/users')
+class UserController extends BaseController {
+  constructor(private readonly userService: UserService) {
+    super();
+  }
+
+  @Get('/:id')
+  getUser(@Param('id') id: string) {
+    return this.userService.findById(id);
+  }
+}
+
+// ============================================================================
+// createTestService — docs/testing.md
+// ============================================================================
+
+describe('docs/testing.md — createTestService', () => {
+  /**
+   * @source docs/testing.md#createtestservice
+   */
+  it('basic usage — creates service with mock logger and config', () => {
+    const { instance, logger, config } = createTestService(UserService);
+
+    const result = instance.findById('123');
+
+    expect(result).toEqual({ id: '123', name: 'User 123' });
+    expect(logger).toBeDefined();
+    expect(config).toBeDefined();
+    expect(config.isInitialized).toBe(true);
+  });
+
+  /**
+   * @source docs/testing.md#with-config-and-dependencies
+   */
+  it('with config — config.get returns provided values', () => {
+    const { instance } = createTestService(ServiceWithConfig, {
+      /* eslint-disable @typescript-eslint/naming-convention */
+      config: { 'database.url': 'postgres://localhost/test' },
+      /* eslint-enable @typescript-eslint/naming-convention */
+    });
+
+    expect(instance.getDbUrl()).toBe('postgres://localhost/test');
+  });
+
+  /**
+   * @source docs/testing.md#with-config-and-dependencies
+   */
+  it('with deps — passes constructor dependencies', () => {
+    const mockRepo = { find: () => 'mock-data' };
+    const { instance } = createTestService(ServiceWithDeps, {
+      deps: [mockRepo],
+    });
+
+    expect(instance.getData()).toBe('mock-data');
+  });
+});
+
+// ============================================================================
+// createTestController — docs/testing.md
+// ============================================================================
+
+describe('docs/testing.md — createTestController', () => {
+  /**
+   * @source docs/testing.md#createtestcontroller
+   */
+  it('basic usage — creates controller with mock logger and config', () => {
+    const mockUserService = { findById: (id: string) => ({ id, name: 'Mock' }) };
+    const { instance, logger, config } = createTestController(UserController, {
+      deps: [mockUserService],
+    });
+
+    expect(instance).toBeInstanceOf(UserController);
+    expect(logger).toBeDefined();
+    expect(config).toBeDefined();
+  });
+});
+
+// ============================================================================
+// TestingModule — docs/testing.md
+// ============================================================================
+
+describe('docs/testing.md — TestingModule', () => {
+  /**
+   * @source docs/testing.md#basic-usage-1
+   */
+  it('basic compile / inject / close flow', async () => {
+    let module: CompiledTestingModule | undefined;
+
+    try {
+      module = await TestingModule
+        .create({
+          controllers: [UserController],
+          providers: [UserService],
+        })
+        .compile();
+
+      const response = await module.inject('GET', '/users/42');
+
+      expect(response.status).toBe(200);
+
+      const body = await response.json() as { result: { id: string; name: string } };
+      expect(body.result.id).toBe('42');
+      expect(body.result.name).toBe('User 42');
+    } finally {
+      await module?.close();
+    }
+  });
+
+  /**
+   * @source docs/testing.md#overrideproviderserviceclass
+   */
+  it('overrideProvider — replaces service with mock value', async () => {
+    const mockUser = { id: '1', name: 'MockUser' };
+    let module: CompiledTestingModule | undefined;
+
+    try {
+      module = await TestingModule
+        .create({ controllers: [UserController], providers: [UserService] })
+        .overrideProvider(UserService).useValue({ findById: () => mockUser })
+        .compile();
+
+      const response = await module.inject('GET', '/users/1');
+
+      expect(response.status).toBe(200);
+
+      const body = await response.json() as { result: { id: string; name: string } };
+      expect(body.result.name).toBe('MockUser');
+    } finally {
+      await module?.close();
+    }
+  });
+
+  /**
+   * @source docs/testing.md#setoptionsoptions
+   */
+  it('setOptions — applies basePath to routes', async () => {
+    let module: CompiledTestingModule | undefined;
+
+    try {
+      module = await TestingModule
+        .create({ controllers: [UserController], providers: [UserService] })
+        .setOptions({ basePath: '/api' })
+        .compile();
+
+      const response = await module.inject('GET', '/api/users/1');
+
+      expect(response.status).toBe(200);
+    } finally {
+      await module?.close();
+    }
+  });
+});
+
+// ============================================================================
+// useFakeTimers — docs/testing.md
+// ============================================================================
+
+describe('docs/testing.md — useFakeTimers', () => {
+  /**
+   * @source docs/testing.md#usefaketimers
+   */
+  it('basic usage — advance time and trigger setTimeout', () => {
+    const timers = useFakeTimers();
+
+    try {
+      let called = false;
+      setTimeout(() => {
+        called = true;
+      }, 1000);
+
+      timers.advanceTime(999);
+      expect(called).toBe(false);
+
+      timers.advanceTime(1);
+      expect(called).toBe(true);
+    } finally {
+      timers.restore();
+    }
+  });
+});
+
+// ============================================================================
+// createMockLogger — docs/testing.md
+// ============================================================================
+
+describe('docs/testing.md — createMockLogger', () => {
+  /**
+   * @source docs/testing.md#createmocklogger
+   */
+  it('basic usage — creates silent async logger', () => {
+    const logger = createMockLogger();
+
+    expect(logger).toBeDefined();
+    expect(typeof logger.info).toBe('function');
+    expect(typeof logger.child).toBe('function');
+    expect(logger.child({ context: 'test' })).toBe(logger);
+  });
+});
+
+// ============================================================================
+// createMockConfig — docs/testing.md
+// ============================================================================
+
+describe('docs/testing.md — createMockConfig', () => {
+  /**
+   * @source docs/testing.md#createmockconfig
+   */
+  it('basic usage — returns values from provided map', () => {
+    const config = createMockConfig({
+      /* eslint-disable @typescript-eslint/naming-convention */
+      'server.port': 3000,
+      'server.host': '0.0.0.0',
+      /* eslint-enable @typescript-eslint/naming-convention */
+    });
+
+    expect(config.get('server.port')).toBe(3000);
+    expect(config.get('server.host')).toBe('0.0.0.0');
+    expect(config.isInitialized).toBe(true);
+  });
+});

package/src/testing/index.ts

@@ -4,5 +4,7 @@
  * Helpers for testing OneBun applications.
  */
 
+export * from './containers';
+export * from './service-helpers';
 export * from './test-utils';
 export * from './testing-module';

package/src/testing/service-helpers.test.ts

@@ -0,0 +1,166 @@
+import {
+  describe,
+  expect,
+  mock,
+  test,
+} from 'bun:test';
+
+import { Controller } from '../decorators/decorators';
+import { Controller as BaseController } from '../module/controller';
+import { BaseService, Service } from '../module/service';
+
+import { createTestController, createTestService } from './service-helpers';
+
+// ============================================================================
+// Test fixtures
+// ============================================================================
+
+@Service()
+class TestService extends BaseService {
+  getValue(): string {
+    return 'service-value';
+  }
+}
+
+@Service()
+class ServiceWithDeps extends BaseService {
+  constructor(private readonly dep: { name: string }) {
+    super();
+  }
+
+  getDep(): string {
+    return this.dep.name;
+  }
+}
+
+@Controller('/test')
+class TestController extends BaseController {
+  handle(): string {
+    return 'controller-value';
+  }
+}
+
+@Controller('/test-deps')
+class ControllerWithDeps extends BaseController {
+  constructor(private readonly dep: { name: string }) {
+    super();
+  }
+
+  getDep(): string {
+    return this.dep.name;
+  }
+}
+
+// ============================================================================
+// createTestService
+// ============================================================================
+
+describe('createTestService', () => {
+  test('creates service instance with mock logger and config', () => {
+    const { instance, logger, config } = createTestService(TestService);
+
+    expect(instance).toBeInstanceOf(TestService);
+    expect(instance.getValue()).toBe('service-value');
+    expect(logger).toBeDefined();
+    expect(config).toBeDefined();
+    expect(config.isInitialized).toBe(true);
+  });
+
+  test('config.get returns provided config values', () => {
+    const { config } = createTestService(TestService, {
+      /* eslint-disable @typescript-eslint/naming-convention */
+      config: { 'app.name': 'my-app', 'server.port': 3000 },
+      /* eslint-enable @typescript-eslint/naming-convention */
+    });
+
+    expect(config.get('app.name')).toBe('my-app');
+    expect(config.get('server.port')).toBe(3000);
+  });
+
+  test('passes constructor dependencies', () => {
+    const { instance } = createTestService(ServiceWithDeps, {
+      deps: [{ name: 'test-dep' }],
+    });
+
+    expect(instance.getDep()).toBe('test-dep');
+  });
+
+  test('logger methods are mock functions with .mock.calls', () => {
+    const { logger } = createTestService(TestService);
+
+    // initializeService calls logger.child() and then debug() internally,
+    // so we track calls made after initialization
+    const debugCallsBefore = (logger.debug as ReturnType<typeof mock>).mock.calls.length;
+
+    logger.info('test message');
+    logger.warn('warning');
+    logger.debug('debug');
+
+    expect((logger.info as ReturnType<typeof mock>).mock.calls).toHaveLength(1);
+    expect((logger.warn as ReturnType<typeof mock>).mock.calls).toHaveLength(1);
+    expect((logger.debug as ReturnType<typeof mock>).mock.calls.length - debugCallsBefore).toBe(1);
+    expect((logger.error as ReturnType<typeof mock>).mock.calls).toHaveLength(0);
+    expect((logger.trace as ReturnType<typeof mock>).mock.calls).toHaveLength(0);
+    expect((logger.fatal as ReturnType<typeof mock>).mock.calls).toHaveLength(0);
+  });
+
+  test('initializes service via initializeService', () => {
+    const { instance } = createTestService(TestService);
+
+    // After initializeService, the service should have logger and config set
+    // We verify this indirectly — the service was created and initialized without errors
+    expect(instance).toBeInstanceOf(TestService);
+  });
+});
+
+// ============================================================================
+// createTestController
+// ============================================================================
+
+describe('createTestController', () => {
+  test('creates controller instance with mock logger and config', () => {
+    const { instance, logger, config } = createTestController(TestController);
+
+    expect(instance).toBeInstanceOf(TestController);
+    expect(instance.handle()).toBe('controller-value');
+    expect(logger).toBeDefined();
+    expect(config).toBeDefined();
+    expect(config.isInitialized).toBe(true);
+  });
+
+  test('config.get returns provided config values', () => {
+    const { config } = createTestController(TestController, {
+      /* eslint-disable @typescript-eslint/naming-convention */
+      config: { 'app.name': 'my-app', 'server.port': 3000 },
+      /* eslint-enable @typescript-eslint/naming-convention */
+    });
+
+    expect(config.get('app.name')).toBe('my-app');
+    expect(config.get('server.port')).toBe(3000);
+  });
+
+  test('passes constructor dependencies', () => {
+    const { instance } = createTestController(ControllerWithDeps, {
+      deps: [{ name: 'test-dep' }],
+    });
+
+    expect(instance.getDep()).toBe('test-dep');
+  });
+
+  test('logger methods are mock functions with .mock.calls', () => {
+    const { logger } = createTestController(TestController);
+
+    logger.info('test message');
+    logger.error('error');
+
+    expect((logger.info as ReturnType<typeof mock>).mock.calls).toHaveLength(1);
+    expect((logger.error as ReturnType<typeof mock>).mock.calls).toHaveLength(1);
+    expect((logger.warn as ReturnType<typeof mock>).mock.calls).toHaveLength(0);
+  });
+
+  test('initializes controller via initializeController', () => {
+    const { instance } = createTestController(TestController);
+
+    expect(instance).toBeInstanceOf(TestController);
+  });
+});

package/src/testing/service-helpers.ts

@@ -0,0 +1,69 @@
+import { mock } from 'bun:test';
+
+import type { IConfig, OneBunAppConfig } from '../module/config.interface';
+
+import type { SyncLogger } from '@onebun/logger';
+
+
+import { createMockConfig } from './test-utils';
+
+export interface TestInstanceResult<T> {
+  instance: T;
+  logger: SyncLogger;
+  config: IConfig<OneBunAppConfig>;
+}
+
+interface CreateTestOptions {
+  config?: Record<string, unknown>;
+  deps?: unknown[];
+}
+
+function createMockableSyncLogger(): SyncLogger {
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  const noOp = () => {};
+  const logger: SyncLogger = {
+    trace: mock(noOp),
+    debug: mock(noOp),
+    info: mock(noOp),
+    warn: mock(noOp),
+    error: mock(noOp),
+    fatal: mock(noOp),
+    child: mock(() => logger),
+  };
+
+  return logger;
+}
+
+export function createTestService<T>(
+  serviceClass: new (...args: never[]) => T,
+  options?: CreateTestOptions,
+): TestInstanceResult<T> {
+  const logger = createMockableSyncLogger();
+  const config = createMockConfig(options?.config ?? {});
+  const deps = options?.deps ?? [];
+
+  const instance = new serviceClass(...deps as never[]);
+
+  if (typeof (instance as Record<string, unknown>).initializeService === 'function') {
+    (instance as Record<string, (...args: unknown[]) => void>).initializeService(logger, config);
+  }
+
+  return { instance, logger, config };
+}
+
+export function createTestController<T>(
+  controllerClass: new (...args: never[]) => T,
+  options?: CreateTestOptions,
+): TestInstanceResult<T> {
+  const logger = createMockableSyncLogger();
+  const config = createMockConfig(options?.config ?? {});
+  const deps = options?.deps ?? [];
+
+  const instance = new controllerClass(...deps as never[]);
+
+  if (typeof (instance as Record<string, unknown>).initializeController === 'function') {
+    (instance as Record<string, (...args: unknown[]) => void>).initializeController(logger, config);
+  }
+
+  return { instance, logger, config };
+}

package/src/testing/testing-module.test.ts

@@ -6,6 +6,7 @@ import {
   it,
 } from 'bun:test';
 
+import { OneBunApplication } from '../application/application';
 import {
   Controller,
   Get,
@@ -17,6 +18,7 @@ import {
 import { Controller as BaseController } from '../module/controller';
 import { BaseService, Service } from '../module/service';
 
+
 import { TestingModule, type CompiledTestingModule } from './testing-module';
 
 // ============================================================================
@@ -146,6 +148,84 @@ describe('TestingModule', () => {
     });
   });
 
+  describe('setOptions()', () => {
+    it('passes options to the application', async () => {
+      const module = await TestingModule
+        .create({
+          controllers: [GreetController],
+          providers: [GreetingService],
+        })
+        .setOptions({ basePath: '/api' })
+        .compile();
+
+      try {
+        // Without basePath prefix the route should not match
+        const notFound = await module.inject('GET', '/greet/world');
+        expect(notFound.status).toBe(404);
+
+        // With basePath prefix the route should match
+        const found = await module.inject('GET', '/api/greet/world');
+        expect(found.status).toBe(200);
+      } finally {
+        await module.close();
+      }
+    });
+  });
+
+  describe('getApp()', () => {
+    it('returns an OneBunApplication instance', async () => {
+      const module = await TestingModule
+        .create({
+          controllers: [GreetController],
+          providers: [GreetingService],
+        })
+        .compile();
+
+      try {
+        expect(module.getApp()).toBeInstanceOf(OneBunApplication);
+      } finally {
+        await module.close();
+      }
+    });
+  });
+
+  describe('getPort()', () => {
+    it('returns a port greater than 0', async () => {
+      const module = await TestingModule
+        .create({
+          controllers: [GreetController],
+          providers: [GreetingService],
+        })
+        .compile();
+
+      try {
+        expect(module.getPort()).toBeGreaterThan(0);
+      } finally {
+        await module.close();
+      }
+    });
+  });
+
+  describe('getConfig()', () => {
+    it('returns config object when envSchema is provided', async () => {
+      const module = await TestingModule
+        .create({
+          controllers: [GreetController],
+          providers: [GreetingService],
+        })
+        .setOptions({ envSchema: {} })
+        .compile();
+
+      try {
+        const config = module.getConfig();
+        expect(config).toBeDefined();
+        expect(typeof config.get).toBe('function');
+      } finally {
+        await module.close();
+      }
+    });
+  });
+
   describe('overrideProvider()', () => {
     it('useValue() replaces service so controller uses mock', async () => {
       const mockService = {

package/src/testing/testing-module.ts

@@ -17,7 +17,12 @@
  */
 
 import type { OneBunApplication } from '../application/application';
-import type { HttpMethod, OneBunResponse } from '../types';
+import type { IConfig, OneBunAppConfig } from '../module/config.interface';
+import type {
+  ApplicationOptions,
+  HttpMethod,
+  OneBunResponse,
+} from '../types';
 import type { Context } from 'effect';
 
 import { Module } from '../decorators/decorators';
@@ -123,6 +128,31 @@ export class CompiledTestingModule {
     }) as OneBunResponse;
   }
 
+  /**
+   * Get the underlying OneBunApplication instance.
+   * Useful for accessing application-level APIs not exposed by the testing module.
+   */
+  getApp(): OneBunApplication {
+    return this.app;
+  }
+
+  /**
+   * Get the port the test server is listening on.
+   */
+  getPort(): number {
+    return this.port;
+  }
+
+  /**
+   * Get the application configuration.
+   * Requires `envSchema` to be set via `setOptions()`.
+   *
+   * @throws If configuration was not initialized (no envSchema provided)
+   */
+  getConfig(): IConfig<OneBunAppConfig> {
+    return this.app.getConfig();
+  }
+
   /**
    * Stop the test server and release resources.
    * Call this in `afterEach` / `afterAll` to prevent port leaks.
@@ -176,6 +206,7 @@ export class TestingModule {
     tag: Context.Tag<any, any>;
     value: unknown;
   }> = [];
+  private appOptions: Partial<ApplicationOptions> = {};
 
   private constructor(options: TestingModuleCreateOptions) {
     this.options = options;
@@ -190,6 +221,19 @@ export class TestingModule {
     return new TestingModule(options);
   }
 
+  /**
+   * Set additional application options (e.g. envSchema, cors, basePath).
+   * Options are merged into the application config. `gracefulShutdown` and
+   * `_testProviders` are always forced by the testing module.
+   *
+   * @param options - Partial application options to merge
+   */
+  setOptions(options: Partial<ApplicationOptions>): TestingModule {
+    this.appOptions = options;
+
+    return this;
+  }
+
   /**
    * Override a provider with a mock value or class.
    * Overrides are applied before `setup()` so controllers receive mocks at construction time.
@@ -239,8 +283,9 @@ export class TestingModule {
     // - silent logger
     // - test provider overrides injected before setup()
     const app = new OneBunApplication(_TestingAppModule, {
-      port: 0,
       loggerLayer: makeMockLoggerLayer() as import('effect').Layer.Layer<import('@onebun/logger').Logger>,
+      port: 0,
+      ...this.appOptions,
       gracefulShutdown: false,
       _testProviders: this.overrides,
     });