@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/testing/mock-provider.js

@@ -0,0 +1,333 @@
+/**
+ * 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 { Container, Scope } from "../di/inversify.js";
+/**
+ * Detect the current test framework.
+ */
+function detectTestFramework() {
+    // Check for Jest
+    if (typeof jest !== "undefined" && typeof jest.fn === "function") {
+        return "jest";
+    }
+    const globalWithVi = globalThis;
+    if (typeof globalWithVi.vi !== "undefined" &&
+        typeof globalWithVi.vi.fn === "function") {
+        return "vitest";
+    }
+    return "unknown";
+}
+/**
+ * Create a mock function compatible with Jest/Vitest.
+ */
+function createMockFunction(framework) {
+    if (framework === "jest" && typeof jest !== "undefined") {
+        return jest.fn();
+    }
+    const globalWithVi = globalThis;
+    if (framework === "vitest" && typeof globalWithVi.vi !== "undefined") {
+        return globalWithVi.vi.fn();
+    }
+    // Fallback: Create a basic mock function
+    const calls = [];
+    const results = [];
+    let returnValue;
+    let resolvedValue;
+    let rejectedValue;
+    let implementation;
+    const mockFn = ((...args) => {
+        calls.push(args);
+        if (implementation) {
+            try {
+                const result = implementation(...args);
+                results.push({ type: "return", value: result });
+                return result;
+            }
+            catch (error) {
+                results.push({ type: "throw", value: error });
+                throw error;
+            }
+        }
+        if (rejectedValue !== undefined) {
+            results.push({ type: "throw", value: rejectedValue });
+            return Promise.reject(rejectedValue);
+        }
+        if (resolvedValue !== undefined) {
+            results.push({ type: "return", value: resolvedValue });
+            return Promise.resolve(resolvedValue);
+        }
+        results.push({ type: "return", value: returnValue });
+        return returnValue;
+    });
+    mockFn.mockReturnValue = (value) => {
+        returnValue = value;
+        return mockFn;
+    };
+    mockFn.mockResolvedValue = (value) => {
+        resolvedValue = value;
+        return mockFn;
+    };
+    mockFn.mockRejectedValue = (error) => {
+        rejectedValue = error;
+        return mockFn;
+    };
+    mockFn.mockImplementation = (fn) => {
+        implementation = fn;
+        return mockFn;
+    };
+    mockFn.mockClear = () => {
+        calls.length = 0;
+        results.length = 0;
+    };
+    mockFn.mockReset = () => {
+        mockFn.mockClear();
+        returnValue = undefined;
+        resolvedValue = undefined;
+        rejectedValue = undefined;
+        implementation = undefined;
+    };
+    mockFn.mock = { calls, results };
+    return mockFn;
+}
+/**
+ * Create a mock object for a class, auto-mocking all methods.
+ */
+function createAutoMock(classRef, framework) {
+    const mock = {};
+    // Get all method names from the prototype
+    const prototype = classRef.prototype;
+    const propertyNames = Object.getOwnPropertyNames(prototype);
+    for (const name of propertyNames) {
+        if (name === "constructor")
+            continue;
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+        if (descriptor && typeof descriptor.value === "function") {
+            mock[name] = createMockFunction(framework);
+        }
+    }
+    return mock;
+}
+/**
+ * Extract dependency types from a class using reflection.
+ * This uses the Inversify metadata to get constructor parameter types.
+ */
+function extractDependencies(classRef) {
+    const dependencies = [];
+    // Try to get parameter types from reflect-metadata
+    const paramTypes = Reflect.getMetadata("design:paramtypes", classRef);
+    if (paramTypes && Array.isArray(paramTypes)) {
+        for (const type of paramTypes) {
+            if (type && typeof type === "function") {
+                dependencies.push(type);
+            }
+        }
+    }
+    return dependencies;
+}
+/**
+ * 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 function mockProvider(serviceClass, options = {}) {
+    const { mocks = {}, additionalBindings = [], autoMock = true, mockFramework = "jest", } = options;
+    // Detect test framework
+    const framework = detectTestFramework();
+    const effectiveFramework = framework !== "unknown" ? framework : mockFramework;
+    // Create a test container
+    const container = new Container({
+        defaultScope: Scope.Singleton,
+    });
+    // Extract dependencies from the service class
+    const dependencies = extractDependencies(serviceClass);
+    // Build mock objects for dependencies
+    const mockObjects = {};
+    for (let i = 0; i < dependencies.length; i++) {
+        const dep = dependencies[i];
+        const depName = typeof dep === "function" ? dep.name : String(dep);
+        // Check if user provided a mock
+        const userMock = mocks[depName];
+        if (userMock) {
+            // Use user-provided mock
+            mockObjects[depName] = userMock;
+            container.bind(dep).toConstantValue(userMock);
+        }
+        else if (autoMock && typeof dep === "function") {
+            // Auto-mock the dependency
+            const autoMocked = createAutoMock(dep, effectiveFramework);
+            mockObjects[depName] = autoMocked;
+            container.bind(dep).toConstantValue(autoMocked);
+        }
+    }
+    // Apply additional bindings
+    for (const binding of additionalBindings) {
+        let value;
+        if (binding.useValue !== undefined) {
+            value = binding.useValue;
+        }
+        else if (binding.useFactory) {
+            value = binding.useFactory();
+        }
+        else if (binding.useClass) {
+            value = new binding.useClass();
+        }
+        if (value !== undefined) {
+            container.bind(binding.provide).toConstantValue(value);
+        }
+    }
+    // Bind and resolve the service
+    container.bind(serviceClass).toSelf();
+    const service = container.get(serviceClass);
+    // Create utility functions
+    const resetAllMocks = () => {
+        for (const mockObj of Object.values(mockObjects)) {
+            if (mockObj && typeof mockObj === "object") {
+                for (const fn of Object.values(mockObj)) {
+                    if (typeof fn === "function" && "mockReset" in fn) {
+                        fn.mockReset();
+                    }
+                }
+            }
+        }
+    };
+    const clearAllMocks = () => {
+        for (const mockObj of Object.values(mockObjects)) {
+            if (mockObj && typeof mockObj === "object") {
+                for (const fn of Object.values(mockObj)) {
+                    if (typeof fn === "function" && "mockClear" in fn) {
+                        fn.mockClear();
+                    }
+                }
+            }
+        }
+    };
+    const verifyAllMocks = () => {
+        // Basic verification - check that all mocks were called at least once
+        // For more sophisticated verification, use Jest/Vitest expect
+        for (const [name, mockObj] of Object.entries(mockObjects)) {
+            if (mockObj && typeof mockObj === "object") {
+                for (const [fnName, fn] of Object.entries(mockObj)) {
+                    if (typeof fn === "function" && "mock" in fn) {
+                        const mockFn = fn;
+                        if (mockFn.mock.calls.length === 0) {
+                            console.warn(`Warning: ${name}.${fnName} was never called`);
+                        }
+                    }
+                }
+            }
+        }
+    };
+    return {
+        service,
+        mocks: mockObjects,
+        container,
+        resetAllMocks,
+        clearAllMocks,
+        verifyAllMocks,
+    };
+}
+/**
+ * Create a standalone mock function.
+ *
+ * @example
+ * ```typescript
+ * const mockFn = createMock<[string], Promise<User>>();
+ * mockFn.mockResolvedValue({ id: "123", name: "John" });
+ * ```
+ */
+export function createMock() {
+    return createMockFunction(detectTestFramework());
+}
+/**
+ * Create a mock object from a class.
+ *
+ * @example
+ * ```typescript
+ * const mockRepo = createMockObject(UserRepository);
+ * mockRepo.findById.mockResolvedValue(mockUser);
+ * ```
+ */
+export function createMockObject(classRef) {
+    return createAutoMock(classRef, detectTestFramework());
+}
+/**
+ * Spy on a method of an object.
+ *
+ * @example
+ * ```typescript
+ * const spy = spyOn(userService, "getUser");
+ * await userService.getUser("123");
+ * expect(spy).toHaveBeenCalledWith("123");
+ * ```
+ */
+export function spyOn(obj, method) {
+    const framework = detectTestFramework();
+    const original = obj[method];
+    if (typeof original !== "function") {
+        throw new Error(`${String(method)} is not a function`);
+    }
+    const mockFn = createMockFunction(framework);
+    mockFn.mockImplementation((...args) => {
+        return original.apply(obj, args);
+    });
+    obj[method] = mockFn;
+    // Add restore method
+    const mockFnWithRestore = mockFn;
+    mockFnWithRestore.mockRestore = () => {
+        obj[method] =
+            original;
+    };
+    return mockFnWithRestore;
+}

