@typokit/testing 0.1.4

package/src/integration-suite.ts

@@ -0,0 +1,191 @@
+// @typokit/testing — Integration Test Suite
+
+import type { TypoKitApp } from "@typokit/core";
+import type { TestClient } from "./index.js";
+import { createTestClient } from "./index.js";
+
+// ─── In-Memory Database ─────────────────────────────────────
+
+/** A simple in-memory database for integration testing */
+export interface InMemoryDatabase {
+  /** Insert a record into a table */
+  insert(table: string, record: Record<string, unknown>): void;
+
+  /** Find all records in a table */
+  findAll(table: string): Record<string, unknown>[];
+
+  /** Find a record by id field */
+  findById(table: string, id: string): Record<string, unknown> | undefined;
+
+  /** Delete all records from a table */
+  clearTable(table: string): void;
+
+  /** Delete all records from all tables */
+  clear(): void;
+
+  /** Get the list of table names */
+  tables(): string[];
+}
+
+function createInMemoryDatabase(): InMemoryDatabase {
+  const store = new Map<string, Record<string, unknown>[]>();
+
+  return {
+    insert(table: string, record: Record<string, unknown>): void {
+      if (!store.has(table)) {
+        store.set(table, []);
+      }
+      // Clone the record to prevent shared references
+      store.get(table)!.push({ ...record });
+    },
+
+    findAll(table: string): Record<string, unknown>[] {
+      return (store.get(table) ?? []).map((r) => ({ ...r }));
+    },
+
+    findById(table: string, id: string): Record<string, unknown> | undefined {
+      const records = store.get(table);
+      if (!records) return undefined;
+      const found = records.find((r) => r["id"] === id);
+      return found ? { ...found } : undefined;
+    },
+
+    clearTable(table: string): void {
+      store.delete(table);
+    },
+
+    clear(): void {
+      store.clear();
+    },
+
+    tables(): string[] {
+      return [...store.keys()];
+    },
+  };
+}
+
+// ─── Seed Data ──────────────────────────────────────────────
+
+/** A seed function populates an in-memory database with test data */
+export type SeedFn = (db: InMemoryDatabase) => void;
+
+const seedRegistry = new Map<string, SeedFn>();
+
+/** Register a named seed data fixture */
+export function registerSeed(name: string, seed: SeedFn): void {
+  seedRegistry.set(name, seed);
+}
+
+/** Get a registered seed function by name */
+export function getSeed(name: string): SeedFn | undefined {
+  return seedRegistry.get(name);
+}
+
+// ─── Integration Suite ──────────────────────────────────────
+
+/** Options for creating an integration test suite */
+export interface IntegrationSuiteOptions {
+  /** Whether to spin up an in-memory database (default: false) */
+  database?: boolean;
+
+  /** Name of a registered seed data fixture to apply */
+  seed?: string;
+}
+
+/** An integration test suite with managed server and database lifecycle */
+export interface IntegrationSuite {
+  /** Start the server and seed the database */
+  setup(): Promise<void>;
+
+  /** Stop the server and clean up */
+  teardown(): Promise<void>;
+
+  /** The typed test client (available after setup) */
+  readonly client: TestClient;
+
+  /** The in-memory database (null if database option is false) */
+  readonly db: InMemoryDatabase | null;
+}
+
+/**
+ * Create an integration test suite for a TypoKit application.
+ *
+ * Sets up an isolated server and optionally an in-memory database
+ * with seeded test data. Each call creates a fully independent
+ * instance with no shared mutable state.
+ *
+ * ```ts
+ * const suite = createIntegrationSuite(app, {
+ *   database: true,
+ *   seed: "users",
+ * });
+ *
+ * // In beforeEach / setup
+ * await suite.setup();
+ *
+ * // In tests
+ * const res = await suite.client.get("/users");
+ *
+ * // In afterEach / teardown
+ * await suite.teardown();
+ * ```
+ */
+export function createIntegrationSuite(
+  app: TypoKitApp,
+  options: IntegrationSuiteOptions = {},
+): IntegrationSuite {
+  let client: TestClient | null = null;
+  let db: InMemoryDatabase | null = null;
+
+  const suite: IntegrationSuite = {
+    async setup(): Promise<void> {
+      // Create a fresh in-memory database if requested
+      if (options.database) {
+        db = createInMemoryDatabase();
+
+        // Apply seed data if specified
+        if (options.seed) {
+          const seedFn = getSeed(options.seed);
+          if (!seedFn) {
+            throw new Error(
+              `Unknown seed fixture: "${options.seed}". Register it with registerSeed() first.`,
+            );
+          }
+          seedFn(db);
+        }
+      }
+
+      // Start the server and create a test client
+      client = await createTestClient(app);
+    },
+
+    async teardown(): Promise<void> {
+      // Close the test client / server
+      if (client) {
+        await client.close();
+        client = null;
+      }
+
+      // Clear the database
+      if (db) {
+        db.clear();
+        db = null;
+      }
+    },
+
+    get client(): TestClient {
+      if (!client) {
+        throw new Error(
+          "Integration suite not set up. Call suite.setup() first.",
+        );
+      }
+      return client;
+    },
+
+    get db(): InMemoryDatabase | null {
+      return db;
+    },
+  };
+
+  return suite;
+}

