nuxt-api-contract 0.2.0 → 0.3.0

package/README.md

@@ -282,10 +282,75 @@ expect(error).toBeNull()
 expect(data.id).toBe('1')
 ```
 
-Validation → handler → response-validation run exactly like in production.
-See `test/integration/playground.test.ts` for full-stack tests with
+`callContract` runs validation → handler → response-validation exactly like
+production. See `test/integration/playground.test.ts` for full-stack tests with
 `@nuxt/test-utils`.
 
+### Contract test suites
+
+`testContract()` wraps a contract + handler into an assertion suite. It is
+framework-agnostic (works with Vitest, Jest, `node:assert` — any runner that
+treats thrown errors as failures):
+
+```ts
+import { testContract } from 'nuxt-api-contract/testing'
+
+const suite = testContract(GetUser, handler)
+
+it('returns the user', async () => {
+  const data = await suite.expectSuccess({ params: { id: '1' } })
+  expect(data.name).toBe('John')
+})
+
+it('returns 404 for missing user', async () => {
+  const error = await suite.expectError(
+    { params: { id: 'missing' } },
+    'USER_NOT_FOUND',
+    404,
+  )
+})
+```
+
+Available assertions:
+
+| method | meaning |
+| --- | --- |
+| `expectSuccess(input?)` | call succeeds; returns typed response data |
+| `expectError(input?, code?, statusCode?)` | call fails with (optionally) the given code/status |
+| `expectValidationError(input?, issuePaths?)` | fails with `VALIDATION_ERROR`; optionally checks issue paths |
+| `expectResponseValidationError(input, badResponse)` | handler returns bad data caught by response validation |
+| `validateResponse(value)` | validates an arbitrary value against the contract's response schema |
+
+### Contract coverage
+
+Record which registered contracts are exercised in tests and print a report:
+
+```ts
+import {
+  startContractCoverage,
+  stopContractCoverage,
+  formatContractCoverage,
+} from 'nuxt-api-contract/testing'
+
+beforeAll(() => startContractCoverage())
+afterAll(() => console.log(formatContractCoverage(stopContractCoverage())))
+```
+
+Output:
+
+```
+Contract coverage
+  5/6 contracts covered (83%)
+Covered:
+  ✓ GET    /api/users/:id                    3 ok
+  ✓ POST   /api/users                        2 ok (1 failed)
+Uncovered:
+  ✗ DELETE /api/users/:id  (DeleteUser)
+```
+
+Coverage is driven by the same `callContract` pipeline, so it works for both
+unit tests and integration tests.
+
 ## DevTools
 
 When `apiContract.devtools` is enabled in development, a panel lists all

package/dist/chunks/server.mjs

@@ -1,10 +1,9 @@
 import { createServer } from 'node:http';
-import { B as BUILT_IN_ERROR_CODES, A as ApiError, s as serializeApiError } from '../shared/nuxt-api-contract.obS6uV8A.mjs';
-import { v as validateContractInput, a as validateContractResponse } from '../shared/nuxt-api-contract.DDpgZj2g.mjs';
-import { g as generateMockResponse } from '../shared/nuxt-api-contract.Bd2Y7Lx0.mjs';
+import { B as BUILT_IN_ERROR_CODES, A as ApiError, s as serializeApiError } from '../shared/nuxt-api-contract.CHdRLlU7.mjs';
+import { v as validateContractInput, a as validateContractResponse } from '../shared/nuxt-api-contract.CAIOgncy.mjs';
+import { g as generateMockResponse } from '../shared/nuxt-api-contract.BWgzVTNN.mjs';
 import 'zod';
 import '../shared/nuxt-api-contract.DCAU2j7t.mjs';
-import '../shared/nuxt-api-contract.V15soI_f.mjs';
 
 function pathToRegex(path) {
   const names = [];

package/dist/client.mjs

@@ -1,5 +1,4 @@
-export { b as buildRequestPath, c as clearContractRegistry, d as defineApiContract, g as getContractByName, a as getContractMock, i as isApiContract, l as listRegisteredContracts, m as mockContract, r as registerContract } from './shared/nuxt-api-contract.V15soI_f.mjs';
-export { A as ApiError, B as BUILT_IN_ERROR_CODES, c as createApiError, i as isApiError, p as parseApiErrorPayload, s as serializeApiError, t as toApiError } from './shared/nuxt-api-contract.obS6uV8A.mjs';
+export { A as ApiError, B as BUILT_IN_ERROR_CODES, b as buildRequestPath, c as clearContractRegistry, a as createApiError, d as defineApiContract, g as getContractByName, e as getContractMock, i as isApiContract, f as isApiError, l as listRegisteredContracts, m as mockContract, p as parseApiErrorPayload, r as registerContract, s as serializeApiError, t as toApiError } from './shared/nuxt-api-contract.CHdRLlU7.mjs';
 export { f as formatValidationMessage, s as sanitizeIssues, t as toValidationIssues } from './shared/nuxt-api-contract.DCAU2j7t.mjs';
 export { s as serializeQuery, a as serializeQueryValue, b as stableStringify } from './shared/nuxt-api-contract.Dr4tPqGB.mjs';
-export { a as autoMockContract, g as generateMockResponse } from './shared/nuxt-api-contract.Bd2Y7Lx0.mjs';
+export { a as autoMockContract, g as generateMockResponse } from './shared/nuxt-api-contract.BWgzVTNN.mjs';

package/dist/composables.mjs

@@ -1,6 +1,5 @@
 import { useAsyncData, useNuxtApp, useRequestEvent } from '#imports';
-import { b as buildRequestPath } from './shared/nuxt-api-contract.V15soI_f.mjs';
-import { p as parseApiErrorPayload, A as ApiError, t as toApiError } from './shared/nuxt-api-contract.obS6uV8A.mjs';
+import { b as buildRequestPath, p as parseApiErrorPayload, A as ApiError, t as toApiError } from './shared/nuxt-api-contract.CHdRLlU7.mjs';
 import { b as stableStringify, s as serializeQuery } from './shared/nuxt-api-contract.Dr4tPqGB.mjs';
 
 function createRequestKey(contract, options) {

package/dist/mock.mjs

@@ -1,8 +1,7 @@
-export { a as autoMockContract, c as createRng, g as generateMockResponse, b as generateMockValue } from './shared/nuxt-api-contract.Bd2Y7Lx0.mjs';
+export { a as autoMockContract, c as createRng, g as generateMockResponse, b as generateMockValue } from './shared/nuxt-api-contract.BWgzVTNN.mjs';
 export { buildMockMatchers, createMockServer, startMockServer } from './chunks/server.mjs';
-import './shared/nuxt-api-contract.V15soI_f.mjs';
+import './shared/nuxt-api-contract.CHdRLlU7.mjs';
 import 'node:http';
-import './shared/nuxt-api-contract.obS6uV8A.mjs';
-import './shared/nuxt-api-contract.DDpgZj2g.mjs';
+import './shared/nuxt-api-contract.CAIOgncy.mjs';
 import 'zod';
 import './shared/nuxt-api-contract.DCAU2j7t.mjs';

package/dist/server.mjs

@@ -1,13 +1,11 @@
-import { a as getContractMock } from './shared/nuxt-api-contract.V15soI_f.mjs';
-export { b as buildRequestPath, c as clearContractRegistry, d as defineApiContract, g as getContractByName, i as isApiContract, l as listRegisteredContracts, m as mockContract, r as registerContract } from './shared/nuxt-api-contract.V15soI_f.mjs';
-import { A as ApiError, s as serializeApiError, B as BUILT_IN_ERROR_CODES } from './shared/nuxt-api-contract.obS6uV8A.mjs';
-export { c as createApiError, i as isApiError, p as parseApiErrorPayload, t as toApiError } from './shared/nuxt-api-contract.obS6uV8A.mjs';
+import { e as getContractMock, A as ApiError, s as serializeApiError, B as BUILT_IN_ERROR_CODES } from './shared/nuxt-api-contract.CHdRLlU7.mjs';
+export { b as buildRequestPath, c as clearContractRegistry, a as createApiError, d as defineApiContract, g as getContractByName, i as isApiContract, f as isApiError, l as listRegisteredContracts, m as mockContract, p as parseApiErrorPayload, r as registerContract, t as toApiError } from './shared/nuxt-api-contract.CHdRLlU7.mjs';
 export { f as formatValidationMessage, s as sanitizeIssues, t as toValidationIssues } from './shared/nuxt-api-contract.DCAU2j7t.mjs';
 export { s as serializeQuery, a as serializeQueryValue, b as stableStringify } from './shared/nuxt-api-contract.Dr4tPqGB.mjs';
 import { defineEventHandler, getRequestHeaders, getQuery, readValidatedBody, setResponseStatus } from 'h3';
-import { g as generateMockResponse } from './shared/nuxt-api-contract.Bd2Y7Lx0.mjs';
-import { v as validateContractInput, r as readRuntimeConfig, s as shouldValidateResponse, a as validateContractResponse } from './shared/nuxt-api-contract.DDpgZj2g.mjs';
-export { b as rawQuerySchema } from './shared/nuxt-api-contract.DDpgZj2g.mjs';
+import { g as generateMockResponse } from './shared/nuxt-api-contract.BWgzVTNN.mjs';
+import { v as validateContractInput, r as readRuntimeConfig, s as shouldValidateResponse, a as validateContractResponse } from './shared/nuxt-api-contract.CAIOgncy.mjs';
+export { b as rawQuerySchema } from './shared/nuxt-api-contract.CAIOgncy.mjs';
 import 'zod';
 
 const CONTRACT_HANDLER_META = Symbol.for("nuxt-api-contract.contractHandlerMeta");

package/dist/shared/{nuxt-api-contract.Bd2Y7Lx0.mjs → nuxt-api-contract.BWgzVTNN.mjs}

@@ -1,4 +1,4 @@
-import { m as mockContract } from './nuxt-api-contract.V15soI_f.mjs';
+import { m as mockContract } from './nuxt-api-contract.CHdRLlU7.mjs';
 
 function zodDef(schema) {
   return schema._def;

package/dist/shared/{nuxt-api-contract.DDpgZj2g.mjs → nuxt-api-contract.CAIOgncy.mjs}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { c as createApiError, B as BUILT_IN_ERROR_CODES } from './nuxt-api-contract.obS6uV8A.mjs';
+import { a as createApiError, B as BUILT_IN_ERROR_CODES } from './nuxt-api-contract.CHdRLlU7.mjs';
 import { t as toValidationIssues, s as sanitizeIssues, f as formatValidationMessage } from './nuxt-api-contract.DCAU2j7t.mjs';
 
 function readRuntimeConfig(getConfig) {

package/dist/shared/nuxt-api-contract.CHdRLlU7.mjs

@@ -0,0 +1,152 @@
+const API_CONTRACT_KIND = "api-contract";
+
+const REGISTRY_KEY = Symbol.for("nuxt-api-contract.registry");
+function getStore() {
+  const globalThis_ = globalThis;
+  if (!globalThis_[REGISTRY_KEY]) {
+    globalThis_[REGISTRY_KEY] = { contracts: /* @__PURE__ */ new Map() };
+  }
+  return globalThis_[REGISTRY_KEY];
+}
+function registerContract(contract) {
+  if (!contract.name) return;
+  const store = getStore();
+  const existing = store.contracts.get(contract.name);
+  if (existing && existing !== contract) {
+    console.warn(
+      `[nuxt-api-contract] Duplicate contract name "${contract.name}" registered. The latest definition wins.`
+    );
+  }
+  store.contracts.set(contract.name, contract);
+}
+function getContractByName(name) {
+  return getStore().contracts.get(name);
+}
+function listRegisteredContracts() {
+  return [...getStore().contracts.values()];
+}
+function clearContractRegistry() {
+  getStore().contracts.clear();
+}
+const MOCK_STORE_KEY = Symbol.for("nuxt-api-contract.mocks");
+const mockStore = globalThis[MOCK_STORE_KEY] ??= /* @__PURE__ */ new Map();
+function mockContract(contract, mock) {
+  mockStore.set(contract, mock);
+}
+function getContractMock(contract) {
+  return mockStore.get(contract);
+}
+function defineApiContract(definition) {
+  const contract = {
+    kind: API_CONTRACT_KIND,
+    name: definition.name,
+    version: definition.version,
+    method: definition.method,
+    path: definition.path,
+    params: definition.params,
+    query: definition.query,
+    body: definition.body,
+    headers: definition.headers,
+    response: definition.response,
+    errors: definition.errors ? Object.freeze({ ...definition.errors }) : void 0,
+    summary: definition.summary,
+    description: definition.description,
+    tags: definition.tags ? Object.freeze([...definition.tags]) : void 0,
+    auth: definition.auth,
+    metadata: definition.metadata ? Object.freeze({ ...definition.metadata }) : void 0
+  };
+  Object.freeze(contract);
+  if (definition.name) {
+    registerContract(contract);
+  }
+  return contract;
+}
+function isApiContract(value) {
+  return typeof value === "object" && value !== null && value.kind === API_CONTRACT_KIND;
+}
+function buildRequestPath(path, params) {
+  let url = path;
+  for (const match of path.matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)) {
+    const name = match[1];
+    const value = params?.[name];
+    if (value === void 0 || value === null) {
+      throw new Error(`[nuxt-api-contract] Missing path parameter ":${name}" for ${path}`);
+    }
+    url = url.replace(`:${name}`, encodeURIComponent(String(value)));
+  }
+  return url;
+}
+
+class ApiError extends Error {
+  code;
+  statusCode;
+  details;
+  issues;
+  constructor(options) {
+    super(options.message);
+    this.name = "ApiError";
+    this.code = options.code;
+    this.statusCode = options.statusCode ?? 500;
+    this.details = options.details;
+    this.issues = options.issues;
+  }
+  toJSON() {
+    return serializeApiError(this);
+  }
+}
+function createApiError(codeOrOptions, message, statusCode, details) {
+  if (typeof codeOrOptions === "string") {
+    return new ApiError({ code: codeOrOptions, message: message ?? codeOrOptions, statusCode, details });
+  }
+  return new ApiError({
+    code: codeOrOptions.code,
+    message: codeOrOptions.message ?? codeOrOptions.code,
+    statusCode: codeOrOptions.statusCode,
+    details: codeOrOptions.details,
+    issues: codeOrOptions.issues
+  });
+}
+function isApiError(value) {
+  return value instanceof ApiError || typeof value === "object" && value !== null && value.name === "ApiError" && typeof value.code === "string";
+}
+function serializeApiError(error) {
+  return {
+    error: {
+      code: error.code,
+      message: error.message,
+      statusCode: error.statusCode,
+      details: error.details,
+      issues: error.issues
+    }
+  };
+}
+function parseApiErrorPayload(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const error = value.error;
+  if (typeof error !== "object" || error === null) return void 0;
+  const { code, message, statusCode, details, issues } = error;
+  if (typeof code !== "string" || typeof message !== "string") return void 0;
+  return {
+    code,
+    message,
+    statusCode: typeof statusCode === "number" ? statusCode : void 0,
+    details,
+    issues: Array.isArray(issues) ? issues : void 0
+  };
+}
+function toApiError(value, fallbackMessage = "Internal server error") {
+  if (isApiError(value)) return value;
+  if (value instanceof Error) {
+    return new ApiError({ code: "INTERNAL_ERROR", message: value.message || fallbackMessage, statusCode: 500 });
+  }
+  return new ApiError({ code: "INTERNAL_ERROR", message: fallbackMessage, statusCode: 500 });
+}
+const BUILT_IN_ERROR_CODES = {
+  validation: "VALIDATION_ERROR",
+  responseValidation: "API_CONTRACT_RESPONSE_VALIDATION_ERROR",
+  internal: "INTERNAL_ERROR",
+  notFound: "NOT_FOUND",
+  methodNotAllowed: "METHOD_NOT_ALLOWED"
+};
+
+export { ApiError as A, BUILT_IN_ERROR_CODES as B, createApiError as a, buildRequestPath as b, clearContractRegistry as c, defineApiContract as d, getContractMock as e, isApiError as f, getContractByName as g, isApiContract as i, listRegisteredContracts as l, mockContract as m, parseApiErrorPayload as p, registerContract as r, serializeApiError as s, toApiError as t };

package/dist/shared.mjs

@@ -1,5 +1,4 @@
-export { b as buildRequestPath, c as clearContractRegistry, d as defineApiContract, g as getContractByName, a as getContractMock, i as isApiContract, l as listRegisteredContracts, m as mockContract, r as registerContract } from './shared/nuxt-api-contract.V15soI_f.mjs';
-export { A as ApiError, B as BUILT_IN_ERROR_CODES, c as createApiError, i as isApiError, p as parseApiErrorPayload, s as serializeApiError, t as toApiError } from './shared/nuxt-api-contract.obS6uV8A.mjs';
+export { A as ApiError, B as BUILT_IN_ERROR_CODES, b as buildRequestPath, c as clearContractRegistry, a as createApiError, d as defineApiContract, g as getContractByName, e as getContractMock, i as isApiContract, f as isApiError, l as listRegisteredContracts, m as mockContract, p as parseApiErrorPayload, r as registerContract, s as serializeApiError, t as toApiError } from './shared/nuxt-api-contract.CHdRLlU7.mjs';
 export { f as formatValidationMessage, s as sanitizeIssues, t as toValidationIssues } from './shared/nuxt-api-contract.DCAU2j7t.mjs';
 export { s as serializeQuery, a as serializeQueryValue, b as stableStringify } from './shared/nuxt-api-contract.Dr4tPqGB.mjs';
-export { a as autoMockContract, c as createRng, g as generateMockResponse, b as generateMockValue } from './shared/nuxt-api-contract.Bd2Y7Lx0.mjs';
+export { a as autoMockContract, c as createRng, g as generateMockResponse, b as generateMockValue } from './shared/nuxt-api-contract.BWgzVTNN.mjs';

package/dist/testing.d.mts

@@ -1,5 +1,5 @@
 import { H3Event, EventHandler } from 'h3';
-import { AnyApiContract, ContractClientResponse } from './client.mjs';
+import { AnyApiContract, ContractClientResponse, HttpMethod } from './client.mjs';
 import { ApiError } from './client.mjs';
 import { ContractHandler } from './server.mjs';
 import 'zod';
@@ -20,9 +20,9 @@ interface ContractHandlerMeta {
         body: unknown;
         headers: unknown;
         event: H3Event;
-    }) => Awaitable<unknown>;
+    }) => Awaitable$1<unknown>;
 }
-type Awaitable<T> = T | Promise<T>;
+type Awaitable$1<T> = T | Promise<T>;
 /**
  * Calls a contract handler pipeline directly (no HTTP server):
  *
@@ -47,9 +47,114 @@ declare function callContract<C extends AnyApiContract>(contract: C, handler: Co
     data: null;
     error: ApiError;
 }>;
-type EventHandlerLike = (ctx: Record<string, unknown>) => Awaitable<unknown>;
+type EventHandlerLike = (ctx: Record<string, unknown>) => Awaitable$1<unknown>;
 /** Exposed so the module-level `defineContractHandler` can attach metadata. */
 declare const contractHandlerMetaKey: symbol;
 
-export { callContract, contractHandlerMetaKey };
-export type { ContractHandlerMeta };
+/**
+ * `testContract` — a testing suite bound to a contract + handler.
+ *
+ * Framework-agnostic: every `expect*` method throws a
+ * `ContractAssertionError` on failure, so it works with Vitest, Jest,
+ * `node:assert` and any other runner that treats thrown errors as failures.
+ *
+ * ```ts
+ * import { testContract } from 'nuxt-api-contract/testing'
+ *
+ * const user = testContract(GetUser, handler)
+ *
+ * it('returns the user', async () => {
+ *   await user.expectSuccess({ params: { id: '1' } })
+ * })
+ * ```
+ */
+
+type Awaitable<T> = T | Promise<T>;
+type TestHandler<C extends AnyApiContract> = ContractHandler<C> | EventHandler | ((ctx: Record<string, unknown>) => Awaitable<unknown>);
+interface ContractTestInput {
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** Thrown by every failed `testContract` assertion. */
+declare class ContractAssertionError extends Error {
+    constructor(message: string);
+}
+interface ContractTestSuite<C extends AnyApiContract> {
+    /** Runs the full pipeline (validation -> handler -> response validation). */
+    call(input?: ContractTestInput): Promise<{
+        data: ContractClientResponse<C> | null;
+        error: ApiError | null;
+    }>;
+    /** Asserts the call succeeds; returns the typed response data. */
+    expectSuccess(input?: ContractTestInput): Promise<ContractClientResponse<C>>;
+    /** Asserts the call fails with (optionally) the given code and status. */
+    expectError(input?: ContractTestInput, code?: string, statusCode?: number): Promise<ApiError>;
+    /** Asserts a `VALIDATION_ERROR`; optionally checks that issues cover the given paths. */
+    expectValidationError(input?: ContractTestInput, issuePaths?: string[]): Promise<ApiError>;
+    /** Asserts the response validation catches a bad handler output. */
+    expectResponseValidationError(input: ContractTestInput, badResponse: unknown | ((ctx: Record<string, unknown>) => unknown)): Promise<ApiError>;
+    /** Validates an arbitrary value against the contract's response schema. */
+    validateResponse(value: unknown): void;
+}
+/**
+ * Creates a test suite for a contract + handler pair.
+ *
+ * ```ts
+ * const suite = testContract(GetUser, handler)
+ *
+ * await suite.expectSuccess({ params: { id: '1' } })
+ * await suite.expectError({ params: { id: 'missing' } }, 'USER_NOT_FOUND', 404)
+ * await suite.expectValidationError({ params: { id: '' } }, ['params.id'])
+ * ```
+ */
+declare function testContract<C extends AnyApiContract>(contract: C, handler: TestHandler<C>): ContractTestSuite<C>;
+
+/**
+ * Contract coverage tracking: records which registered contracts have been
+ * exercised through `callContract` / `testContract` (and with which outcome).
+ * Enable it in a test setup hook and print the report in an after-hook:
+ *
+ * ```ts
+ * import { startContractCoverage, formatContractCoverage, getContractCoverage } from 'nuxt-api-contract/testing'
+ *
+ * beforeAll(() => startContractCoverage())
+ * afterAll(() => console.log(formatContractCoverage(getContractCoverage())))
+ * ```
+ */
+
+interface ContractCoverageEntry {
+    /** Contract name, or `METHOD path` for anonymous contracts. */
+    key: string;
+    name?: string;
+    method: HttpMethod;
+    path: string;
+    calls: number;
+    failures: number;
+}
+interface ContractCoverageReport {
+    /** Named contracts registered in the registry at report time. */
+    total: number;
+    coveredCount: number;
+    percent: number;
+    covered: ContractCoverageEntry[];
+    uncovered: Array<{
+        name?: string;
+        method: HttpMethod;
+        path: string;
+    }>;
+}
+/** Starts (and resets) coverage recording. */
+declare function startContractCoverage(): void;
+/** Stops recording and returns the final report. */
+declare function stopContractCoverage(): ContractCoverageReport;
+/** Clears recorded stats without changing the active state. */
+declare function resetContractCoverage(): void;
+/** Builds the coverage report against the currently registered contracts. */
+declare function getContractCoverage(): ContractCoverageReport;
+/** Formats the report as a human-readable table for test output. */
+declare function formatContractCoverage(report: ContractCoverageReport): string;
+
+export { ContractAssertionError, callContract, contractHandlerMetaKey, formatContractCoverage, getContractCoverage, resetContractCoverage, startContractCoverage, stopContractCoverage, testContract };
+export type { ContractCoverageEntry, ContractCoverageReport, ContractHandlerMeta, ContractTestInput, ContractTestSuite, TestHandler };

package/dist/testing.d.ts

@@ -1,5 +1,5 @@
 import { H3Event, EventHandler } from 'h3';
-import { AnyApiContract, ContractClientResponse } from './client.js';
+import { AnyApiContract, ContractClientResponse, HttpMethod } from './client.js';
 import { ApiError } from './client.js';
 import { ContractHandler } from './server.js';
 import 'zod';
@@ -20,9 +20,9 @@ interface ContractHandlerMeta {
         body: unknown;
         headers: unknown;
         event: H3Event;
-    }) => Awaitable<unknown>;
+    }) => Awaitable$1<unknown>;
 }
-type Awaitable<T> = T | Promise<T>;
+type Awaitable$1<T> = T | Promise<T>;
 /**
  * Calls a contract handler pipeline directly (no HTTP server):
  *
@@ -47,9 +47,114 @@ declare function callContract<C extends AnyApiContract>(contract: C, handler: Co
     data: null;
     error: ApiError;
 }>;
-type EventHandlerLike = (ctx: Record<string, unknown>) => Awaitable<unknown>;
+type EventHandlerLike = (ctx: Record<string, unknown>) => Awaitable$1<unknown>;
 /** Exposed so the module-level `defineContractHandler` can attach metadata. */
 declare const contractHandlerMetaKey: symbol;
 
-export { callContract, contractHandlerMetaKey };
-export type { ContractHandlerMeta };
+/**
+ * `testContract` — a testing suite bound to a contract + handler.
+ *
+ * Framework-agnostic: every `expect*` method throws a
+ * `ContractAssertionError` on failure, so it works with Vitest, Jest,
+ * `node:assert` and any other runner that treats thrown errors as failures.
+ *
+ * ```ts
+ * import { testContract } from 'nuxt-api-contract/testing'
+ *
+ * const user = testContract(GetUser, handler)
+ *
+ * it('returns the user', async () => {
+ *   await user.expectSuccess({ params: { id: '1' } })
+ * })
+ * ```
+ */
+
+type Awaitable<T> = T | Promise<T>;
+type TestHandler<C extends AnyApiContract> = ContractHandler<C> | EventHandler | ((ctx: Record<string, unknown>) => Awaitable<unknown>);
+interface ContractTestInput {
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** Thrown by every failed `testContract` assertion. */
+declare class ContractAssertionError extends Error {
+    constructor(message: string);
+}
+interface ContractTestSuite<C extends AnyApiContract> {
+    /** Runs the full pipeline (validation -> handler -> response validation). */
+    call(input?: ContractTestInput): Promise<{
+        data: ContractClientResponse<C> | null;
+        error: ApiError | null;
+    }>;
+    /** Asserts the call succeeds; returns the typed response data. */
+    expectSuccess(input?: ContractTestInput): Promise<ContractClientResponse<C>>;
+    /** Asserts the call fails with (optionally) the given code and status. */
+    expectError(input?: ContractTestInput, code?: string, statusCode?: number): Promise<ApiError>;
+    /** Asserts a `VALIDATION_ERROR`; optionally checks that issues cover the given paths. */
+    expectValidationError(input?: ContractTestInput, issuePaths?: string[]): Promise<ApiError>;
+    /** Asserts the response validation catches a bad handler output. */
+    expectResponseValidationError(input: ContractTestInput, badResponse: unknown | ((ctx: Record<string, unknown>) => unknown)): Promise<ApiError>;
+    /** Validates an arbitrary value against the contract's response schema. */
+    validateResponse(value: unknown): void;
+}
+/**
+ * Creates a test suite for a contract + handler pair.
+ *
+ * ```ts
+ * const suite = testContract(GetUser, handler)
+ *
+ * await suite.expectSuccess({ params: { id: '1' } })
+ * await suite.expectError({ params: { id: 'missing' } }, 'USER_NOT_FOUND', 404)
+ * await suite.expectValidationError({ params: { id: '' } }, ['params.id'])
+ * ```
+ */
+declare function testContract<C extends AnyApiContract>(contract: C, handler: TestHandler<C>): ContractTestSuite<C>;
+
+/**
+ * Contract coverage tracking: records which registered contracts have been
+ * exercised through `callContract` / `testContract` (and with which outcome).
+ * Enable it in a test setup hook and print the report in an after-hook:
+ *
+ * ```ts
+ * import { startContractCoverage, formatContractCoverage, getContractCoverage } from 'nuxt-api-contract/testing'
+ *
+ * beforeAll(() => startContractCoverage())
+ * afterAll(() => console.log(formatContractCoverage(getContractCoverage())))
+ * ```
+ */
+
+interface ContractCoverageEntry {
+    /** Contract name, or `METHOD path` for anonymous contracts. */
+    key: string;
+    name?: string;
+    method: HttpMethod;
+    path: string;
+    calls: number;
+    failures: number;
+}
+interface ContractCoverageReport {
+    /** Named contracts registered in the registry at report time. */
+    total: number;
+    coveredCount: number;
+    percent: number;
+    covered: ContractCoverageEntry[];
+    uncovered: Array<{
+        name?: string;
+        method: HttpMethod;
+        path: string;
+    }>;
+}
+/** Starts (and resets) coverage recording. */
+declare function startContractCoverage(): void;
+/** Stops recording and returns the final report. */
+declare function stopContractCoverage(): ContractCoverageReport;
+/** Clears recorded stats without changing the active state. */
+declare function resetContractCoverage(): void;
+/** Builds the coverage report against the currently registered contracts. */
+declare function getContractCoverage(): ContractCoverageReport;
+/** Formats the report as a human-readable table for test output. */
+declare function formatContractCoverage(report: ContractCoverageReport): string;
+
+export { ContractAssertionError, callContract, contractHandlerMetaKey, formatContractCoverage, getContractCoverage, resetContractCoverage, startContractCoverage, stopContractCoverage, testContract };
+export type { ContractCoverageEntry, ContractCoverageReport, ContractHandlerMeta, ContractTestInput, ContractTestSuite, TestHandler };

package/dist/testing.mjs

@@ -1,8 +1,72 @@
-import { A as ApiError } from './shared/nuxt-api-contract.obS6uV8A.mjs';
-import { v as validateContractInput, a as validateContractResponse } from './shared/nuxt-api-contract.DDpgZj2g.mjs';
+import { l as listRegisteredContracts, A as ApiError, B as BUILT_IN_ERROR_CODES } from './shared/nuxt-api-contract.CHdRLlU7.mjs';
+import { v as validateContractInput, a as validateContractResponse } from './shared/nuxt-api-contract.CAIOgncy.mjs';
 import 'zod';
 import './shared/nuxt-api-contract.DCAU2j7t.mjs';
 
+const state = { active: false, entries: /* @__PURE__ */ new Map() };
+function entryKey(contract) {
+  return contract.name ?? `${contract.method} ${contract.path}`;
+}
+function startContractCoverage() {
+  state.active = true;
+  state.entries.clear();
+}
+function stopContractCoverage() {
+  state.active = false;
+  return getContractCoverage();
+}
+function resetContractCoverage() {
+  state.entries.clear();
+}
+function recordCoverageCall(contract, success) {
+  if (!state.active) return;
+  const key = entryKey(contract);
+  const entry = state.entries.get(key) ?? {
+    key,
+    name: contract.name,
+    method: contract.method,
+    path: contract.path,
+    calls: 0,
+    failures: 0
+  };
+  entry.calls++;
+  if (!success) entry.failures++;
+  state.entries.set(key, entry);
+}
+function getContractCoverage() {
+  const covered = [...state.entries.values()].sort((a, b) => a.key.localeCompare(b.key));
+  const coveredKeys = new Set(covered.map((entry) => entry.key));
+  const uncovered = listRegisteredContracts().filter((contract) => contract.name && !coveredKeys.has(contract.name)).map((contract) => ({ name: contract.name, method: contract.method, path: contract.path }));
+  const total = uncovered.length + covered.length;
+  return {
+    total,
+    coveredCount: covered.length,
+    percent: total === 0 ? 100 : Math.round(covered.length / total * 100),
+    covered,
+    uncovered
+  };
+}
+function formatContractCoverage(report) {
+  const lines = [
+    "Contract coverage",
+    `  ${report.coveredCount}/${report.total} contracts covered (${report.percent}%)`
+  ];
+  if (report.covered.length > 0) {
+    lines.push("Covered:");
+    for (const entry of report.covered) {
+      const status = entry.failures > 0 ? `${entry.calls - entry.failures}/${entry.calls} ok` : `${entry.calls} ok`;
+      lines.push(`  \u2713 ${entry.method.padEnd(6)} ${entry.path.padEnd(32)} ${status}${entry.failures > 0 ? ` (${entry.failures} failed)` : ""}`);
+    }
+  }
+  if (report.uncovered.length > 0) {
+    lines.push("Uncovered:");
+    for (const entry of report.uncovered) {
+      lines.push(`  \u2717 ${entry.method.padEnd(6)} ${entry.path}${entry.name ? `  (${entry.name})` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+
 const CONTRACT_HANDLER_META = Symbol.for("nuxt-api-contract.contractHandlerMeta");
 async function callContract(contract, handler, input = {}) {
   const runHandler = extractHandler(contract, handler);
@@ -14,8 +78,10 @@ async function callContract(contract, handler, input = {}) {
     const event = createFakeEvent(headers);
     const rawResponse = await runHandler({ params, query, body, headers, event });
     const data = contract.response ? validateContractResponse(contract, contract.response, rawResponse) : rawResponse;
+    recordCoverageCall(contract, true);
     return { data, error: null };
   } catch (error) {
+    recordCoverageCall(contract, false);
     return {
       data: null,
       error: error instanceof ApiError ? error : new ApiError({ code: "INTERNAL_ERROR", message: String(error) })
@@ -46,4 +112,95 @@ function createFakeEvent(headers) {
 }
 const contractHandlerMetaKey = CONTRACT_HANDLER_META;
 
-export { callContract, contractHandlerMetaKey };
+class ContractAssertionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContractAssertionError";
+  }
+}
+function describeCall(contract) {
+  return `${contract.method} ${contract.path}`;
+}
+function testContract(contract, handler) {
+  const suite = {
+    async call(input) {
+      return callContract(contract, handler, input);
+    },
+    async expectSuccess(input) {
+      const { data, error } = await callContract(contract, handler, input);
+      if (error) {
+        throw new ContractAssertionError(
+          `[nuxt-api-contract] Expected success for ${describeCall(contract)}, got ${error.code} (${error.statusCode}): ${error.message}`
+        );
+      }
+      return data;
+    },
+    async expectError(input, code, statusCode) {
+      const { data, error } = await callContract(contract, handler, input);
+      if (!error) {
+        throw new ContractAssertionError(
+          `[nuxt-api-contract] Expected an error for ${describeCall(contract)}, but the call succeeded with: ${JSON.stringify(data)}`
+        );
+      }
+      if (code && error.code !== code) {
+        throw new ContractAssertionError(
+          `[nuxt-api-contract] Expected error code "${code}" for ${describeCall(contract)}, got "${error.code}" (${error.message})`
+        );
+      }
+      if (statusCode !== void 0 && error.statusCode !== statusCode) {
+        throw new ContractAssertionError(
+          `[nuxt-api-contract] Expected status ${statusCode} for ${describeCall(contract)}, got ${error.statusCode}`
+        );
+      }
+      return error;
+    },
+    async expectValidationError(input, issuePaths) {
+      const error = await suite.expectError(input, BUILT_IN_ERROR_CODES.validation, 400);
+      if (issuePaths && issuePaths.length > 0) {
+        const actual = new Set((error.issues ?? []).map((issue) => issue.path));
+        const missing = issuePaths.filter((path) => {
+          for (const actualPath of actual) {
+            if (actualPath === path || actualPath.endsWith(`.${path}`) || path.endsWith(`.${actualPath}`) || actualPath.startsWith(`${path}.`)) return false;
+          }
+          return true;
+        });
+        if (missing.length > 0) {
+          throw new ContractAssertionError(
+            `[nuxt-api-contract] Expected validation issues for ${[...missing].join(", ")} on ${describeCall(contract)}, got: ${(error.issues ?? []).map((issue) => issue.path).join(", ") || "(none)"}`
+          );
+        }
+      }
+      return error;
+    },
+    async expectResponseValidationError(input, badResponse) {
+      const raw = badResponse;
+      const badHandler = typeof raw === "function" ? raw : ((_ctx) => raw);
+      const { error } = await callContract(contract, badHandler, input);
+      if (!error) {
+        throw new ContractAssertionError(
+          `[nuxt-api-contract] Expected a response validation failure for ${describeCall(contract)}, but the call succeeded`
+        );
+      }
+      if (error.code !== BUILT_IN_ERROR_CODES.responseValidation) {
+        throw new ContractAssertionError(
+          `[nuxt-api-contract] Expected "${BUILT_IN_ERROR_CODES.responseValidation}" for ${describeCall(contract)}, got "${error.code}" (${error.message})`
+        );
+      }
+      return error;
+    },
+    validateResponse(value) {
+      if (!contract.response) return;
+      try {
+        validateContractResponse(contract, contract.response, value);
+      } catch (error) {
+        if (error instanceof ApiError) {
+          throw new ContractAssertionError(`[nuxt-api-contract] Response validation failed: ${error.message}`);
+        }
+        throw error;
+      }
+    }
+  };
+  return suite;
+}
+
+export { ContractAssertionError, callContract, contractHandlerMetaKey, formatContractCoverage, getContractCoverage, resetContractCoverage, startContractCoverage, stopContractCoverage, testContract };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-api-contract",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Type-safe API contracts between Nitro server routes and the Nuxt client.",
   "type": "module",
   "license": "MIT",

package/dist/shared/nuxt-api-contract.V15soI_f.mjs

@@ -1,80 +0,0 @@
-const API_CONTRACT_KIND = "api-contract";
-
-const REGISTRY_KEY = Symbol.for("nuxt-api-contract.registry");
-function getStore() {
-  const globalThis_ = globalThis;
-  if (!globalThis_[REGISTRY_KEY]) {
-    globalThis_[REGISTRY_KEY] = { contracts: /* @__PURE__ */ new Map() };
-  }
-  return globalThis_[REGISTRY_KEY];
-}
-function registerContract(contract) {
-  if (!contract.name) return;
-  const store = getStore();
-  const existing = store.contracts.get(contract.name);
-  if (existing && existing !== contract) {
-    console.warn(
-      `[nuxt-api-contract] Duplicate contract name "${contract.name}" registered. The latest definition wins.`
-    );
-  }
-  store.contracts.set(contract.name, contract);
-}
-function getContractByName(name) {
-  return getStore().contracts.get(name);
-}
-function listRegisteredContracts() {
-  return [...getStore().contracts.values()];
-}
-function clearContractRegistry() {
-  getStore().contracts.clear();
-}
-const MOCK_STORE_KEY = Symbol.for("nuxt-api-contract.mocks");
-const mockStore = globalThis[MOCK_STORE_KEY] ??= /* @__PURE__ */ new Map();
-function mockContract(contract, mock) {
-  mockStore.set(contract, mock);
-}
-function getContractMock(contract) {
-  return mockStore.get(contract);
-}
-function defineApiContract(definition) {
-  const contract = {
-    kind: API_CONTRACT_KIND,
-    name: definition.name,
-    version: definition.version,
-    method: definition.method,
-    path: definition.path,
-    params: definition.params,
-    query: definition.query,
-    body: definition.body,
-    headers: definition.headers,
-    response: definition.response,
-    errors: definition.errors ? Object.freeze({ ...definition.errors }) : void 0,
-    summary: definition.summary,
-    description: definition.description,
-    tags: definition.tags ? Object.freeze([...definition.tags]) : void 0,
-    auth: definition.auth,
-    metadata: definition.metadata ? Object.freeze({ ...definition.metadata }) : void 0
-  };
-  Object.freeze(contract);
-  if (definition.name) {
-    registerContract(contract);
-  }
-  return contract;
-}
-function isApiContract(value) {
-  return typeof value === "object" && value !== null && value.kind === API_CONTRACT_KIND;
-}
-function buildRequestPath(path, params) {
-  let url = path;
-  for (const match of path.matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)) {
-    const name = match[1];
-    const value = params?.[name];
-    if (value === void 0 || value === null) {
-      throw new Error(`[nuxt-api-contract] Missing path parameter ":${name}" for ${path}`);
-    }
-    url = url.replace(`:${name}`, encodeURIComponent(String(value)));
-  }
-  return url;
-}
-
-export { getContractMock as a, buildRequestPath as b, clearContractRegistry as c, defineApiContract as d, getContractByName as g, isApiContract as i, listRegisteredContracts as l, mockContract as m, registerContract as r };

package/dist/shared/nuxt-api-contract.obS6uV8A.mjs

@@ -1,73 +0,0 @@
-class ApiError extends Error {
-  code;
-  statusCode;
-  details;
-  issues;
-  constructor(options) {
-    super(options.message);
-    this.name = "ApiError";
-    this.code = options.code;
-    this.statusCode = options.statusCode ?? 500;
-    this.details = options.details;
-    this.issues = options.issues;
-  }
-  toJSON() {
-    return serializeApiError(this);
-  }
-}
-function createApiError(codeOrOptions, message, statusCode, details) {
-  if (typeof codeOrOptions === "string") {
-    return new ApiError({ code: codeOrOptions, message: message ?? codeOrOptions, statusCode, details });
-  }
-  return new ApiError({
-    code: codeOrOptions.code,
-    message: codeOrOptions.message ?? codeOrOptions.code,
-    statusCode: codeOrOptions.statusCode,
-    details: codeOrOptions.details,
-    issues: codeOrOptions.issues
-  });
-}
-function isApiError(value) {
-  return value instanceof ApiError || typeof value === "object" && value !== null && value.name === "ApiError" && typeof value.code === "string";
-}
-function serializeApiError(error) {
-  return {
-    error: {
-      code: error.code,
-      message: error.message,
-      statusCode: error.statusCode,
-      details: error.details,
-      issues: error.issues
-    }
-  };
-}
-function parseApiErrorPayload(value) {
-  if (typeof value !== "object" || value === null) return void 0;
-  const error = value.error;
-  if (typeof error !== "object" || error === null) return void 0;
-  const { code, message, statusCode, details, issues } = error;
-  if (typeof code !== "string" || typeof message !== "string") return void 0;
-  return {
-    code,
-    message,
-    statusCode: typeof statusCode === "number" ? statusCode : void 0,
-    details,
-    issues: Array.isArray(issues) ? issues : void 0
-  };
-}
-function toApiError(value, fallbackMessage = "Internal server error") {
-  if (isApiError(value)) return value;
-  if (value instanceof Error) {
-    return new ApiError({ code: "INTERNAL_ERROR", message: value.message || fallbackMessage, statusCode: 500 });
-  }
-  return new ApiError({ code: "INTERNAL_ERROR", message: fallbackMessage, statusCode: 500 });
-}
-const BUILT_IN_ERROR_CODES = {
-  validation: "VALIDATION_ERROR",
-  responseValidation: "API_CONTRACT_RESPONSE_VALIDATION_ERROR",
-  internal: "INTERNAL_ERROR",
-  notFound: "NOT_FOUND",
-  methodNotAllowed: "METHOD_NOT_ALLOWED"
-};
-
-export { ApiError as A, BUILT_IN_ERROR_CODES as B, createApiError as c, isApiError as i, parseApiErrorPayload as p, serializeApiError as s, toApiError as t };