@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/cjs/types/testing/matchers.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Custom Matchers for Jest/Vitest
+ *
+ * @module testing
+ *
+ * Extends Jest/Vitest with ExpressoTS-specific matchers.
+ *
+ * @example
+ * ```typescript
+ * // Setup in test/setup.ts
+ * import { setupExpressoTSMatchers } from "@expressots/testing";
+ * setupExpressoTSMatchers();
+ *
+ * // Use in tests
+ * expect(response).toHaveStatus(200);
+ * expect(response).toHaveBody({ id: 1 });
+ * expect(response).toRespondWithin(100);
+ * ```
+ */
+import { FluentResponse } from "./testing.interfaces.js";
+/**
+ * Matcher result interface compatible with Jest/Vitest.
+ */
+interface MatcherResult {
+    pass: boolean;
+    message: () => string;
+}
+/**
+ * Custom matchers for ExpressoTS responses.
+ */
+export declare const expressoTSMatchers: {
+    /**
+     * Assert response has specific status code.
+     *
+     * @example
+     * expect(response).toHaveStatus(200);
+     * expect(response).toHaveStatus(201);
+     */
+    toHaveStatus(received: FluentResponse, expected: number): MatcherResult;
+    /**
+     * Assert response is successful (2xx).
+     *
+     * @example
+     * expect(response).toBeSuccessful();
+     */
+    toBeSuccessful(received: FluentResponse): MatcherResult;
+    /**
+     * Assert response is a redirect (3xx).
+     *
+     * @example
+     * expect(response).toBeRedirect();
+     */
+    toBeRedirect(received: FluentResponse): MatcherResult;
+    /**
+     * Assert response is a client error (4xx).
+     *
+     * @example
+     * expect(response).toBeClientError();
+     */
+    toBeClientError(received: FluentResponse): MatcherResult;
+    /**
+     * Assert response is a server error (5xx).
+     *
+     * @example
+     * expect(response).toBeServerError();
+     */
+    toBeServerError(received: FluentResponse): MatcherResult;
+    /**
+     * Assert response has specific body content.
+     *
+     * @example
+     * expect(response).toHaveBody({ id: 1, name: "John" });
+     * expect(response).toHaveBody((body) => body.id > 0);
+     */
+    toHaveBody(received: FluentResponse, expected: unknown | ((body: unknown) => boolean)): MatcherResult;
+    /**
+     * Assert response has specific header.
+     *
+     * @example
+     * expect(response).toHaveHeader("content-type", "application/json");
+     * expect(response).toHaveHeader("x-custom-header");
+     */
+    toHaveHeader(received: FluentResponse, header: string, value?: string | RegExp): MatcherResult;
+    /**
+     * Assert response content type.
+     *
+     * @example
+     * expect(response).toHaveContentType("application/json");
+     * expect(response).toHaveContentType(/json/);
+     */
+    toHaveContentType(received: FluentResponse, expected: string | RegExp): MatcherResult;
+    /**
+     * Assert response time is within threshold.
+     *
+     * @example
+     * expect(response).toRespondWithin(100); // Less than 100ms
+     */
+    toRespondWithin(received: FluentResponse, maxMs: number): MatcherResult;
+    /**
+     * Assert response has JSON body.
+     *
+     * @example
+     * expect(response).toBeJSON();
+     */
+    toBeJSON(received: FluentResponse): MatcherResult;
+    /**
+     * Assert response body has property.
+     *
+     * @example
+     * expect(response).toHaveBodyProperty("user.id");
+     * expect(response).toHaveBodyProperty("user.name", "John");
+     */
+    toHaveBodyProperty(received: FluentResponse, path: string, value?: unknown): MatcherResult;
+    /**
+     * Assert response body is an array.
+     *
+     * @example
+     * expect(response).toHaveBodyArray();
+     * expect(response).toHaveBodyArray(3); // Array with length 3
+     */
+    toHaveBodyArray(received: FluentResponse, length?: number): MatcherResult;
+    /**
+     * Assert response body matches JSON schema (basic validation).
+     *
+     * @example
+     * expect(response).toMatchSchema({
+     *   type: "object",
+     *   properties: {
+     *     id: { type: "number" },
+     *     name: { type: "string" }
+     *   }
+     * });
+     */
+    toMatchSchema(received: FluentResponse, schema: JSONSchema): MatcherResult;
+};
+/**
+ * Setup ExpressoTS matchers for Jest/Vitest.
+ *
+ * @example
+ * ```typescript
+ * // In test/setup.ts or jest.setup.ts
+ * import { setupExpressoTSMatchers } from "@expressots/testing";
+ * setupExpressoTSMatchers();
+ * ```
+ */
+export declare function setupExpressoTSMatchers(): void;
+/**
+ * Extend Jest/Vitest expect interface.
+ */
+declare global {
+    namespace jest {
+        interface Matchers<R> {
+            toHaveStatus(status: number): R;
+            toBeSuccessful(): R;
+            toBeRedirect(): R;
+            toBeClientError(): R;
+            toBeServerError(): R;
+            toHaveBody(expected: unknown | ((body: unknown) => boolean)): R;
+            toHaveHeader(header: string, value?: string | RegExp): R;
+            toHaveContentType(expected: string | RegExp): R;
+            toRespondWithin(maxMs: number): R;
+            toBeJSON(): R;
+            toHaveBodyProperty(path: string, value?: unknown): R;
+            toHaveBodyArray(length?: number): R;
+            toMatchSchema(schema: JSONSchema): R;
+        }
+    }
+}
+/**
+ * Basic JSON Schema type.
+ */
+interface JSONSchema {
+    type?: "string" | "number" | "boolean" | "object" | "array" | "null";
+    properties?: Record<string, JSONSchema>;
+    items?: JSONSchema;
+    required?: Array<string>;
+    enum?: Array<unknown>;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+}
+export {};