package/src/schema-matcher.test.ts

@@ -0,0 +1,293 @@
+import { describe, it, expect, beforeEach } from "@rstest/core";
+import {
+  toMatchSchema,
+  registerSchemaValidators,
+  clearSchemaValidators,
+  matchSchema,
+  getSchemaValidator,
+} from "./schema-matcher.js";
+import type { ValidatorFn, ValidationFieldError } from "@typokit/types";
+
+// ─── Test Helpers ─────────────────────────────────────────────
+
+/** Creates a validator that passes for objects with required PublicUser fields */
+function createPublicUserValidator(): ValidatorFn {
+  return (input: unknown) => {
+    if (typeof input !== "object" || input === null) {
+      return {
+        success: false,
+        errors: [
+          { path: "$", expected: "object", actual: typeof input },
+        ] as ValidationFieldError[],
+      };
+    }
+
+    const obj = input as Record<string, unknown>;
+    const errors: ValidationFieldError[] = [];
+
+    if (typeof obj["id"] !== "string") {
+      errors.push({ path: "id", expected: "string", actual: obj["id"] });
+    }
+    if (typeof obj["name"] !== "string") {
+      errors.push({ path: "name", expected: "string", actual: obj["name"] });
+    }
+    if (typeof obj["email"] !== "string") {
+      errors.push({ path: "email", expected: "string", actual: obj["email"] });
+    }
+
+    return {
+      success: errors.length === 0,
+      data: errors.length === 0 ? input : undefined,
+      errors: errors.length > 0 ? errors : undefined,
+    };
+  };
+}
+
+/** Creates a simple pass/fail validator */
+function createSimpleValidator(
+  fieldName: string,
+  fieldType: string,
+): ValidatorFn {
+  return (input: unknown) => {
+    if (typeof input !== "object" || input === null) {
+      return {
+        success: false,
+        errors: [{ path: "$", expected: "object", actual: typeof input }],
+      };
+    }
+    const obj = input as Record<string, unknown>;
+    if (typeof obj[fieldName] !== fieldType) {
+      return {
+        success: false,
+        errors: [
+          { path: fieldName, expected: fieldType, actual: obj[fieldName] },
+        ],
+      };
+    }
+    return { success: true, data: input };
+  };
+}
+
+// ─── Tests ────────────────────────────────────────────────────
+
+describe("schema-matcher", () => {
+  beforeEach(() => {
+    clearSchemaValidators();
+  });
+
+  describe("registerSchemaValidators / getSchemaValidator", () => {
+    it("should register and retrieve validators", () => {
+      const validator = createPublicUserValidator();
+      registerSchemaValidators({ PublicUser: validator });
+
+      const retrieved = getSchemaValidator("PublicUser");
+      expect(retrieved).toBe(validator);
+    });
+
+    it("should throw when schema not registered", () => {
+      expect(() => getSchemaValidator("Unknown")).toThrow(
+        'Schema "Unknown" not registered',
+      );
+    });
+
+    it("should list available schemas in error message", () => {
+      registerSchemaValidators({
+        PublicUser: createPublicUserValidator(),
+        Post: createSimpleValidator("title", "string"),
+      });
+
+      try {
+        getSchemaValidator("Missing");
+        expect(true).toBe(false); // should not reach
+      } catch (err: unknown) {
+        const msg = (err as Error).message;
+        expect(msg).toContain("PublicUser");
+        expect(msg).toContain("Post");
+      }
+    });
+
+    it("should merge validators when registering multiple times", () => {
+      registerSchemaValidators({ A: createSimpleValidator("a", "string") });
+      registerSchemaValidators({ B: createSimpleValidator("b", "number") });
+
+      expect(() => getSchemaValidator("A")).not.toThrow();
+      expect(() => getSchemaValidator("B")).not.toThrow();
+    });
+  });
+
+  describe("clearSchemaValidators", () => {
+    it("should remove all registered validators", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+      clearSchemaValidators();
+
+      expect(() => getSchemaValidator("PublicUser")).toThrow();
+    });
+  });
+
+  describe("matchSchema (core logic)", () => {
+    it("should pass for a valid PublicUser", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      const validUser = { id: "u1", name: "Alice", email: "alice@example.com" };
+      const result = matchSchema(validUser, "PublicUser");
+
+      expect(result.pass).toBe(true);
+      expect(result.message).toContain("NOT to match");
+    });
+
+    it("should fail for an invalid PublicUser (missing fields)", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      const invalidUser = { id: 123, name: "Alice" }; // id is number, email missing
+      const result = matchSchema(invalidUser, "PublicUser");
+
+      expect(result.pass).toBe(false);
+      expect(result.message).toContain("validation failed");
+      expect(result.message).toContain("id");
+      expect(result.message).toContain("email");
+    });
+
+    it("should fail for a non-object value", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      const result = matchSchema("not an object", "PublicUser");
+      expect(result.pass).toBe(false);
+      expect(result.message).toContain("validation failed");
+    });
+
+    it("should include field-level error details", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      const result = matchSchema(
+        { id: 42, name: true, email: null },
+        "PublicUser",
+      );
+      expect(result.pass).toBe(false);
+      expect(result.message).toContain("id");
+      expect(result.message).toContain("expected string");
+      expect(result.message).toContain("name");
+      expect(result.message).toContain("email");
+    });
+
+    it("should show schema name in pass message", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      const result = matchSchema(
+        { id: "1", name: "A", email: "a@b.com" },
+        "PublicUser",
+      );
+      expect(result.message).toContain('"PublicUser"');
+    });
+
+    it("should show schema name in fail message", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      const result = matchSchema({}, "PublicUser");
+      expect(result.message).toContain('"PublicUser"');
+    });
+  });
+
+  describe("toMatchSchema (framework matcher)", () => {
+    it("should return pass: true for valid data", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      const result = toMatchSchema.call(
+        {},
+        { id: "u1", name: "Alice", email: "alice@example.com" },
+        "PublicUser",
+      );
+
+      expect(result.pass).toBe(true);
+      expect(typeof result.message).toBe("function");
+    });
+
+    it("should return pass: false for invalid data", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      const result = toMatchSchema.call({}, { wrong: "data" }, "PublicUser");
+
+      expect(result.pass).toBe(false);
+      expect(result.message()).toContain("validation failed");
+    });
+
+    it("should provide message as a function (Jest/Vitest API)", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      const result = toMatchSchema.call(
+        {},
+        { id: "1", name: "A", email: "a@b" },
+        "PublicUser",
+      );
+
+      // Jest/Vitest expect message to be a function
+      expect(typeof result.message).toBe("function");
+      expect(typeof result.message()).toBe("string");
+    });
+
+    it("should work with .not context (isNot)", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      // When .not is used, pass: true means the assertion fails
+      const result = toMatchSchema.call(
+        { isNot: true },
+        { id: "1", name: "A", email: "a@b.com" },
+        "PublicUser",
+      );
+
+      // pass is true (value matches), so .not would make it fail
+      expect(result.pass).toBe(true);
+      expect(result.message()).toContain("NOT to match");
+    });
+
+    it("should work without this context", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      const result = toMatchSchema(
+        { id: "1", name: "A", email: "a@b.com" },
+        "PublicUser",
+      );
+
+      expect(result.pass).toBe(true);
+    });
+  });
+
+  describe("expect.extend integration", () => {
+    it("should work with expect.extend for passing assertion", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      // Simulate how expect.extend works in all three frameworks
+      expect.extend({ toMatchSchema });
+
+      const validUser = { id: "u1", name: "Alice", email: "alice@example.com" };
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (expect(validUser) as any).toMatchSchema("PublicUser");
+    });
+
+    it("should work with expect.extend for failing assertion", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      expect.extend({ toMatchSchema });
+
+      const invalidUser = { wrong: "data" };
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (expect(invalidUser) as any).toMatchSchema("PublicUser");
+        // Should not reach here
+        expect(true).toBe(false);
+      } catch (err: unknown) {
+        const msg = (err as Error).message;
+        expect(msg).toContain("validation failed");
+      }
+    });
+
+    it("should work with .not for negated assertions", () => {
+      registerSchemaValidators({ PublicUser: createPublicUserValidator() });
+
+      expect.extend({ toMatchSchema });
+
+      const invalidUser = { wrong: "data" };
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (expect(invalidUser) as any).not.toMatchSchema("PublicUser");
+    });
+  });
+});

