@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

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

@@ -0,0 +1,452 @@
+/**
+ * Fluent HTTP Testing API
+ *
+ * @module testing
+ *
+ * Provides a chainable, readable, type-safe API for HTTP testing.
+ * Better than supertest with built-in performance assertions.
+ *
+ * @example
+ * ```typescript
+ * await request(app)
+ *   .get("/users/123")
+ *   .expectStatus(200)
+ *   .expectBody<User>({ id: 123, name: "John" })
+ *   .expectTime({ lessThan: 100 });
+ * ```
+ */
+/**
+ * Internal fluent request implementation.
+ */
+class FluentRequestImpl {
+    config;
+    baseUrl;
+    constructor(baseUrl, method, path) {
+        this.baseUrl = baseUrl;
+        this.config = {
+            method,
+            path,
+            headers: {},
+            query: {},
+            timeout: 30000,
+            assertions: [],
+        };
+    }
+    /**
+     * Set request headers.
+     */
+    set(headersOrKey, value) {
+        if (typeof headersOrKey === "string" && value !== undefined) {
+            this.config.headers[headersOrKey] = value;
+        }
+        else if (typeof headersOrKey === "object") {
+            Object.assign(this.config.headers, headersOrKey);
+        }
+        return this;
+    }
+    /**
+     * Set request body.
+     */
+    send(body) {
+        this.config.body = body;
+        if (!this.config.headers["Content-Type"] && typeof body === "object") {
+            this.config.headers["Content-Type"] = "application/json";
+        }
+        return this;
+    }
+    /**
+     * Set query parameters.
+     */
+    query(params) {
+        Object.assign(this.config.query, params);
+        return this;
+    }
+    /**
+     * Set authorization header.
+     */
+    auth(token, type = "Bearer") {
+        this.config.headers["Authorization"] = `${type} ${token}`;
+        return this;
+    }
+    /**
+     * Attach file for upload.
+     * Note: Basic implementation. For full multipart support, use form-data package.
+     */
+    attach(field, filePath) {
+        // Store for later processing during execute
+        if (!this.config.attachments) {
+            this.config.attachments = [];
+        }
+        this.config.attachments.push({ field, filePath });
+        return this;
+    }
+    /**
+     * Set content type.
+     */
+    type(contentType) {
+        this.config.headers["Content-Type"] = contentType;
+        return this;
+    }
+    /**
+     * Set accept header.
+     */
+    accept(contentType) {
+        this.config.headers["Accept"] = contentType;
+        return this;
+    }
+    /**
+     * Set timeout.
+     */
+    timeout(ms) {
+        this.config.timeout = ms;
+        return this;
+    }
+    /**
+     * Assert response status code.
+     */
+    expectStatus(status) {
+        this.config.expectedStatus = status;
+        this.config.assertions.push((response) => {
+            if (response.status !== status) {
+                throw new Error(`Expected status ${status}, but got ${response.status}\n` +
+                    `Response body: ${JSON.stringify(response.body, null, 2)}`);
+            }
+        });
+        return this;
+    }
+    /**
+     * Assert response body.
+     */
+    expectBody(expected) {
+        this.config.assertions.push((response) => {
+            const body = response.body;
+            if (typeof expected === "function") {
+                // Predicate assertion
+                const predicate = expected;
+                if (!predicate(body)) {
+                    throw new Error(`Body predicate assertion failed.\n` +
+                        `Body: ${JSON.stringify(body, null, 2)}`);
+                }
+            }
+            else if (typeof expected === "object" && expected !== null) {
+                // Object comparison (partial match for objects)
+                if (!deepPartialMatch(body, expected)) {
+                    throw new Error(`Expected body to match:\n${JSON.stringify(expected, null, 2)}\n` +
+                        `Actual body:\n${JSON.stringify(body, null, 2)}`);
+                }
+            }
+            else {
+                // Exact match for primitives
+                if (body !== expected) {
+                    throw new Error(`Expected body: ${JSON.stringify(expected)}\n` +
+                        `Actual body: ${JSON.stringify(body)}`);
+                }
+            }
+        });
+        return this;
+    }
+    /**
+     * Assert response body with JSON path.
+     */
+    expectBodyPath(path, expected) {
+        this.config.assertions.push((response) => {
+            const value = getValueByPath(response.body, path);
+            if (!deepEqual(value, expected)) {
+                throw new Error(`Expected body.${path} to be ${JSON.stringify(expected)}, ` +
+                    `but got ${JSON.stringify(value)}`);
+            }
+        });
+        return this;
+    }
+    /**
+     * Assert response headers.
+     */
+    expectHeaders(headers) {
+        this.config.assertions.push((response) => {
+            for (const [key, expected] of Object.entries(headers)) {
+                const actual = response.headers[key.toLowerCase()];
+                if (expected instanceof RegExp) {
+                    if (!expected.test(actual)) {
+                        throw new Error(`Expected header "${key}" to match ${expected}, but got "${actual}"`);
+                    }
+                }
+                else if (actual !== expected) {
+                    throw new Error(`Expected header "${key}" to be "${expected}", but got "${actual}"`);
+                }
+            }
+        });
+        return this;
+    }
+    /**
+     * Assert a single header.
+     */
+    expectHeader(key, value) {
+        return this.expectHeaders({ [key]: value });
+    }
+    /**
+     * Assert response time (UNIQUE ExpressoTS feature).
+     */
+    expectTime(options) {
+        this.config.expectedTime = options;
+        this.config.assertions.push((response) => {
+            const time = response.time;
+            if (options.lessThan !== undefined && time >= options.lessThan) {
+                throw new Error(`Expected response time < ${options.lessThan}ms, but got ${time}ms`);
+            }
+            if (options.greaterThan !== undefined && time <= options.greaterThan) {
+                throw new Error(`Expected response time > ${options.greaterThan}ms, but got ${time}ms`);
+            }
+            if (options.between !== undefined) {
+                const [min, max] = options.between;
+                if (time < min || time > max) {
+                    throw new Error(`Expected response time between ${min}ms and ${max}ms, but got ${time}ms`);
+                }
+            }
+        });
+        return this;
+    }
+    /**
+     * Assert content type.
+     */
+    expectContentType(type) {
+        this.config.assertions.push((response) => {
+            const contentType = response.contentType;
+            if (type instanceof RegExp) {
+                if (!type.test(contentType)) {
+                    throw new Error(`Expected content-type to match ${type}, but got "${contentType}"`);
+                }
+            }
+            else if (!contentType.includes(type)) {
+                throw new Error(`Expected content-type to contain "${type}", but got "${contentType}"`);
+            }
+        });
+        return this;
+    }
+    /**
+     * Custom assertion.
+     */
+    expect(assertion) {
+        this.config.assertions.push(assertion);
+        return this;
+    }
+    /**
+     * Execute the request and return the response.
+     */
+    async execute() {
+        const startTime = Date.now();
+        // Build URL with query parameters
+        let url = `${this.baseUrl}${this.config.path}`;
+        const queryParams = Object.entries(this.config.query);
+        if (queryParams.length > 0) {
+            const searchParams = new URLSearchParams();
+            for (const [key, value] of queryParams) {
+                searchParams.append(key, String(value));
+            }
+            url += `?${searchParams.toString()}`;
+        }
+        // Prepare request options
+        const fetchOptions = {
+            method: this.config.method,
+            headers: this.config.headers,
+        };
+        // Add body if present
+        if (this.config.body !== undefined) {
+            fetchOptions.body =
+                typeof this.config.body === "string"
+                    ? this.config.body
+                    : JSON.stringify(this.config.body);
+        }
+        // Create abort controller for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        // Prevent timer from keeping Jest alive
+        const timerWithUnref = timeoutId;
+        if (typeof timerWithUnref.unref === "function") {
+            timerWithUnref.unref();
+        }
+        fetchOptions.signal = controller.signal;
+        try {
+            const fetchResponse = await fetch(url, fetchOptions);
+            const endTime = Date.now();
+            const responseTime = endTime - startTime;
+            clearTimeout(timeoutId);
+            // Parse response
+            const text = await fetchResponse.text();
+            let body;
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                body = text;
+            }
+            // Build headers object
+            const headers = {};
+            fetchResponse.headers.forEach((value, key) => {
+                headers[key.toLowerCase()] = value;
+            });
+            // Create response object
+            const response = {
+                status: fetchResponse.status,
+                statusText: fetchResponse.statusText,
+                headers,
+                body,
+                text,
+                time: responseTime,
+                contentType: headers["content-type"] || "",
+                ok: fetchResponse.ok,
+                redirect: fetchResponse.status >= 300 && fetchResponse.status < 400,
+                clientError: fetchResponse.status >= 400 && fetchResponse.status < 500,
+                serverError: fetchResponse.status >= 500,
+            };
+            // Run assertions
+            for (const assertion of this.config.assertions) {
+                assertion(response);
+            }
+            return response;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new Error(`Request timed out after ${this.config.timeout}ms`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Alias for execute().
+     */
+    end() {
+        return this.execute();
+    }
+}
+/**
+ * Create a fluent request builder for a base URL.
+ */
+export function createFluentRequest(baseUrl) {
+    return {
+        get(path) {
+            return new FluentRequestImpl(baseUrl, "GET", path);
+        },
+        post(path) {
+            return new FluentRequestImpl(baseUrl, "POST", path);
+        },
+        put(path) {
+            return new FluentRequestImpl(baseUrl, "PUT", path);
+        },
+        patch(path) {
+            return new FluentRequestImpl(baseUrl, "PATCH", path);
+        },
+        delete(path) {
+            return new FluentRequestImpl(baseUrl, "DELETE", path);
+        },
+        head(path) {
+            return new FluentRequestImpl(baseUrl, "HEAD", path);
+        },
+        options(path) {
+            return new FluentRequestImpl(baseUrl, "OPTIONS", path);
+        },
+        request(method, path) {
+            return new FluentRequestImpl(baseUrl, method, path);
+        },
+    };
+}
+/**
+ * Create a standalone request builder from an app or URL.
+ *
+ * @example
+ * ```typescript
+ * // With app
+ * const response = await request(app).get("/users").execute();
+ *
+ * // With URL
+ * const response = await request("http://localhost:3000").get("/users").execute();
+ * ```
+ */
+export function request(appOrUrl) {
+    const baseUrl = typeof appOrUrl === "string" ? appOrUrl : appOrUrl.baseUrl;
+    return createFluentRequest(baseUrl);
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Deep partial match - checks if actual contains all properties of expected.
+ */
+function deepPartialMatch(actual, expected) {
+    if (expected === actual)
+        return true;
+    if (typeof expected !== "object" || expected === null) {
+        return expected === actual;
+    }
+    if (typeof actual !== "object" || actual === null) {
+        return false;
+    }
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual))
+            return false;
+        if (expected.length !== actual.length)
+            return false;
+        return expected.every((item, index) => deepPartialMatch(actual[index], item));
+    }
+    // Object comparison
+    for (const key of Object.keys(expected)) {
+        if (!(key in actual))
+            return false;
+        if (!deepPartialMatch(actual[key], expected[key])) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Deep equality check.
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== "object" || a === null || b === null) {
+        return a === b;
+    }
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((item, index) => deepEqual(item, b[index]));
+    }
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every((key) => deepEqual(a[key], b[key]));
+}
+/**
+ * Get value from object by dot-notation path.
+ */
+function getValueByPath(obj, path) {
+    const parts = path.split(".");
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        // Handle array indexing: "users[0]" or "users.0"
+        const arrayMatch = part.match(/^(\w+)\[(\d+)\]$/);
+        if (arrayMatch) {
+            const [, key, index] = arrayMatch;
+            current = current[key];
+            if (Array.isArray(current)) {
+                current = current[parseInt(index, 10)];
+            }
+            else {
+                return undefined;
+            }
+        }
+        else {
+            current = current[part];
+        }
+    }
+    return current;
+}