package/lib/cjs/types/testing/mock-context.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Request Context Mocking
+ *
+ * @module testing
+ *
+ * Mock entire request contexts for testing guards, middleware, and services.
+ *
+ * @example
+ * ```typescript
+ * const context = mockContext({
+ *   user: { id: 123, role: "admin" },
+ *   headers: { "x-api-key": "test-key" },
+ *   params: { id: "456" }
+ * });
+ *
+ * const guard = container.get(AdminGuard);
+ * const result = await guard.canActivate(context);
+ * expect(result).toBe(true);
+ * ```
+ */
+import { Request, Response } from "express";
+import { MockContextOptions, MockContext, MockFunction } from "./testing.interfaces.js";
+/**
+ * Create a mock request context for testing.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept testing
+ *
+ * Creates mock Express request and response objects for testing
+ * guards, middleware, interceptors, and services.
+ *
+ * @param options - Mock context options
+ * @returns Mock context with request, response, and utilities
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const ctx = mockContext({
+ *   user: { id: 123, role: "admin" },
+ *   headers: { "authorization": "Bearer token123" }
+ * });
+ *
+ * // Test a guard
+ * const guard = container.get(AuthGuard);
+ * const canActivate = await guard.canActivate(ctx);
+ * expect(canActivate).toBe(true);
+ *
+ * // Test middleware
+ * const middleware = container.get(LoggingMiddleware);
+ * await middleware.use(ctx.request, ctx.response, ctx.next);
+ * expect(ctx.next).toHaveBeenCalled();
+ *
+ * // Update context
+ * ctx.update({ user: { id: 456, role: "user" } });
+ *
+ * // Reset to initial state
+ * ctx.reset();
+ * ```
+ */
+export declare function mockContext(options?: MockContextOptions): MockContext;
+/**
+ * Create a mock execution context compatible with ExpressoTS guards/interceptors.
+ *
+ * @example
+ * ```typescript
+ * const execContext = mockExecutionContext({
+ *   user: { id: 123 },
+ *   params: { id: "456" }
+ * });
+ *
+ * const result = await guard.canActivate(execContext);
+ * ```
+ */
+export declare function mockExecutionContext(options?: MockContextOptions): {
+    request: Request;
+    response: Response;
+    getRequest: () => Request;
+    getResponse: () => Response;
+    getClass: () => new (...args: Array<unknown>) => unknown;
+    getHandler: () => (...args: Array<unknown>) => unknown;
+    switchToHttp: () => {
+        getRequest: () => Request;
+        getResponse: () => Response;
+    };
+};
+/**
+ * Create a mock next function that tracks calls.
+ *
+ * @example
+ * ```typescript
+ * const next = mockNextFunction();
+ * await middleware.use(req, res, next);
+ * expect(next).toHaveBeenCalled();
+ * expect(next.mock.calls.length).toBe(1);
+ * ```
+ */
+export declare function mockNextFunction(): MockFunction;
+/**
+ * Create mock request/response pair for simple middleware testing.
+ *
+ * @example
+ * ```typescript
+ * const { req, res, next } = mockReqRes({
+ *   method: "POST",
+ *   body: { name: "Test" }
+ * });
+ *
+ * await validationMiddleware(req, res, next);
+ * expect(next).toHaveBeenCalled();
+ * ```
+ */
+export declare function mockReqRes(options?: MockContextOptions): {
+    req: Request;
+    res: Response;
+    next: MockFunction;
+};