package/lib/esm/testing/snapshot-request.js

@@ -0,0 +1,358 @@
+/**
+ * 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 * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+import { createFluentRequest } from "./fluent-request.js";
+/**
+ * Internal snapshot request implementation.
+ */
+class SnapshotRequestImpl {
+    baseUrl;
+    method;
+    urlPath;
+    fluentRequest;
+    testName;
+    constructor(baseUrl, method, urlPath) {
+        this.baseUrl = baseUrl;
+        this.method = method;
+        this.urlPath = urlPath;
+        this.fluentRequest = createFluentRequest(baseUrl).request(method, urlPath);
+        this.testName = getTestName();
+    }
+    set(headersOrKey, value) {
+        if (typeof headersOrKey === "string" && value !== undefined) {
+            this.fluentRequest.set(headersOrKey, value);
+        }
+        else {
+            this.fluentRequest.set(headersOrKey);
+        }
+        return this;
+    }
+    send(body) {
+        this.fluentRequest.send(body);
+        return this;
+    }
+    query(params) {
+        this.fluentRequest.query(params);
+        return this;
+    }
+    auth(token, type) {
+        this.fluentRequest.auth(token, type);
+        return this;
+    }
+    attach(field, filePath) {
+        this.fluentRequest.attach(field, filePath);
+        return this;
+    }
+    type(contentType) {
+        this.fluentRequest.type(contentType);
+        return this;
+    }
+    accept(contentType) {
+        this.fluentRequest.accept(contentType);
+        return this;
+    }
+    timeout(ms) {
+        this.fluentRequest.timeout(ms);
+        return this;
+    }
+    expectStatus(status) {
+        this.fluentRequest.expectStatus(status);
+        return this;
+    }
+    expectBodyPath(jsonPath, expected) {
+        this.fluentRequest.expectBodyPath(jsonPath, expected);
+        return this;
+    }
+    expectHeaders(headers) {
+        this.fluentRequest.expectHeaders(headers);
+        return this;
+    }
+    expectHeader(key, value) {
+        this.fluentRequest.expectHeader(key, value);
+        return this;
+    }
+    expectTime(options) {
+        this.fluentRequest.expectTime(options);
+        return this;
+    }
+    expectContentType(typeValue) {
+        this.fluentRequest.expectContentType(typeValue);
+        return this;
+    }
+    expect(assertion) {
+        this.fluentRequest.expect(assertion);
+        return this;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    execute() {
+        return this.fluentRequest.execute();
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    end() {
+        return this.fluentRequest.end();
+    }
+    /**
+     * Assert response matches snapshot.
+     *
+     * @param options - Snapshot options
+     */
+    async expectSnapshot(options = {}) {
+        const response = await this.fluentRequest.execute();
+        const snapshotPath = this.getSnapshotPath(options);
+        const serializedBody = this.serializeForSnapshot(response.body, options);
+        // Check if snapshot exists
+        if (fs.existsSync(snapshotPath)) {
+            // Compare with existing snapshot
+            const existingSnapshot = fs.readFileSync(snapshotPath, "utf-8");
+            if (options.update) {
+                // Update mode - write new snapshot
+                this.writeSnapshot(snapshotPath, serializedBody);
+                console.log(`📸 Snapshot updated: ${snapshotPath}`);
+            }
+            else if (existingSnapshot !== serializedBody) {
+                // Show diff and throw error
+                const diff = generateDiff(existingSnapshot, serializedBody);
+                throw new Error(`Snapshot mismatch!\n\n` +
+                    `Expected:\n${existingSnapshot}\n\n` +
+                    `Received:\n${serializedBody}\n\n` +
+                    `Diff:\n${diff}\n\n` +
+                    `💡 To update the snapshot, run with { update: true } or use updateSnapshot()`);
+            }
+        }
+        else {
+            // Create new snapshot
+            this.writeSnapshot(snapshotPath, serializedBody);
+            console.log(`📸 Snapshot created: ${snapshotPath}`);
+        }
+    }
+    /**
+     * Create or update snapshot.
+     */
+    async updateSnapshot(options = {}) {
+        return this.expectSnapshot({ ...options, update: true });
+    }
+    /**
+     * Get current snapshot for comparison.
+     */
+    async getSnapshot(options = {}) {
+        const snapshotPath = this.getSnapshotPath(options);
+        if (fs.existsSync(snapshotPath)) {
+            const content = fs.readFileSync(snapshotPath, "utf-8");
+            try {
+                return JSON.parse(content);
+            }
+            catch {
+                return content;
+            }
+        }
+        return null;
+    }
+    /**
+     * Get the snapshot file path.
+     */
+    getSnapshotPath(options) {
+        const directory = options.directory || "__snapshots__";
+        const name = options.name || this.generateSnapshotName();
+        // Ensure directory exists
+        const snapshotDir = path.resolve(process.cwd(), directory);
+        if (!fs.existsSync(snapshotDir)) {
+            fs.mkdirSync(snapshotDir, { recursive: true });
+        }
+        return path.join(snapshotDir, `${name}.snap`);
+    }
+    /**
+     * Generate a unique snapshot name based on test and request.
+     */
+    generateSnapshotName() {
+        const testPart = this.testName.replace(/[^a-zA-Z0-9]/g, "_").toLowerCase();
+        const requestPart = `${this.method.toLowerCase()}_${this.urlPath.replace(/[^a-zA-Z0-9]/g, "_")}`;
+        return `${testPart}_${requestPart}`;
+    }
+    /**
+     * Serialize body for snapshot, applying ignore rules.
+     */
+    serializeForSnapshot(body, options) {
+        let processed = body;
+        // Apply ignore rules
+        if (options.ignore && options.ignore.length > 0) {
+            processed = removeIgnoredFields(body, options.ignore);
+        }
+        // Use custom serializer if provided
+        if (options.serializer) {
+            return options.serializer(processed);
+        }
+        // Default: Pretty-print JSON
+        return JSON.stringify(processed, null, 2);
+    }
+    /**
+     * Write snapshot to file.
+     */
+    writeSnapshot(snapshotPath, content) {
+        fs.writeFileSync(snapshotPath, content, "utf-8");
+    }
+}
+/**
+ * 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 function snapshotRequest(appOrUrl) {
+    const baseUrl = typeof appOrUrl === "string" ? appOrUrl : appOrUrl.baseUrl;
+    return {
+        get(urlPath) {
+            return new SnapshotRequestImpl(baseUrl, "GET", urlPath);
+        },
+        post(urlPath) {
+            return new SnapshotRequestImpl(baseUrl, "POST", urlPath);
+        },
+        put(urlPath) {
+            return new SnapshotRequestImpl(baseUrl, "PUT", urlPath);
+        },
+        patch(urlPath) {
+            return new SnapshotRequestImpl(baseUrl, "PATCH", urlPath);
+        },
+        delete(urlPath) {
+            return new SnapshotRequestImpl(baseUrl, "DELETE", urlPath);
+        },
+        head(urlPath) {
+            return new SnapshotRequestImpl(baseUrl, "HEAD", urlPath);
+        },
+        options(urlPath) {
+            return new SnapshotRequestImpl(baseUrl, "OPTIONS", urlPath);
+        },
+    };
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Get the current test name from the test framework.
+ */
+function getTestName() {
+    const expectWithState = expect;
+    if (typeof expect !== "undefined" && expectWithState.getState) {
+        const state = expectWithState.getState();
+        if (state && state.currentTestName) {
+            return state.currentTestName;
+        }
+    }
+    const globalWithVitest = globalThis;
+    if (typeof globalWithVitest.__vitest_worker__ !== "undefined") {
+        const worker = globalWithVitest.__vitest_worker__;
+        if (worker?.current?.name) {
+            return worker.current.name;
+        }
+    }
+    // Fallback: Generate hash based on stack trace
+    const stack = new Error().stack || "";
+    return crypto.createHash("md5").update(stack).digest("hex").substring(0, 8);
+}
+/**
+ * Remove ignored fields from an object recursively.
+ */
+function removeIgnoredFields(obj, ignore) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => removeIgnoredFields(item, ignore));
+    }
+    if (typeof obj === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (ignore.includes(key)) {
+                result[key] = "[IGNORED]";
+            }
+            else if (typeof value === "object" && value !== null) {
+                result[key] = removeIgnoredFields(value, ignore);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Generate a simple diff between two strings.
+ */
+function generateDiff(expected, received) {
+    const expectedLines = expected.split("\n");
+    const receivedLines = received.split("\n");
+    const diff = [];
+    const maxLines = Math.max(expectedLines.length, receivedLines.length);
+    for (let i = 0; i < maxLines; i++) {
+        const expectedLine = expectedLines[i];
+        const receivedLine = receivedLines[i];
+        if (expectedLine === receivedLine) {
+            diff.push(`  ${expectedLine || ""}`);
+        }
+        else {
+            if (expectedLine !== undefined) {
+                diff.push(`- ${expectedLine}`);
+            }
+            if (receivedLine !== undefined) {
+                diff.push(`+ ${receivedLine}`);
+            }
+        }
+    }
+    return diff.join("\n");
+}
+/**
+ * Snapshot assertion helper for use with Jest/Vitest.
+ *
+ * @example
+ * ```typescript
+ * expect(response.body).toMatchApiSnapshot({
+ *   ignore: ["id", "createdAt"]
+ * });
+ * ```
+ */
+export function toMatchApiSnapshot(received, options = {}) {
+    const processed = options.ignore
+        ? removeIgnoredFields(received, options.ignore)
+        : received;
+    if (typeof expect !== "undefined" && expect.getState) {
+        try {
+            expect(processed).toMatchSnapshot();
+            return {
+                pass: true,
+                message: () => "Snapshot matched",
+            };
+        }
+        catch (error) {
+            return {
+                pass: false,
+                message: () => error.message,
+            };
+        }
+    }
+    return {
+        pass: true,
+        message: () => "Snapshot matching not available in this environment",
+    };
+}

package/lib/esm/testing/testing.interfaces.js

@@ -0,0 +1,9 @@
+/**
+ * Testing Module - Core Interfaces and Types
+ *
+ * @module testing
+ *
+ * Provides comprehensive testing utilities for ExpressoTS applications.
+ * These interfaces define the contract for all testing utilities.
+ */
+export {};