@typokit/testing 0.1.4

package/src/factory.ts

@@ -0,0 +1,248 @@
+// @typokit/testing — Test Factories
+//
+// Type-safe test factories that produce valid/invalid fixture data
+// from TypeMetadata. Deterministic when seeded.
+
+import type { TypeMetadata } from "@typokit/types";
+
+// ─── Seeded PRNG (mulberry32) ─────────────────────────────────
+
+function mulberry32(seed: number): () => number {
+  let s = seed | 0;
+  return () => {
+    s = (s + 0x6d2b79f5) | 0;
+    let t = Math.imul(s ^ (s >>> 15), 1 | s);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// ─── Types ────────────────────────────────────────────────────
+
+/** Options for creating a factory */
+export interface FactoryOptions {
+  /** Seed for deterministic random generation */
+  seed?: number;
+}
+
+/** A test factory that produces typed instances */
+export interface Factory<T> {
+  /** Build a single valid instance with optional field overrides */
+  build(overrides?: Partial<T>): T;
+  /** Build multiple valid instances */
+  buildMany(count: number, overrides?: Partial<T>): T[];
+  /** Build an instance with a specific field set to an invalid value */
+  buildInvalid(field: keyof T & string): T;
+}
+
+// ─── Random Data Generators ───────────────────────────────────
+
+function randomString(rand: () => number, length: number): string {
+  const chars = "abcdefghijklmnopqrstuvwxyz";
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    result += chars[Math.floor(rand() * chars.length)];
+  }
+  return result;
+}
+
+function randomEmail(rand: () => number): string {
+  return `${randomString(rand, 8)}@${randomString(rand, 5)}.com`;
+}
+
+function randomUrl(rand: () => number): string {
+  return `https://${randomString(rand, 8)}.com/${randomString(rand, 4)}`;
+}
+
+function randomUuid(rand: () => number): string {
+  const hex = "0123456789abcdef";
+  const segments = [8, 4, 4, 4, 12];
+  return segments
+    .map((len) => {
+      let s = "";
+      for (let i = 0; i < len; i++) {
+        s += hex[Math.floor(rand() * 16)];
+      }
+      return s;
+    })
+    .join("-");
+}
+
+function randomInt(rand: () => number, min: number, max: number): number {
+  return Math.floor(rand() * (max - min + 1)) + min;
+}
+
+function randomDate(rand: () => number): string {
+  const year = randomInt(rand, 2020, 2030);
+  const month = String(randomInt(rand, 1, 12)).padStart(2, "0");
+  const day = String(randomInt(rand, 1, 28)).padStart(2, "0");
+  return `${year}-${month}-${day}T00:00:00.000Z`;
+}
+
+// ─── Value Generator ──────────────────────────────────────────
+
+function generateValue(
+  type: string,
+  jsdoc: Record<string, string> | undefined,
+  rand: () => number,
+): unknown {
+  const format = jsdoc?.["format"];
+  const minLengthStr = jsdoc?.["minLength"];
+  const maxLengthStr = jsdoc?.["maxLength"];
+  const minStr = jsdoc?.["minimum"];
+  const maxStr = jsdoc?.["maximum"];
+
+  // Check for JSDoc format constraints first
+  if (format === "email") return randomEmail(rand);
+  if (format === "url" || format === "uri") return randomUrl(rand);
+  if (format === "uuid") return randomUuid(rand);
+  if (format === "date" || format === "date-time") return randomDate(rand);
+
+  // String union types like '"a" | "b" | "c"'
+  if (type.includes('" | "') || type.includes("' | '")) {
+    const values = type
+      .split("|")
+      .map((v) => v.trim().replace(/^["']|["']$/g, ""));
+    return values[Math.floor(rand() * values.length)];
+  }
+
+  // Handle base types
+  const baseType = type.replace(/\[\]$/, "");
+  const isArray = type.endsWith("[]");
+
+  const gen = (): unknown => {
+    switch (baseType) {
+      case "string": {
+        const minLen = minLengthStr ? parseInt(minLengthStr, 10) : 5;
+        const maxLen = maxLengthStr ? parseInt(maxLengthStr, 10) : 20;
+        const len = randomInt(rand, minLen, maxLen);
+        return randomString(rand, len);
+      }
+      case "number": {
+        const min = minStr ? parseInt(minStr, 10) : 1;
+        const max = maxStr ? parseInt(maxStr, 10) : 1000;
+        return randomInt(rand, min, max);
+      }
+      case "boolean":
+        return rand() > 0.5;
+      case "Date":
+        return randomDate(rand);
+      default:
+        return randomString(rand, 10);
+    }
+  };
+
+  if (isArray) {
+    const count = randomInt(rand, 1, 3);
+    return Array.from({ length: count }, gen);
+  }
+
+  return gen();
+}
+
+// ─── Invalid Value Generator ──────────────────────────────────
+
+function generateInvalidValue(
+  type: string,
+  jsdoc: Record<string, string> | undefined,
+): unknown {
+  const format = jsdoc?.["format"];
+  const minLengthStr = jsdoc?.["minLength"];
+  const maxStr = jsdoc?.["maximum"];
+  const minStr = jsdoc?.["minimum"];
+
+  if (format === "email") return "not-an-email";
+  if (format === "url" || format === "uri") return "not a url";
+  if (format === "uuid") return "not-a-uuid";
+  if (format === "date" || format === "date-time") return "not-a-date";
+
+  if (type.includes('" | "') || type.includes("' | '")) {
+    return "__invalid_enum_value__";
+  }
+
+  const baseType = type.replace(/\[\]$/, "");
+
+  switch (baseType) {
+    case "string": {
+      if (minLengthStr) {
+        const minLen = parseInt(minLengthStr, 10);
+        return minLen > 1 ? "x" : "";
+      }
+      return "";
+    }
+    case "number": {
+      if (maxStr) return parseInt(maxStr, 10) + 100;
+      if (minStr) return parseInt(minStr, 10) - 100;
+      return null;
+    }
+    case "boolean":
+      return "not-a-boolean";
+    default:
+      return null;
+  }
+}
+
+// ─── createFactory ────────────────────────────────────────────
+
+/**
+ * Create a type-safe test factory from TypeMetadata.
+ *
+ * ```ts
+ * const userFactory = createFactory<User>(userMetadata, { seed: 42 });
+ * const user = userFactory.build();
+ * const admin = userFactory.build({ role: "admin" });
+ * const invalid = userFactory.buildInvalid("email");
+ * ```
+ */
+export function createFactory<T>(
+  metadata: TypeMetadata,
+  options: FactoryOptions = {},
+): Factory<T> {
+  const seed = options.seed ?? 12345;
+
+  function buildOne(rand: () => number, overrides?: Partial<T>): T {
+    const result: Record<string, unknown> = {};
+
+    for (const [key, prop] of Object.entries(metadata.properties)) {
+      if (prop.optional && rand() > 0.7) {
+        continue; // skip some optional fields
+      }
+      result[key] = generateValue(prop.type, prop.jsdoc, rand);
+    }
+
+    if (overrides) {
+      Object.assign(result, overrides);
+    }
+
+    return result as T;
+  }
+
+  return {
+    build(overrides?: Partial<T>): T {
+      const rand = mulberry32(seed);
+      return buildOne(rand, overrides);
+    },
+
+    buildMany(count: number, overrides?: Partial<T>): T[] {
+      const rand = mulberry32(seed);
+      const results: T[] = [];
+      for (let i = 0; i < count; i++) {
+        results.push(buildOne(rand, overrides));
+      }
+      return results;
+    },
+
+    buildInvalid(field: keyof T & string): T {
+      const rand = mulberry32(seed);
+      const instance = buildOne(rand);
+      const prop = metadata.properties[field];
+      if (prop) {
+        (instance as Record<string, unknown>)[field] = generateInvalidValue(
+          prop.type,
+          prop.jsdoc,
+        );
+      }
+      return instance;
+    },
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,275 @@
+// @typokit/testing — Integration Tests
+
+import { describe, it, expect } from "@rstest/core";
+import type {
+  CompiledRoute,
+  CompiledRouteTable,
+  HandlerMap,
+  MiddlewareChain,
+  RouteContract,
+  TypoKitRequest,
+  TypoKitResponse,
+} from "@typokit/types";
+import { createApp } from "@typokit/core";
+import { nativeServer } from "@typokit/server-native";
+import { createTestClient } from "./index.js";
+
+// ─── Test Helpers ────────────────────────────────────────────
+
+function makeRouteTable(): CompiledRouteTable {
+  const root: CompiledRoute = {
+    segment: "",
+    handlers: {
+      GET: { ref: "root#index", middleware: [] },
+    },
+    children: {
+      users: {
+        segment: "users",
+        handlers: {
+          GET: { ref: "users#list", middleware: [] },
+          POST: { ref: "users#create", middleware: [] },
+        },
+        paramChild: {
+          segment: ":id",
+          paramName: "id",
+          handlers: {
+            GET: { ref: "users#get", middleware: [] },
+            PUT: { ref: "users#update", middleware: [] },
+            DELETE: { ref: "users#delete", middleware: [] },
+          },
+        },
+      },
+      echo: {
+        segment: "echo",
+        handlers: {
+          POST: { ref: "echo#post", middleware: [] },
+        },
+      },
+    },
+  };
+  return root;
+}
+
+function makeHandlerMap(): HandlerMap {
+  const users = [
+    { id: "1", name: "Alice" },
+    { id: "2", name: "Bob" },
+  ];
+
+  return {
+    "root#index": async (): Promise<TypoKitResponse> => ({
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: { message: "Hello, TypoKit!" },
+    }),
+    "users#list": async (req: TypoKitRequest): Promise<TypoKitResponse> => {
+      const limit = req.query["limit"];
+      const data = limit ? users.slice(0, Number(limit)) : users;
+      return {
+        status: 200,
+        headers: { "content-type": "application/json" },
+        body: { data },
+      };
+    },
+    "users#create": async (req: TypoKitRequest): Promise<TypoKitResponse> => {
+      const newUser = req.body as { name: string };
+      return {
+        status: 201,
+        headers: { "content-type": "application/json" },
+        body: { id: "3", name: newUser.name },
+      };
+    },
+    "users#get": async (req: TypoKitRequest): Promise<TypoKitResponse> => {
+      const user = users.find((u) => u.id === req.params["id"]);
+      if (!user) {
+        return {
+          status: 404,
+          headers: { "content-type": "application/json" },
+          body: { error: "Not Found" },
+        };
+      }
+      return {
+        status: 200,
+        headers: { "content-type": "application/json" },
+        body: user,
+      };
+    },
+    "users#update": async (req: TypoKitRequest): Promise<TypoKitResponse> => {
+      const updates = req.body as { name: string };
+      return {
+        status: 200,
+        headers: { "content-type": "application/json" },
+        body: { id: req.params["id"], name: updates.name },
+      };
+    },
+    "users#delete": async (_req: TypoKitRequest): Promise<TypoKitResponse> => ({
+      status: 204,
+      headers: {},
+      body: null,
+    }),
+    "echo#post": async (req: TypoKitRequest): Promise<TypoKitResponse> => ({
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        "x-custom": (req.headers["x-custom"] as string) ?? "",
+      },
+      body: { echo: req.body },
+    }),
+  };
+}
+
+function createTestApp() {
+  const adapter = nativeServer();
+  const routeTable = makeRouteTable();
+  const handlerMap = makeHandlerMap();
+  const middlewareChain: MiddlewareChain = { entries: [] };
+
+  adapter.registerRoutes(routeTable, handlerMap, middlewareChain);
+
+  return createApp({
+    server: adapter,
+    routes: [],
+  });
+}
+
+// ─── Tests ───────────────────────────────────────────────────
+
+describe("createTestClient", () => {
+  it("should start the app and return a client with baseUrl", async () => {
+    const app = createTestApp();
+    const client = await createTestClient(app);
+    try {
+      expect(client.baseUrl).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
+    } finally {
+      await client.close();
+    }
+  });
+
+  it("should GET / and return JSON body", async () => {
+    const app = createTestApp();
+    const client = await createTestClient(app);
+    try {
+      const res = await client.get<{ message: string }>("/");
+      expect(res.status).toBe(200);
+      expect(res.body).toEqual({ message: "Hello, TypoKit!" });
+      expect(res.headers["content-type"]).toContain("application/json");
+    } finally {
+      await client.close();
+    }
+  });
+
+  it("should GET /users and list users", async () => {
+    const app = createTestApp();
+    const client = await createTestClient(app);
+    try {
+      const res = await client.get<{
+        data: Array<{ id: string; name: string }>;
+      }>("/users");
+      expect(res.status).toBe(200);
+      expect(res.body.data).toHaveLength(2);
+      expect(res.body.data[0].name).toBe("Alice");
+    } finally {
+      await client.close();
+    }
+  });
+
+  it("should support query parameters", async () => {
+    const app = createTestApp();
+    const client = await createTestClient(app);
+    try {
+      const res = await client.get<{
+        data: Array<{ id: string; name: string }>;
+      }>("/users", { query: { limit: "1" } });
+      expect(res.status).toBe(200);
+      expect(res.body.data).toHaveLength(1);
+    } finally {
+      await client.close();
+    }
+  });
+
+  it("should POST and create a resource", async () => {
+    const app = createTestApp();
+    const client = await createTestClient(app);
+    try {
+      const res = await client.post<{ id: string; name: string }>("/users", {
+        body: { name: "Charlie" },
+      });
+      expect(res.status).toBe(201);
+      expect(res.body.name).toBe("Charlie");
+      expect(res.body.id).toBe("3");
+    } finally {
+      await client.close();
+    }
+  });
+
+  it("should PUT to update a resource", async () => {
+    const app = createTestApp();
+    const client = await createTestClient(app);
+    try {
+      const res = await client.put<{ id: string; name: string }>("/users/1", {
+        body: { name: "Alice Updated" },
+      });
+      expect(res.status).toBe(200);
+      expect(res.body.name).toBe("Alice Updated");
+    } finally {
+      await client.close();
+    }
+  });
+
+  it("should DELETE a resource", async () => {
+    const app = createTestApp();
+    const client = await createTestClient(app);
+    try {
+      const res = await client.delete("/users/1");
+      expect(res.status).toBe(204);
+    } finally {
+      await client.close();
+    }
+  });
+
+  it("should pass custom headers", async () => {
+    const app = createTestApp();
+    const client = await createTestClient(app);
+    try {
+      const res = await client.post<{ echo: unknown }>("/echo", {
+        body: { test: true },
+        headers: { "x-custom": "my-value" },
+      });
+      expect(res.status).toBe(200);
+      expect(res.headers["x-custom"]).toBe("my-value");
+      expect(res.body.echo).toEqual({ test: true });
+    } finally {
+      await client.close();
+    }
+  });
+
+  it("should return 404 for unknown routes", async () => {
+    const app = createTestApp();
+    const client = await createTestClient(app);
+    try {
+      const res = await client.get("/nonexistent");
+      expect(res.status).toBe(404);
+    } finally {
+      await client.close();
+    }
+  });
+
+  it("should support contract-typed request method", async () => {
+    const app = createTestApp();
+    const client = await createTestClient(app);
+    try {
+      const res = await client.request<
+        RouteContract<
+          void,
+          void,
+          void,
+          { data: Array<{ id: string; name: string }> }
+        >
+      >("GET", "/users");
+      expect(res.status).toBe(200);
+      expect(res.body.data).toHaveLength(2);
+    } finally {
+      await client.close();
+    }
+  });
+});