package/lib/cjs/types/testing/mock-provider.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Smart Mocking System
+ *
+ * @module testing
+ *
+ * Provides intelligent mocking with auto-discovery of dependencies
+ * and TypeScript auto-completion for all mock methods.
+ *
+ * @example
+ * ```typescript
+ * const { service, mocks } = mockProvider(UserService, {
+ *   mocks: {
+ *     UserRepository: {
+ *       findById: jest.fn().mockResolvedValue(mockUser)
+ *     }
+ *   }
+ * });
+ *
+ * await service.getUser("123");
+ * expect(mocks.UserRepository.findById).toHaveBeenCalledWith("123");
+ * ```
+ */
+import { MockProviderOptions, MockProviderResult, MockDependencies, MockFunction } from "./testing.interfaces.js";
+/**
+ * Mock a provider with smart dependency discovery and auto-completion.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept testing
+ *
+ * This function provides:
+ * - Auto-discovery of dependencies
+ * - TypeScript auto-completion for mock methods
+ * - Automatic mock creation for unspecified dependencies
+ * - Easy mock verification
+ *
+ * @param serviceClass - The service class to mock
+ * @param options - Mock options including dependency mocks
+ * @returns Mock result with service, mocks, and utilities
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const { service, mocks } = mockProvider(UserService, {
+ *   mocks: {
+ *     UserRepository: {
+ *       findById: jest.fn().mockResolvedValue(mockUser)
+ *     }
+ *   }
+ * });
+ *
+ * // With auto-mocking
+ * const { service, mocks } = mockProvider(UserService, {
+ *   autoMock: true  // All dependencies are auto-mocked
+ * });
+ *
+ * // Test the service
+ * await service.getUser("123");
+ * expect(mocks.UserRepository.findById).toHaveBeenCalledWith("123");
+ * ```
+ */
+export declare function mockProvider<T>(serviceClass: new (...args: Array<unknown>) => T, options?: MockProviderOptions<T>): MockProviderResult<T>;
+/**
+ * Create a standalone mock function.
+ *
+ * @example
+ * ```typescript
+ * const mockFn = createMock<[string], Promise<User>>();
+ * mockFn.mockResolvedValue({ id: "123", name: "John" });
+ * ```
+ */
+export declare function createMock<A extends Array<unknown> = Array<unknown>, R = unknown>(): MockFunction<A, R>;
+/**
+ * Create a mock object from a class.
+ *
+ * @example
+ * ```typescript
+ * const mockRepo = createMockObject(UserRepository);
+ * mockRepo.findById.mockResolvedValue(mockUser);
+ * ```
+ */
+export declare function createMockObject<T>(classRef: new (...args: Array<unknown>) => T): MockDependencies<typeof classRef>;
+/**
+ * Spy on a method of an object.
+ *
+ * @example
+ * ```typescript
+ * const spy = spyOn(userService, "getUser");
+ * await userService.getUser("123");
+ * expect(spy).toHaveBeenCalledWith("123");
+ * ```
+ */
+export declare function spyOn<T extends object, K extends keyof T>(obj: T, method: K): MockFunction;

package/lib/cjs/types/testing/snapshot-request.d.ts

@@ -0,0 +1,46 @@
+/**
+ * API Snapshot Testing
+ *
+ * @module testing
+ *
+ * Provides snapshot testing for API responses.
+ * Automatically detects breaking changes in API structure.
+ *
+ * @example
+ * ```typescript
+ * await snapshotRequest(app)
+ *   .get("/users")
+ *   .expectSnapshot({ ignore: ["createdAt", "updatedAt"] });
+ * ```
+ */
+import { SnapshotRequestBuilder, SnapshotOptions } from "./testing.interfaces.js";
+/**
+ * Create a snapshot request builder.
+ *
+ * @param appOrUrl - Test app or base URL
+ * @returns Snapshot request builder
+ *
+ * @example
+ * ```typescript
+ * await snapshotRequest(app)
+ *   .get("/users")
+ *   .expectSnapshot({ ignore: ["id", "createdAt"] });
+ * ```
+ */
+export declare function snapshotRequest(appOrUrl: {
+    baseUrl: string;
+} | string): SnapshotRequestBuilder;
+/**
+ * Snapshot assertion helper for use with Jest/Vitest.
+ *
+ * @example
+ * ```typescript
+ * expect(response.body).toMatchApiSnapshot({
+ *   ignore: ["id", "createdAt"]
+ * });
+ * ```
+ */
+export declare function toMatchApiSnapshot(received: unknown, options?: SnapshotOptions): {
+    pass: boolean;
+    message: () => string;
+};