package/lib/esm/testing/index.js

@@ -0,0 +1,102 @@
+/**
+ * ExpressoTS Testing Module
+ *
+ * @module testing
+ *
+ * Comprehensive testing utilities for ExpressoTS applications.
+ * Provides zero-config setup, smart mocks, fluent HTTP testing,
+ * snapshot testing, and built-in load testing.
+ *
+ * UNIQUE FEATURES (No other framework has these!):
+ * - Zero-config test app creation
+ * - Smart mocking with auto-discovery
+ * - Fluent HTTP testing API (better than supertest)
+ * - API snapshot testing
+ * - Built-in load testing with percentile metrics
+ * - Database testing utilities
+ * - Request context mocking
+ *
+ * @example
+ * ```typescript
+ * // Zero-config test setup
+ * import { createTestApp } from "@expressots/testing";
+ *
+ * describe("UserController", () => {
+ *   let app, request;
+ *
+ *   beforeAll(async () => {
+ *     ({ app, request } = await createTestApp(App));
+ *   });
+ *
+ *   test("GET /users returns user list", async () => {
+ *     const response = await request
+ *       .get("/users")
+ *       .expectStatus(200)
+ *       .expectBody((body) => body.length > 0)
+ *       .expectTime({ lessThan: 100 })
+ *       .execute();
+ *
+ *     expect(response.body).toHaveLength(2);
+ *   });
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Smart mocking
+ * import { mockProvider } from "@expressots/testing";
+ *
+ * test("UserService creates user", async () => {
+ *   const { service, mocks } = mockProvider(UserService, {
+ *     mocks: {
+ *       UserRepository: {
+ *         create: jest.fn().mockResolvedValue({ id: 1, name: "John" })
+ *       }
+ *     }
+ *   });
+ *
+ *   const user = await service.createUser({ name: "John" });
+ *   expect(user.id).toBe(1);
+ *   expect(mocks.UserRepository.create).toHaveBeenCalled();
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Load testing (UNIQUE!)
+ * import { loadTest } from "@expressots/testing";
+ *
+ * test("handles 1000 concurrent requests", async () => {
+ *   const results = await loadTest(app, {
+ *     endpoint: "/users",
+ *     concurrent: 1000,
+ *     duration: "10s",
+ *     assertions: {
+ *       maxErrorRate: 0.01,
+ *       maxP95: 200
+ *     }
+ *   });
+ *
+ *   expect(results.assertionsPassed).toBe(true);
+ *   expect(results.p95ResponseTime).toBeLessThan(200);
+ * });
+ * ```
+ */
+// Core interfaces and types
+export * from "./testing.interfaces.js";
+// Test app creation
+export { createTestApp, cleanupAllTestApps, getActiveTestAppCount, } from "./create-test-app.js";
+// Smart mocking
+export { mockProvider, createMock, createMockObject, spyOn, } from "./mock-provider.js";
+// Fluent HTTP testing
+export { createFluentRequest, request } from "./fluent-request.js";
+// Snapshot testing
+export { snapshotRequest, toMatchApiSnapshot } from "./snapshot-request.js";
+// Load testing (UNIQUE!)
+export { loadTest, benchmark, stressTest } from "./load-test.js";
+// Database testing
+export { createTestDatabase, createFixtureFactory, fixture, } from "./create-test-database.js";
+// Request context mocking
+export { mockContext, mockExecutionContext, mockNextFunction, mockReqRes, } from "./mock-context.js";
+// Custom matchers
+export { expressoTSMatchers, setupExpressoTSMatchers } from "./matchers.js";