package/src/schema-matcher.ts

@@ -0,0 +1,160 @@
+// @typokit/testing — toMatchSchema custom matcher
+// Adapters for Jest, Vitest, and Rstest
+
+import type {
+  ValidatorFn,
+  ValidatorMap,
+  ValidationFieldError,
+} from "@typokit/types";
+
+// ─── Schema Registry ─────────────────────────────────────────
+
+/** Global registry of compiled validators keyed by schema name */
+let validatorRegistry: ValidatorMap = {};
+
+/**
+ * Register compiled validators for use with toMatchSchema().
+ * Call this in your test setup with validators from your build output.
+ *
+ * ```ts
+ * import { registerSchemaValidators } from "@typokit/testing";
+ * registerSchemaValidators({
+ *   PublicUser: (input) => ({ success: true, data: input }),
+ *   CreateUserInput: myTypiaValidator,
+ * });
+ * ```
+ */
+export function registerSchemaValidators(validators: ValidatorMap): void {
+  validatorRegistry = { ...validatorRegistry, ...validators };
+}
+
+/**
+ * Get a validator by schema name. Throws if not registered.
+ */
+export function getSchemaValidator(schemaName: string): ValidatorFn {
+  const validator = validatorRegistry[schemaName];
+  if (!validator) {
+    const available = Object.keys(validatorRegistry);
+    throw new Error(
+      `Schema "${schemaName}" not registered. ` +
+        `Available schemas: ${available.length > 0 ? available.join(", ") : "(none)"}. ` +
+        `Call registerSchemaValidators() in your test setup.`,
+    );
+  }
+  return validator;
+}
+
+/** Clear all registered validators (for test isolation) */
+export function clearSchemaValidators(): void {
+  validatorRegistry = {};
+}
+
+// ─── Matcher Result ──────────────────────────────────────────
+
+/** Result of a schema match operation */
+export interface SchemaMatchResult {
+  pass: boolean;
+  message: string;
+}
+
+// ─── Core Matcher Logic ──────────────────────────────────────
+
+/**
+ * Format validation errors into a human-readable message.
+ */
+function formatErrors(errors: ValidationFieldError[]): string {
+  return errors
+    .map(
+      (e) =>
+        `  • ${e.path}: expected ${e.expected}, received ${JSON.stringify(e.actual)}`,
+    )
+    .join("\n");
+}
+
+/**
+ * Core schema matching logic shared by all framework adapters.
+ */
+export function matchSchema(
+  received: unknown,
+  schemaName: string,
+): SchemaMatchResult {
+  const validator = getSchemaValidator(schemaName);
+  const result = validator(received);
+
+  if (result.success) {
+    return {
+      pass: true,
+      message: `Expected value NOT to match schema "${schemaName}", but it did.`,
+    };
+  }
+
+  const errorDetails =
+    result.errors && result.errors.length > 0
+      ? `\nField errors:\n${formatErrors(result.errors)}`
+      : "";
+
+  return {
+    pass: false,
+    message: `Expected value to match schema "${schemaName}", but validation failed.${errorDetails}`,
+  };
+}
+
+// ─── Jest / Vitest / Rstest Adapter ──────────────────────────
+
+/**
+ * Custom matcher for Jest, Vitest, and Rstest expect() chains.
+ *
+ * All three frameworks share compatible matcher APIs:
+ * - `this.isNot` indicates `.not.toMatchSchema()` usage
+ * - Return `{ pass, message() }` object
+ *
+ * Usage:
+ * ```ts
+ * import { toMatchSchema, registerSchemaValidators } from "@typokit/testing";
+ *
+ * // For Jest:
+ * expect.extend({ toMatchSchema });
+ *
+ * // For Vitest:
+ * expect.extend({ toMatchSchema });
+ *
+ * // For Rstest:
+ * expect.extend({ toMatchSchema });
+ *
+ * // Then in tests:
+ * expect(responseBody).toMatchSchema("PublicUser");
+ * ```
+ */
+export function toMatchSchema(
+  this: { isNot?: boolean } | void,
+  received: unknown,
+  schemaName: string,
+): { pass: boolean; message: () => string } {
+  const result = matchSchema(received, schemaName);
+
+  return {
+    pass: result.pass,
+    message: () => result.message,
+  };
+}
+
+// ─── Type Augmentations ──────────────────────────────────────
+
+/**
+ * Type declaration for extending expect() in Jest, Vitest, and Rstest.
+ *
+ * Users should add to their test setup:
+ * ```ts
+ * declare module "expect" {
+ *   interface AsymmetricMatchers {
+ *     toMatchSchema(schemaName: string): void;
+ *   }
+ *   interface Matchers<R> {
+ *     toMatchSchema(schemaName: string): R;
+ *   }
+ * }
+ * ```
+ */
+export interface SchemaMatchers<R = unknown> {
+  toMatchSchema(schemaName: string): R;
+}