@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -0,0 +1,400 @@
+/**
+ * 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);
+ * ```
+ */
+/**
+ * Create a mock function.
+ */
+function createMockFn() {
+    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 Express request object.
+ */
+function createMockRequest(options) {
+    const { user, headers = {}, params = {}, query = {}, body, cookies = {}, session = {}, method = "GET", path = "/", url, ip = "127.0.0.1", request: customRequest = {}, } = options;
+    // Normalize headers to lowercase
+    const normalizedHeaders = {};
+    for (const [key, value] of Object.entries(headers)) {
+        normalizedHeaders[key.toLowerCase()] = value;
+    }
+    const mockReq = {
+        method,
+        path,
+        url: url || path,
+        baseUrl: "",
+        originalUrl: url || path,
+        params,
+        query: query,
+        body,
+        headers: normalizedHeaders,
+        cookies,
+        ip,
+        ips: [ip],
+        protocol: "http",
+        secure: false,
+        hostname: "localhost",
+        host: "localhost",
+        subdomains: [],
+        fresh: false,
+        stale: true,
+        xhr: false,
+        route: undefined,
+        signedCookies: {},
+        app: {},
+        res: undefined,
+        // Methods
+        get: ((name) => {
+            return normalizedHeaders[name.toLowerCase()];
+        }),
+        header: ((name) => {
+            return normalizedHeaders[name.toLowerCase()];
+        }),
+        accepts: createMockFn().mockReturnValue(true),
+        acceptsCharsets: createMockFn().mockReturnValue(true),
+        acceptsEncodings: createMockFn().mockReturnValue(true),
+        acceptsLanguages: createMockFn().mockReturnValue(true),
+        is: ((type) => {
+            const contentType = normalizedHeaders["content-type"] || "";
+            if (Array.isArray(type)) {
+                return type.find((t) => contentType.includes(t)) || false;
+            }
+            return contentType.includes(type) ? type : false;
+        }),
+        range: createMockFn().mockReturnValue(undefined),
+        ...customRequest,
+    };
+    // Add user if provided
+    if (user) {
+        mockReq.user = user;
+    }
+    // Add session if provided
+    if (session) {
+        mockReq.session = session;
+    }
+    return mockReq;
+}
+/**
+ * Create a mock Express response object.
+ */
+function createMockResponse(options) {
+    const { response: customResponse = {} } = options;
+    let statusCode = 200;
+    const statusMessage = "OK";
+    const responseHeaders = {};
+    let responseBody;
+    const locals = {};
+    const mockRes = {
+        statusCode,
+        statusMessage,
+        headersSent: false,
+        locals,
+        app: {},
+        req: undefined,
+        // Chainable methods
+        status: function (code) {
+            statusCode = code;
+            this.statusCode = code;
+            return this;
+        },
+        sendStatus: function (code) {
+            statusCode = code;
+            this.statusCode = code;
+            return this;
+        },
+    };
+    // Create the mock response object with proper this binding
+    // We'll define methods that return the mockRes object
+    const setFn = function (field, val) {
+        if (typeof field === "object") {
+            for (const [key, value] of Object.entries(field)) {
+                responseHeaders[key.toLowerCase()] = value;
+            }
+        }
+        else if (val !== undefined) {
+            responseHeaders[field.toLowerCase()] = val;
+        }
+        return mockRes;
+    };
+    Object.assign(mockRes, {
+        set: setFn,
+        header: setFn,
+        get: function (field) {
+            return responseHeaders[field.toLowerCase()];
+        },
+        json: function (body) {
+            responseBody = body;
+            responseHeaders["content-type"] = "application/json";
+            return mockRes;
+        },
+        send: function (body) {
+            responseBody = body;
+            return mockRes;
+        },
+        end: createMockFn(),
+        type: function (typeValue) {
+            responseHeaders["content-type"] = typeValue;
+            return mockRes;
+        },
+        contentType: function (typeValue) {
+            responseHeaders["content-type"] = typeValue;
+            return mockRes;
+        },
+        format: createMockFn(),
+        attachment: function (filename) {
+            responseHeaders["content-disposition"] = filename
+                ? `attachment; filename="${filename}"`
+                : "attachment";
+            return mockRes;
+        },
+        cookie: createMockFn(),
+        clearCookie: createMockFn(),
+        redirect: createMockFn(),
+        render: createMockFn(),
+        location: function (url) {
+            responseHeaders["location"] = url;
+            return mockRes;
+        },
+        links: createMockFn(),
+        vary: function (field) {
+            responseHeaders["vary"] = field;
+            return mockRes;
+        },
+        append: function (field, val) {
+            const existing = responseHeaders[field.toLowerCase()];
+            const newVal = Array.isArray(val) ? val.join(", ") : val;
+            responseHeaders[field.toLowerCase()] = existing
+                ? `${existing}, ${newVal}`
+                : newVal;
+            return mockRes;
+        },
+        ...customResponse,
+    });
+    // Add getters for response data (useful for assertions)
+    Object.defineProperty(mockRes, "_body", {
+        get: () => responseBody,
+        enumerable: true,
+    });
+    Object.defineProperty(mockRes, "_headers", {
+        get: () => ({ ...responseHeaders }),
+        enumerable: true,
+    });
+    Object.defineProperty(mockRes, "_status", {
+        get: () => statusCode,
+        enumerable: true,
+    });
+    return mockRes;
+}
+/**
+ * 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 function mockContext(options = {}) {
+    let currentOptions = { ...options };
+    let request = createMockRequest(currentOptions);
+    let response = createMockResponse(currentOptions);
+    let next = createMockFn();
+    const context = {
+        get request() {
+            return request;
+        },
+        get response() {
+            return response;
+        },
+        get next() {
+            return next;
+        },
+        get user() {
+            return currentOptions.user;
+        },
+        reset() {
+            currentOptions = { ...options };
+            request = createMockRequest(currentOptions);
+            response = createMockResponse(currentOptions);
+            next = createMockFn();
+        },
+        update(newOptions) {
+            currentOptions = { ...currentOptions, ...newOptions };
+            request = createMockRequest(currentOptions);
+            response = createMockResponse(currentOptions);
+        },
+    };
+    return context;
+}
+/**
+ * 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 function mockExecutionContext(options = {}) {
+    const ctx = mockContext(options);
+    // Mock controller class
+    class MockController {
+    }
+    // Mock handler function
+    const mockHandler = () => undefined;
+    return {
+        request: ctx.request,
+        response: ctx.response,
+        getRequest: () => ctx.request,
+        getResponse: () => ctx.response,
+        getClass: () => MockController,
+        getHandler: () => mockHandler,
+        switchToHttp: () => ({
+            getRequest: () => ctx.request,
+            getResponse: () => ctx.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 function mockNextFunction() {
+    return createMockFn();
+}
+/**
+ * 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 function mockReqRes(options = {}) {
+    const ctx = mockContext(options);
+    return {
+        req: ctx.request,
+        res: ctx.response,
+        next: ctx.next,
+    };
+}