test: set up automated mocking based on API schema (#48)

* test: add msw

* test: add auto mocker

* test: test actual mock api

* test: remove implicity failures in auto-mocker

* test: fix auto mocker

* chore: fix type errors

* test: reduce crazy auto mock size

* fixes

* fix heuristics

* fixes

* .

* .

* add standalone mock server for using msw with nextjs

* allow running  local server against mocks

* fixes

* .

* .

* .

* .

* .

* chore: store provider accessToken into secure cookie

* test: auth test cases

* test: move test files

* test: refactor import

* .

* fix: delete unmatched cookie

* refactor:  caching the derived key

* refactor: suggestions from copilot

* fix: derived key for missing better-auth secret

* refactor: replace crypto with jose and clean cookie on signout

* refactor: move auth into a dedicated lib/auth folder

* leftover

* refactor: add more error handling

* .

* .

* cleanup

* .

* fixes

* .

* .

* cleanup

* .

* config fixes

* more global mocks

* do not change generated files

* move data fetching to server action

* simplify base url logic

* .

* comment cleanup

* .

* .

* .

* load .env and .env.local equally

* remove unused logic

* patches from Giueseppe

* remove OIDC_PROVIDER_ID env var

---------

Co-authored-by: Giuseppe Scuglia <[email protected]>

Author: kantord

AGENTS.md

@@ -9,6 +9,7 @@ This document provides essential context for AI coding assistants (Claude, GitHu
 1. This file (AGENTS.md) - Project overview and key patterns
 2. `CLAUDE.md` - Detailed guidelines for AI assistants
 3. `README.md` - Setup and deployment instructions
+4. `docs/mocks.md` - MSW auto-mocker, fixtures, and dev server
 
 ## Project Summary
 
@@ -36,10 +37,11 @@ This document provides essential context for AI coding assistants (Claude, GitHu
 ## Core Principles
 
 1. **Server Components First** - Use `'use client'` only when necessary
-2. **Generated API Client** - Never write manual fetch logic, use hey-api hooks
-3. **Async/Await Only** - No `.then()` promise chains
-4. **🚫 NEVER USE `any`** - STRICTLY FORBIDDEN. Use `unknown` with type guards or proper types
-5. **Stateless Auth** - JWT tokens, no server-side sessions
+2. **Generated API Client** - Never write manual fetch logic, use hey-api functions in server actions
+3. **Server Actions for API Calls** - Client components fetch data via server actions, not direct API calls
+4. **Async/Await Only** - No `.then()` promise chains
+5. **🚫 NEVER USE `any`** - STRICTLY FORBIDDEN. Use `unknown` with type guards or proper types
+6. **Stateless Auth** - JWT tokens, no server-side sessions
 
 ## ⚠️ Before Suggesting Code
 
@@ -68,6 +70,8 @@ src/
 ├── generated/        # hey-api output (DO NOT EDIT)
 └── hooks/            # Custom React hooks
 
+src/mocks/            # MSW auto-mocker, handlers, fixtures, and dev server
+
 dev-auth/             # Development OIDC mock
 helm/                 # Kubernetes deployment
 scripts/              # Build scripts
@@ -78,6 +82,7 @@ scripts/              # Build scripts
 ```bash
 # Development
 pnpm dev              # Start dev server + OIDC mock
+pnpm mock:server      # Start standalone MSW mock server (default: http://localhost:9090)
 pnpm dev:next        # Start only Next.js
 pnpm oidc            # Start only OIDC mock
 
@@ -91,6 +96,14 @@ pnpm test            # Run tests
 pnpm generate-client # Regenerate from backend API
 ```
 
+## Mocking & Fixtures
+
+- Schema-based mocks are generated automatically. To create a new mock for an endpoint, run a Vitest test (or the app in dev) that calls that endpoint. The first call writes a fixture under `src/mocks/fixtures/<sanitized-path>/<method>.ts`.
+- To adjust the payload, edit the generated fixture file. Prefer this over adding a non-schema mock when you only need more realistic sample data.
+- Non-schema mocks live in `src/mocks/customHandlers` and take precedence over schema-based mocks. Use these for behavior overrides or endpoints without schema.
+
+- Global test setup: Add common mocks to `vitest.setup.ts` (e.g., `next/headers`, `next/navigation`, `next/image`, `sonner`, auth client). Before copying a mock into a test file, check if it can be centralized globally. Reset all mocks globally between tests.
+
 ## Next.js App Router Key Concepts
 
 ### File-System Routing
@@ -134,8 +147,8 @@ app/
 
 ```typescript
 async function ServerList() {
-  const response = await fetch("http://api/servers", {
-    next: { revalidate: 3600 }, // Cache for 1 hour
+  const response = await fetch("/registry/v0.1/servers", {
+    next: { revalidate: 3600 }, // In dev, Next rewrites proxy to mock server
   });
   const data = await response.json();
   return <ServerList servers={data} />;
@@ -242,7 +255,7 @@ export async function createServer(formData: FormData) {
 ### ❌ NEVER DO
 
 - **Use `any` type** - STRICTLY FORBIDDEN. Use `unknown` + type guards or proper types
-- Edit files in `src/generated/*` (auto-generated)
+- **Edit files in `src/generated/*`** - Auto-generated, will be overwritten on regeneration
 - Use `'use client'` on every component
 - Create manual fetch logic in components
 - Use `.then()` promise chains
@@ -262,21 +275,42 @@ export async function createServer(formData: FormData) {
 
 ### Using Generated API Client
 
-**Queries (GET)**:
+**⚠️ IMPORTANT:**
+- Never edit files in `src/generated/*`** - they are auto-generated and will be overwritten
+- **Always use server actions** - Client components should not call the API directly
+- The API client is server-side only (no `NEXT_PUBLIC_` env vars needed)
+
+**Example: Server Action**:
 
 ```typescript
-import { useGetApiV0Servers } from "@/generated/client/@tanstack/react-query.gen";
+// src/app/catalog/actions.ts
+"use server";
+
+import { getRegistryV01Servers } from "@/generated/sdk.gen";
 
-const { data, isLoading, error } = useGetApiV0Servers();
+export async function getServersSummary() {
+  try {
+    const resp = await getRegistryV01Servers();
+    const data = resp.data;
+    // Process data...
+    return { count: data?.servers?.length ?? 0, ... };
+  } catch (error) {
+    console.error("Failed to fetch servers:", error);
+    return { count: 0, ... };
+  }
+}
 ```
 
-**Mutations (POST/PUT/DELETE)**:
+**Example: Server Component**:
 
 ```typescript
-import { usePostApiV0Servers } from "@/generated/client/@tanstack/react-query.gen";
+// src/app/catalog/page.tsx
+import { getServersSummary } from "./actions";
 
-const mutation = usePostApiV0Servers();
-await mutation.mutateAsync({ body: data });
+export default async function CatalogPage() {
+  const summary = await getServersSummary();
+  return <div>{summary.count} servers</div>;
+}
 ```
 
 **When Backend Changes**:

CLAUDE.md

@@ -67,11 +67,13 @@ This document provides context and guidelines for Claude (and other AI assistant
 
 ### 3. Generated API Client
 
-- **Never write manual fetch logic** - Always use hey-api generated hooks
+- **Never write manual fetch logic** - Always use hey-api generated functions
+- **Never edit generated files** - They are regenerated from OpenAPI spec and changes will be lost
+- **Use server actions for all API calls** - Client components should not call the API directly
 - API client regenerated from OpenAPI spec via custom script
-- Type-safe API calls with automatic loading/error states
+- Type-safe API calls with proper error handling
 
-**Why**: Generated client ensures type safety, eliminates manual state management, and stays in sync with backend API.
+**Why**: Generated client ensures type safety and stays in sync with backend API. Server-only API access keeps the backend URL secure and reduces client bundle size.
 
 ### 4. Async/Await Over Promises
 
@@ -137,7 +139,9 @@ pnpm generate-client:nofetch # Regenerate without fetching
 ### DON'T ❌
 
 1. **🚫 Don't EVER use `any` type** - STRICTLY FORBIDDEN. Use `unknown` + type guards or proper types
-2. **Don't edit generated files** - `src/generated/*` is auto-generated
+2. **🚫 Don't EVER edit generated files** - `src/generated/*` is auto-generated and will be overwritten
+   - Generated files are overwritten on every `pnpm generate-client` run
+   - If you need to configure or extend the client, do it in your own files
 3. **Don't use `'use client'` everywhere** - Only when necessary
 4. **Don't create custom fetch logic** - Use hey-api hooks
 5. **Don't use `.then()`** - Use async/await
@@ -198,11 +202,19 @@ pnpm generate-client:nofetch # Regenerate without fetching
 - Loading states and skeleton screens
 - Accessibility (keyboard navigation, screen readers)
 
-### Testing Tools
+### Mocking & Testing
+
+- **MSW Auto-Mocker**
+  - Auto-generates handlers from `swagger.json` and creates fixtures under `src/mocks/fixtures` on first run.
+  - Strict validation with Ajv + ajv-formats; fixtures are type-checked against `@api/types.gen` by default.
+  - Hand-written, non-schema mocks live in `src/mocks/customHandlers` and take precedence over schema-based mocks.
+  - Dev: `pnpm mock:server` starts a standalone HTTP mock on `http://localhost:9090` (configurable via `API_BASE_URL`). In dev, Next rewrites proxy `/registry/*` there; always use relative URLs like `/registry/v0.1/servers`.
+  - Regenerate by deleting specific fixture files.
+  - Create new fixtures by calling the desired endpoint in a Vitest test (or via the app in dev). The first call generates a TypeScript fixture file; customize the payload by editing that file instead of writing a new custom handler when you only need different sample data.
+  - Prefer global test setup for common mocks: add shared mocks to `vitest.setup.ts` (e.g., `next/headers`, `next/navigation`, `next/image`, `sonner`, auth client). Before adding a mock in a specific test file, check if it belongs in the global setup.
 
 - **Vitest** - Test runner (faster than Jest)
 - **Testing Library** - Component testing
-- **MSW** - API mocking
 - **jsdom** - DOM simulation
 
 ### Example Test

dev-auth/oidc-provider.mjs

@@ -1,7 +1,14 @@
+import { config } from "dotenv";
 import Provider from "oidc-provider";
 
-const ISSUER = "http://localhost:4000";
-const PORT = 4000;
+config();
+config({ path: ".env.local" });
+
+const ISSUER = process.env.OIDC_ISSUER_URL || "http://localhost:4000";
+const PORT = new URL(ISSUER).port || 4000;
+const CLIENT_ID = process.env.OIDC_CLIENT_ID || "better-auth-dev";
+const CLIENT_SECRET =
+  process.env.OIDC_CLIENT_SECRET || "dev-secret-change-in-production";
 
 // Simple in-memory account storage
 const accounts = {
@@ -17,8 +24,8 @@ const accounts = {
 const configuration = {
   clients: [
     {
-      client_id: "better-auth-dev",
-      client_secret: "dev-secret-change-in-production",
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
       redirect_uris: [
         // Better Auth genericOAuth uses /oauth2/callback/:providerId
         "http://localhost:3000/api/auth/oauth2/callback/oidc",
@@ -126,10 +133,10 @@ oidc.use(async (ctx, next) => {
 
 oidc.listen(PORT, () => {
   console.log(`🔐 OIDC Provider running at ${ISSUER}`);
-  console.log(`📝 Client ID: better-auth-dev`);
-  console.log(`🔑 Client Secret: dev-secret-change-in-production`);
+  console.log(`📝 Client ID: ${CLIENT_ID}`);
+  console.log(`🔑 Client Secret: ${CLIENT_SECRET}`);
   console.log(`👤 Test user: [email protected]`);
   console.log(
-    `\n⚙️  Update your .env.local with:\nOIDC_CLIENT_ID=better-auth-dev\nOIDC_CLIENT_SECRET=dev-secret-change-in-production\nOIDC_ISSUER=${ISSUER}`,
+    `\n⚙️  Update your .env.local with:\nOIDC_CLIENT_ID=${CLIENT_ID}\nOIDC_CLIENT_SECRET=${CLIENT_SECRET}\nOIDC_ISSUER_URL=${ISSUER}`,
   );
 });

docs/mocks.md

@@ -0,0 +1,26 @@
+MSW Auto-Mocker
+
+- Handlers: `src/mocks/handlers.ts` combines non-schema mocks and auto-generated mocks.
+- Non-schema mocks: add hand-written handlers in `src/mocks/customHandlers/index.ts`. These take precedence over schema-based mocks.
+- Auto-generated: `src/mocks/mocker.ts` reads `swagger.json` and creates fixtures under `src/mocks/fixtures` on first run.
+- Validation: Loaded fixtures are validated with Ajv; errors log to console.
+
+Usage
+- Vitest: tests initialize MSW in `src/mocks/test.setup.ts`. Run `pnpm test`.
+- Browser (optional): call `startWorker()` from `src/mocks/browser.ts` in your development entry point to mock requests in the browser.
+- Standalone server (dev): `pnpm mock:server` starts an HTTP mock server at `http://localhost:9090` (configurable via `API_BASE_URL`). In dev, Next.js rewrites proxy `/registry/*` to this origin; use relative URLs like `/registry/v0.1/servers` from both client and server code.
+
+Generating fixtures
+- To create a new fixture for an endpoint, simply run a Vitest test (or the app in dev) that calls that endpoint. The auto‑mocker will generate `src/mocks/fixtures/<sanitized-path>/<method>.ts` on first use using schema‑based fake data.
+- To customize the response, edit the generated TypeScript file. This is preferred over writing a non‑schema mock for simple data tweaks (e.g., replacing lorem ipsum with realistic text). Non‑schema mocks are intended for behavior overrides or endpoints without schema.
+
+Regeneration
+- Delete a fixture file to re-generate it on next request.
+
+Failure behavior (always strict)
+- If a schema is missing or faker fails, the handler responds 500 and does not write a placeholder.
+- Invalid fixtures (including empty `{}` when the schema defines properties) respond 500.
+
+Types
+- Fixtures default to strict types. Generated modules import response types from `@api/types.gen` and use a `satisfies` clause to ensure compatibility.
+- Make sure `tsconfig.json` includes: `"paths": { "@api/*": ["./src/generated/*"] }`.

next.config.ts

@@ -1,9 +1,24 @@
 import type { NextConfig } from "next";
 
+const isDev = process.env.NODE_ENV !== "production";
+
 const nextConfig: NextConfig = {
   /* config options here */
   reactCompiler: true,
   output: "standalone",
+  async rewrites() {
+    if (!isDev) return [];
+
+    const apiBaseUrl = process.env.API_BASE_URL || "";
+
+    return [
+      // Proxy registry API in development (to mock server or real backend)
+      {
+        source: "/registry/:path*",
+        destination: `${apiBaseUrl}/registry/:path*`,
+      },
+    ];
+  },
 };
 
 export default nextConfig;

package.json

@@ -4,7 +4,7 @@
   "private": true,
   "packageManager": "[email protected]",
   "scripts": {
-    "dev": "concurrently -n \"OIDC,Next\" -c \"blue,green\" \"pnpm oidc\" \"pnpm dev:next\"",
+    "dev": "concurrently -n \"OIDC,Mock,Next\" -c \"blue,magenta,green\" \"pnpm oidc\" \"pnpm mock:server\" \"pnpm dev:next\"",
     "dev:next": "next dev",
     "build": "next build",
     "start": "next start",
@@ -16,13 +16,18 @@
     "oidc": "node dev-auth/oidc-provider.mjs",
     "generate-swagger": "tsx scripts/generate-swagger.ts",
     "generate-client": "pnpm run generate-swagger && openapi-ts",
-    "generate-client:nofetch": "openapi-ts"
+    "generate-client:nofetch": "openapi-ts",
+    "mock:server": "tsx src/mocks/server.ts"
   },
   "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "better-auth": "1.4.0-beta.25",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
     "jose": "^6.1.2",
+    "json-schema-faker": "^0.5.6",
+    "msw": "^2.12.2",
     "next": "16.0.3",
     "react": "19.2.0",
     "react-dom": "19.2.0",
@@ -33,6 +38,7 @@
     "@biomejs/biome": "2.3.6",
     "@hey-api/client-next": "0.5.1",
     "@hey-api/openapi-ts": "0.87.5",
+    "@mswjs/http-middleware": "^0.10.2",
     "@tailwindcss/postcss": "^4",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",
@@ -43,6 +49,7 @@
     "@vitejs/plugin-react": "^5.1.1",
     "babel-plugin-react-compiler": "1.0.0",
     "concurrently": "^9.2.1",
+    "dotenv": "^17.2.3",
     "husky": "^9.1.7",
     "jsdom": "^27.2.0",
     "lint-staged": "^16.0.0",