@stratal/testing 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,332 @@
+# @stratal/testing
+
+Testing utilities and mocks for [Stratal](https://github.com/strataljs/stratal) framework applications.
+
+[![npm version](https://img.shields.io/npm/v/@stratal/testing)](https://www.npmjs.com/package/@stratal/testing)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+npm install -D @stratal/testing
+# or
+yarn add -D @stratal/testing
+```
+
+### Peer dependencies
+
+```bash
+npm install -D stratal vitest
+```
+
+## Quick Start
+
+Set up base modules once in your Vitest setup file, then create test modules in each test:
+
+```typescript
+// vitest.setup.ts
+import 'reflect-metadata'
+import { Test } from '@stratal/testing'
+import { CoreModule } from './src/core.module'
+
+Test.setBaseModules([CoreModule])
+```
+
+```typescript
+// users/__tests__/users.spec.ts
+import { Test, type TestingModule } from '@stratal/testing'
+import { UsersModule } from '../users.module'
+
+describe('UsersController', () => {
+  let module: TestingModule
+
+  beforeAll(async () => {
+    module = await Test.createTestingModule({
+      imports: [UsersModule],
+    }).compile()
+  })
+
+  afterAll(async () => {
+    await module.close()
+  })
+
+  it('lists users', async () => {
+    const response = await module.http
+      .get('/api/users')
+      .send()
+
+    response.assertOk()
+  })
+})
+```
+
+## Core API
+
+### `Test`
+
+Static entry point for creating testing modules.
+
+```typescript
+import { Test } from '@stratal/testing'
+
+// Set once in vitest.setup.ts — included in every test module
+Test.setBaseModules([CoreModule])
+
+// Create a test module in each test file
+const builder = Test.createTestingModule({
+  imports: [UsersModule, AuthModule],
+  providers: [{ provide: MOCK_TOKEN, useValue: mockValue }],
+  controllers: [TestController],
+  env: { DATABASE_URL: 'test://db' },
+})
+```
+
+### `TestingModuleBuilder`
+
+Fluent builder returned by `Test.createTestingModule()`. Chain provider overrides, then call `.compile()`.
+
+```typescript
+const module = await Test.createTestingModule({
+  imports: [OrdersModule],
+})
+  .overrideProvider(PAYMENT_TOKEN)
+  .useValue(mockPaymentService)
+  .withEnv({ STRIPE_KEY: 'sk_test_xxx' })
+  .compile()
+```
+
+### `TestingModule`
+
+The compiled test context. Provides access to services, HTTP client, storage, and lifecycle management.
+
+```typescript
+// Resolve services from the DI container
+const service = module.get(ORDER_TOKENS.OrderService)
+
+// Access the HTTP test client
+module.http
+
+// Access fake storage for assertions
+module.storage
+
+// Execute code in a request-scoped container
+await module.runInRequestScope(async () => {
+  const scoped = module.get(REQUEST_SCOPED_TOKEN)
+})
+
+// Cleanup in afterAll
+await module.close()
+```
+
+## HTTP Testing
+
+The built-in HTTP client provides a fluent API for making requests and asserting responses.
+
+### Making requests
+
+```typescript
+const response = await module.http
+  .forHost('api.example.com')  // optional — defaults to localhost
+  .post('/api/v1/orders')
+  .withHeaders({ Authorization: 'Bearer token' })
+  .withBody({ item: 'Widget', qty: 3 })
+  .send()
+```
+
+All HTTP methods are supported: `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`.
+
+### Response assertions
+
+```typescript
+response
+  .assertCreated()               // 201
+  .assertHeader('Content-Type', 'application/json')
+
+// Status helpers
+response.assertOk()              // 200
+response.assertNoContent()       // 204
+response.assertBadRequest()      // 400
+response.assertUnauthorized()    // 401
+response.assertForbidden()       // 403
+response.assertNotFound()        // 404
+response.assertUnprocessable()   // 422
+response.assertServerError()     // 500
+response.assertStatus(418)       // any status
+response.assertSuccessful()      // 2xx range
+
+// JSON assertions (async — chainable with await)
+await response.assertJson({ success: true })
+await response.assertJsonPath('data.user.id', expect.any(String))
+await response.assertJsonPaths({ 'data.name': 'Alice', 'data.role': 'admin' })
+await response.assertJsonStructure(['id', 'name', 'email'])
+await response.assertJsonPathExists('data.createdAt')
+await response.assertJsonPathMissing('data.password')
+await response.assertJsonPathCount('data.items', 3)
+await response.assertJsonPathContains('data.bio', 'engineer')
+await response.assertJsonPathIncludes('data.tags', 'featured')
+
+// Header assertions
+response.assertHeader('X-Request-Id')        // exists
+response.assertHeader('X-Request-Id', '123') // exact value
+response.assertHeaderMissing('X-Debug')
+
+// Raw access
+const json = await response.json<OrderResponse>()
+const text = await response.text()
+response.status   // number
+response.headers  // Headers
+response.raw      // underlying Response
+```
+
+## Provider Overrides
+
+Replace any provider in the DI container for testing:
+
+```typescript
+const module = await Test.createTestingModule({
+  imports: [NotificationModule],
+})
+  // Static value
+  .overrideProvider(EMAIL_TOKEN)
+  .useValue(mockEmailService)
+
+  // Class replacement
+  .overrideProvider(LOGGER_TOKEN)
+  .useClass(SilentLogger)
+
+  // Factory with container access
+  .overrideProvider(CACHE_TOKEN)
+  .useFactory((container) => new InMemoryCache(container.resolve(CONFIG_TOKEN)))
+
+  // Alias to existing token
+  .overrideProvider(PAYMENT_TOKEN)
+  .useExisting(MOCK_PAYMENT_TOKEN)
+
+  .compile()
+```
+
+## Fetch Mocking
+
+Mock external HTTP calls with `createFetchMock()`, backed by [undici MockAgent](https://undici.nodejs.org/#/docs/api/MockAgent):
+
+```typescript
+import { createFetchMock, type FetchMock } from '@stratal/testing'
+
+describe('GeoService', () => {
+  let module: TestingModule
+  let fetchMock: FetchMock
+
+  beforeEach(() => {
+    fetchMock = createFetchMock()
+    fetchMock.activate()
+    fetchMock.disableNetConnect()
+  })
+
+  afterEach(() => {
+    fetchMock.reset()
+  })
+
+  it('looks up coordinates', async () => {
+    fetchMock.mockJsonResponse('https://geo.api.com/lookup', {
+      lat: 40.7128,
+      lng: -74.006,
+    })
+
+    const response = await module.http
+      .get('/api/geo/lookup?address=NYC')
+      .send()
+
+    response.assertOk()
+    await response.assertJsonPath('data.lat', 40.7128)
+    fetchMock.assertNoPendingInterceptors()
+  })
+
+  it('handles API errors', async () => {
+    fetchMock.mockError('https://geo.api.com/lookup', 503, 'Service Unavailable')
+
+    const response = await module.http
+      .get('/api/geo/lookup?address=NYC')
+      .send()
+
+    response.assertServerError()
+  })
+})
+```
+
+For advanced scenarios, access the undici `MockPool` directly:
+
+```typescript
+fetchMock
+  .get('https://api.example.com')
+  .intercept({ path: '/users', method: 'POST' })
+  .reply(201, { id: '1' })
+```
+
+## Storage Testing
+
+`FakeStorageService` is an in-memory storage implementation auto-registered in every test module. It replaces the real storage service and provides assertion helpers.
+
+```typescript
+it('uploads a document', async () => {
+  await module.http
+    .post('/api/documents')
+    .withBody({ name: 'report.pdf' })
+    .send()
+
+  // Assert files were stored
+  module.storage.assertExists('documents/report.pdf')
+  module.storage.assertMissing('documents/old.pdf')
+  module.storage.assertCount(1)
+
+  // Inspect stored files
+  const file = module.storage.getFile('documents/report.pdf')
+  expect(file?.mimeType).toBe('application/pdf')
+  expect(file?.size).toBeGreaterThan(0)
+})
+
+afterEach(() => {
+  module.storage.clear() // reset between tests
+})
+```
+
+## Deep Mocking
+
+Create deeply-mocked instances of any interface or class with `createMock()` from [`@golevelup/ts-vitest`](https://github.com/golevelup/nestjs/tree/master/packages/ts-vitest):
+
+```typescript
+import { createMock, type DeepMocked } from '@stratal/testing/mocks'
+
+let mockService: DeepMocked<PaymentService>
+
+beforeEach(() => {
+  mockService = createMock<PaymentService>()
+  mockService.charge.mockResolvedValue({ id: 'ch_123', status: 'paid' })
+})
+```
+
+### Nodemailer mock
+
+A drop-in mock for nodemailer, useful in Vitest's module mocking:
+
+```typescript
+// vitest.config.ts (or inline vi.mock)
+export default defineConfig({
+  test: {
+    alias: {
+      nodemailer: '@stratal/testing/mocks/nodemailer',
+    },
+  },
+})
+```
+
+## Sub-path Exports
+
+```typescript
+import { Test, TestingModule, createFetchMock } from '@stratal/testing'
+import { createMock, type DeepMocked } from '@stratal/testing/mocks'
+import nodemailer from '@stratal/testing/mocks/nodemailer'
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stratal/testing",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Testing utilities and mocks for Stratal framework applications",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,7 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "yarn prebuild && tsc -p tsconfig.build.json",
     "clean": "rm -rf dist",
     "prebuild": "yarn clean",
     "typecheck": "tsc --noEmit",
@@ -51,19 +51,19 @@
     "lint:fix": "npx eslint --fix ."
   },
   "dependencies": {
-    "@faker-js/faker": "^9.7.0",
-    "@golevelup/ts-vitest": "^2.1.1"
+    "@faker-js/faker": "^10.3.0",
+    "@golevelup/ts-vitest": "^2.2.0"
   },
   "peerDependencies": {
-    "stratal": "^0.0.1",
+    "stratal": "^0.0.2",
     "vitest": "^3.2.0"
   },
   "devDependencies": {
-    "@cloudflare/vitest-pool-workers": "^0.9.0",
-    "@cloudflare/workers-types": "^4.20251121.0",
-    "@types/node": "^24.10.0",
+    "@cloudflare/vitest-pool-workers": "^0.12.18",
+    "@cloudflare/workers-types": "4.20260228.1",
+    "@types/node": "^25.3.2",
     "stratal": "workspace:*",
-    "typescript": "^5.8.3",
-    "vitest": "^3.2.0"
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
   }
 }

package/dist/core/env/index.d.ts

@@ -1,2 +0,0 @@
-export { getTestEnv } from './test-env';
-//# sourceMappingURL=index.d.ts.map

package/dist/core/env/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/env/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/core/env/index.js

@@ -1,2 +0,0 @@
-export { getTestEnv } from './test-env';
-//# sourceMappingURL=index.js.map

package/dist/core/env/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/env/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/core/env/test-env.d.ts

@@ -1,9 +0,0 @@
-import { type StratalEnv } from 'stratal';
-/**
- * Get test environment with optional overrides
- *
- * @param overrides - Optional partial env to merge with cloudflare:test env
- * @returns Complete Env object for testing
- */
-export declare function getTestEnv(overrides?: Partial<StratalEnv>): StratalEnv;
-//# sourceMappingURL=test-env.d.ts.map

package/dist/core/env/test-env.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"test-env.d.ts","sourceRoot":"","sources":["../../../src/core/env/test-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,SAAS,CAAA;AAGzC;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAKtE"}

package/dist/core/env/test-env.js

@@ -1,14 +0,0 @@
-import { env as cloudflareEnv } from 'cloudflare:test';
-/**
- * Get test environment with optional overrides
- *
- * @param overrides - Optional partial env to merge with cloudflare:test env
- * @returns Complete Env object for testing
- */
-export function getTestEnv(overrides) {
-    return {
-        ...cloudflareEnv,
-        ...overrides,
-    };
-}
-//# sourceMappingURL=test-env.js.map

package/dist/core/env/test-env.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"test-env.js","sourceRoot":"","sources":["../../../src/core/env/test-env.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,SAA+B;IACxD,OAAO;QACL,GAAG,aAAa;QAChB,GAAG,SAAS;KACC,CAAA;AACjB,CAAC"}

package/dist/core/http/fetch-mock.d.ts

@@ -1,236 +0,0 @@
-import type { MockJsonOptions, MockErrorOptions } from './fetch-mock.types';
-/**
- * Wrapper around Cloudflare's fetchMock for declarative fetch mocking in tests
- *
- * Based on undici's MockAgent, fetchMock.get(origin) returns a MockPool for that origin.
- * The MockPool's intercept() method is used to define which requests to mock.
- *
- * @example
- * ```typescript
- * import { createFetchMock } from '@stratal/testing'
- *
- * const mock = createFetchMock()
- *
- * beforeEach(() => {
- *   mock.activate()
- *   mock.disableNetConnect()
- * })
- *
- * afterEach(() => {
- *   mock.reset()
- * })
- *
- * it('should mock external API', async () => {
- *   // Using helper method
- *   mock.mockJsonResponse('https://api.example.com/data', { success: true })
- *
- *   // Or using direct API
- *   mock.get('https://api.example.com')
- *     .intercept({ path: '/users', method: 'POST' })
- *     .reply(201, JSON.stringify({ created: true }))
- *
- *   const response = await fetch('https://api.example.com/data')
- *   const json = await response.json()
- *
- *   expect(json.success).toBe(true)
- *   mock.assertNoPendingInterceptors()
- * })
- * ```
- */
-export declare class FetchMock {
-    /**
-     * Get a MockPool for the specified origin
-     *
-     * This is the underlying fetchMock.get() method that returns a MockPool
-     * for mocking requests to the specified origin.
-     *
-     * @param origin - The origin URL (e.g., 'https://api.example.com')
-     * @returns MockPool for chaining .intercept() and .reply()
-     *
-     * @example
-     * ```typescript
-     * // Mock a GET request
-     * mock.get('https://api.example.com')
-     *   .intercept({ path: '/users', method: 'GET' })
-     *   .reply(200, JSON.stringify({ users: [] }))
-     *
-     * // Mock a POST request with body matching
-     * mock.get('https://api.example.com')
-     *   .intercept({
-     *     path: '/users',
-     *     method: 'POST',
-     *     body: (body) => body.includes('test')
-     *   })
-     *   .reply(201, JSON.stringify({ created: true }))
-     * ```
-     */
-    get(origin: string): import("cloudflare:test").Interceptable;
-    /**
-     * Activate fetch mocking for the current test
-     *
-     * @example
-     * ```typescript
-     * beforeEach(() => {
-     *   mock.activate()
-     * })
-     * ```
-     */
-    activate(): void;
-    /**
-     * Deactivate fetch mocking
-     */
-    deactivate(): void;
-    /**
-     * Disable all network connections, forcing all requests to use mocks
-     *
-     * @example
-     * ```typescript
-     * beforeEach(() => {
-     *   mock.activate()
-     *   mock.disableNetConnect() // Ensure all requests are mocked
-     * })
-     * ```
-     */
-    disableNetConnect(): void;
-    /**
-     * Enable network connections for specific hosts
-     *
-     * @example
-     * ```typescript
-     * mock.enableNetConnect('localhost')
-     * mock.enableNetConnect(/^https:\/\/trusted\.com/)
-     * ```
-     */
-    enableNetConnect(host?: string | RegExp): void;
-    /**
-     * Assert that all defined interceptors were called
-     *
-     * @throws {Error} If there are pending interceptors that weren't matched
-     *
-     * @example
-     * ```typescript
-     * it('should call all mocked endpoints', async () => {
-     *   mock.mockJsonResponse('https://api.example.com/data', { data: [] })
-     *
-     *   await fetch('https://api.example.com/data')
-     *
-     *   mock.assertNoPendingInterceptors() // Pass
-     * })
-     * ```
-     */
-    assertNoPendingInterceptors(): void;
-    /**
-     * Reset all mocks and interceptors
-     *
-     * @example
-     * ```typescript
-     * afterEach(() => {
-     *   mock.reset()
-     * })
-     * ```
-     */
-    reset(): void;
-    /**
-     * Helper method to mock JSON responses
-     *
-     * Automatically parses the URL into origin and path, and sets up the mock.
-     *
-     * @param url - Full URL to mock (e.g., 'https://api.example.com/users')
-     * @param data - JSON data to return
-     * @param options - Additional options for the mock
-     *
-     * @example
-     * ```typescript
-     * // Mock a GET request
-     * mock.mockJsonResponse('https://api.example.com/users', { users: [] })
-     *
-     * // Mock a POST request
-     * mock.mockJsonResponse(
-     *   'https://api.example.com/users',
-     *   { created: true },
-     *   { method: 'POST', status: 201 }
-     * )
-     *
-     * // With custom headers and delay
-     * mock.mockJsonResponse(
-     *   'https://api.example.com/users',
-     *   { users: [] },
-     *   {
-     *     status: 200,
-     *     method: 'GET',
-     *     headers: { 'X-Custom': 'value' },
-     *     delay: 100
-     *   }
-     * )
-     * ```
-     */
-    mockJsonResponse(url: string, data: unknown, options?: MockJsonOptions): import("cloudflare:test").MockScope<object>;
-    /**
-     * Helper method to mock error responses
-     *
-     * @param url - Full URL to mock
-     * @param status - HTTP error status code
-     * @param message - Optional error message
-     * @param options - Additional options for the error mock
-     *
-     * @example
-     * ```typescript
-     * // Mock a 401 error
-     * mock.mockError('https://api.example.com/fail', 401, 'Unauthorized')
-     *
-     * // Mock a 500 error with custom method
-     * mock.mockError(
-     *   'https://api.example.com/fail',
-     *   500,
-     *   'Server Error',
-     *   { method: 'POST' }
-     * )
-     * ```
-     */
-    mockError(url: string, status: number, message?: string, options?: MockErrorOptions): import("cloudflare:test").MockScope<object>;
-    /**
-     * Generic helper to mock any HTTP request
-     *
-     * @param origin - The origin URL (e.g., 'https://api.example.com')
-     * @param options - Request matching and response options
-     *
-     * @example
-     * ```typescript
-     * mock.mockRequest('https://api.example.com', {
-     *   path: '/users',
-     *   method: 'PUT',
-     *   status: 200,
-     *   body: { updated: true }
-     * })
-     * ```
-     */
-    mockRequest(origin: string, options: {
-        path: string;
-        method?: string;
-        status?: number;
-        body?: unknown;
-    }): import("cloudflare:test").MockScope<object>;
-}
-/**
- * Factory function to create a new FetchMock instance
- *
- * @returns A new FetchMock instance
- *
- * @example
- * ```typescript
- * import { createFetchMock } from '@stratal/testing'
- *
- * const mock = createFetchMock()
- *
- * beforeEach(() => {
- *   mock.activate()
- *   mock.disableNetConnect()
- * })
- *
- * afterEach(() => {
- *   mock.reset()
- * })
- * ```
- */
-export declare function createFetchMock(): FetchMock;
-//# sourceMappingURL=fetch-mock.d.ts.map

package/dist/core/http/fetch-mock.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"fetch-mock.d.ts","sourceRoot":"","sources":["../../../src/core/http/fetch-mock.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,SAAS;IACrB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM;IAIlB;;;;;;;;;OASG;IACH,QAAQ;IAIR;;OAEG;IACH,UAAU;IAIV;;;;;;;;;;OAUG;IACH,iBAAiB;IAIjB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAOvC;;;;;;;;;;;;;;;OAeG;IACH,2BAA2B;IAI3B;;;;;;;;;OASG;IACH,KAAK;IAKL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB;IAwB1E;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB;IAkBvF;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE;CAS5E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,IAAI,SAAS,CAE3C"}