encourage type safety in mock overrides

Author: kantord

docs/mocks.md

@@ -53,18 +53,19 @@ import { mockedGetRegistryV01Servers } from "@mocks/fixtures/registry_v0_1_serve
 
 describe("ServerList", () => {
   it("shows empty state when no servers", async () => {
-    // Override to return empty list for this test only
-    mockedGetRegistryV01Servers.override(() =>
-      HttpResponse.json({ servers: [], metadata: { count: 0 } })
-    );
+    // Override to return empty list for this test only (type-safe)
+    mockedGetRegistryV01Servers.override(() => ({
+      servers: [],
+      metadata: { count: 0 },
+    }));
 
     render(<ServerList />);
     expect(screen.getByText("No servers available")).toBeVisible();
   });
 
   it("shows error state on API failure", async () => {
-    // Override to return an error
-    mockedGetRegistryV01Servers.override(() =>
+    // Use overrideHandler for error responses
+    mockedGetRegistryV01Servers.overrideHandler(() =>
       HttpResponse.json({ error: "Server error" }, { status: 500 })
     );
 
@@ -87,11 +88,11 @@ interface AutoAPIMockInstance<T> {
   // The default fixture data
   defaultValue: T;
 
-  // Override the response for the current test (full control)
-  override(fn: (data: T, info: ResponseResolverInfo) => Response): this;
+  // Override the response data (type-safe, preferred)
+  override(fn: (data: T, info: ResponseResolverInfo) => T): this;
 
-  // Override just the response data (simpler API)
-  overrideResponse(fn: (data: T, info: ResponseResolverInfo) => T): this;
+  // Override the full handler (for errors, network failures, invalid data)
+  overrideHandler(fn: (data: T, info: ResponseResolverInfo) => Response): this;
 
   // Reset to default behavior (called automatically before each test)
   reset(): this;
@@ -101,41 +102,41 @@ interface AutoAPIMockInstance<T> {
 }
 ```
 
-### Choosing Between `override` and `overrideResponse`
+### Choosing Between `override` and `overrideHandler`
 
-Use **`overrideResponse`** (simpler) when you just want to change the response data:
+Use **`override`** (type-safe, preferred) when you just want to change the response data:
 
 ```typescript
 // Simple - just return the data you want
-mockedGetRegistryV01Servers.overrideResponse(() => ({
+mockedGetRegistryV01Servers.override(() => ({
   servers: [],
   metadata: { count: 0 },
 }));
 
 // With default data modifications
-mockedGetRegistryV01Servers.overrideResponse((data) => ({
+mockedGetRegistryV01Servers.override((data) => ({
   ...data,
   servers: data.servers?.slice(0, 3),
 }));
 ```
 
-Use **`override`** (full control) when you need:
+Use **`overrideHandler`** (full control) when you need:
 - Custom HTTP status codes (errors)
 - Non-JSON responses
 - Network errors
 - Invalid/malformed data for edge case testing
 
 ```typescript
 // Return error status
-mockedGetRegistryV01Servers.override(() =>
+mockedGetRegistryV01Servers.overrideHandler(() =>
   HttpResponse.json({ error: "Server error" }, { status: 500 })
 );
 
 // Network error
-mockedGetRegistryV01Servers.override(() => HttpResponse.error());
+mockedGetRegistryV01Servers.overrideHandler(() => HttpResponse.error());
 
 // Testing invalid data shapes
-mockedGetRegistryV01Servers.override(() =>
+mockedGetRegistryV01Servers.overrideHandler(() =>
   HttpResponse.json({ servers: [{ server: null }] })
 );
 ```
@@ -149,14 +150,14 @@ Overrides are automatically reset before each test via `beforeEach()` in `src/mo
 Access the default fixture data to make partial modifications:
 
 ```typescript
-// With overrideResponse (cleaner)
-mockedGetRegistryV01Servers.overrideResponse((data) => ({
+// With override (type-safe, preferred)
+mockedGetRegistryV01Servers.override((data) => ({
   ...data,
   servers: data.servers?.slice(0, 1),
 }));
 
-// With override (when you need the Response wrapper)
-mockedGetRegistryV01Servers.override((data) =>
+// With overrideHandler (when you need the Response wrapper)
+mockedGetRegistryV01Servers.overrideHandler((data) =>
   HttpResponse.json({
     ...data,
     servers: data.servers?.slice(0, 1),
@@ -169,16 +170,16 @@ mockedGetRegistryV01Servers.override((data) =>
 Both methods receive request info as the second parameter:
 
 ```typescript
-// With overrideResponse
-mockedGetRegistryV01Servers.overrideResponse((data, info) => {
+// With override (type-safe)
+mockedGetRegistryV01Servers.override((data, info) => {
   const cursor = new URL(info.request.url).searchParams.get("cursor");
   return cursor === "page2"
     ? { servers: [], metadata: { count: 0 } }
     : data;
 });
 
-// With override (when you need different status codes based on request)
-mockedGetRegistryV01Servers.override((data, info) => {
+// With overrideHandler (when you need different status codes based on request)
+mockedGetRegistryV01Servers.overrideHandler((data, info) => {
   const authHeader = info.request.headers.get("Authorization");
   if (!authHeader) {
     return HttpResponse.json({ error: "Unauthorized" }, { status: 401 });

src/app/catalog/actions.test.ts

@@ -28,9 +28,8 @@ describe("getServers", () => {
       expect(servers[0].title).toBe("AWS Nova Canvas");
     });
 
-    // Using overrideResponse - simpler API when you just want to change the data
     it("returns empty array when API returns no servers", async () => {
-      mockedGetRegistryV01Servers.overrideResponse(() => ({
+      mockedGetRegistryV01Servers.override(() => ({
         servers: [],
         metadata: { count: 0 },
       }));
@@ -40,9 +39,11 @@ describe("getServers", () => {
       expect(servers).toEqual([]);
     });
 
-    // Using override - needed when returning non-JSON responses like null
+    // Using overrideHandler - needed when returning non-JSON responses like null
     it("returns empty array when API returns null data", async () => {
-      mockedGetRegistryV01Servers.override(() => HttpResponse.json(null));
+      mockedGetRegistryV01Servers.overrideHandler(() =>
+        HttpResponse.json(null),
+      );
 
       const servers = await getServers();
 
@@ -51,34 +52,34 @@ describe("getServers", () => {
   });
 
   describe("error handling", () => {
-    // Using override - needed for error status codes
+    // Using overrideHandler - needed for error status codes
     it("throws on 500 server error", async () => {
-      mockedGetRegistryV01Servers.override(() =>
+      mockedGetRegistryV01Servers.overrideHandler(() =>
         HttpResponse.json({ error: "Internal Server Error" }, { status: 500 }),
       );
 
       await expect(getServers()).rejects.toBeDefined();
     });
 
     it("throws on 401 unauthorized", async () => {
-      mockedGetRegistryV01Servers.override(() =>
+      mockedGetRegistryV01Servers.overrideHandler(() =>
         HttpResponse.json({ error: "Unauthorized" }, { status: 401 }),
       );
 
       await expect(getServers()).rejects.toBeDefined();
     });
 
     it("throws on network error", async () => {
-      mockedGetRegistryV01Servers.override(() => HttpResponse.error());
+      mockedGetRegistryV01Servers.overrideHandler(() => HttpResponse.error());
 
       await expect(getServers()).rejects.toBeDefined();
     });
   });
 
   describe("data transformation", () => {
-    // Using override - needed when testing invalid data shapes (null servers)
+    // Using overrideHandler - needed when testing invalid data shapes (null servers)
     it("filters out null servers from response", async () => {
-      mockedGetRegistryV01Servers.override((data) =>
+      mockedGetRegistryV01Servers.overrideHandler((data) =>
         HttpResponse.json({
           ...data,
           servers: [
@@ -99,9 +100,9 @@ describe("getServers", () => {
       ]);
     });
 
-    // Using override - needed when testing invalid data shapes (undefined servers)
+    // Using overrideHandler - needed when testing invalid data shapes (undefined servers)
     it("filters out undefined servers from response", async () => {
-      mockedGetRegistryV01Servers.override(() =>
+      mockedGetRegistryV01Servers.overrideHandler(() =>
         HttpResponse.json({
           servers: [
             { server: { name: "valid/server", title: "Valid" } },
@@ -118,9 +119,8 @@ describe("getServers", () => {
       expect(servers[0].name).toBe("valid/server");
     });
 
-    // Using overrideResponse - valid response structure
     it("extracts server objects from nested response structure", async () => {
-      mockedGetRegistryV01Servers.overrideResponse(() => ({
+      mockedGetRegistryV01Servers.override(() => ({
         servers: [
           {
             server: {
@@ -147,9 +147,8 @@ describe("getServers", () => {
   });
 
   describe("using default data in overrides", () => {
-    // Using overrideResponse - cleaner syntax for data modifications
     it("can modify specific server titles", async () => {
-      mockedGetRegistryV01Servers.overrideResponse((data) => ({
+      mockedGetRegistryV01Servers.override((data) => ({
         ...data,
         servers: data.servers?.map((item) => ({
           ...item,
@@ -166,7 +165,7 @@ describe("getServers", () => {
     });
 
     it("can limit the number of returned servers", async () => {
-      mockedGetRegistryV01Servers.overrideResponse((data) => ({
+      mockedGetRegistryV01Servers.override((data) => ({
         ...data,
         servers: data.servers?.slice(0, 3),
         metadata: { count: 3 },
@@ -178,7 +177,7 @@ describe("getServers", () => {
     });
 
     it("can filter servers by criteria", async () => {
-      mockedGetRegistryV01Servers.overrideResponse((data) => ({
+      mockedGetRegistryV01Servers.override((data) => ({
         ...data,
         servers: data.servers?.filter((item) =>
           item.server?.name?.includes("google"),
@@ -192,11 +191,10 @@ describe("getServers", () => {
   });
 
   describe("request-aware overrides", () => {
-    // Using overrideResponse with request info
-    it("can access request info in overrideResponse", async () => {
+    it("can access request info in override", async () => {
       let capturedUrl: string | undefined;
 
-      mockedGetRegistryV01Servers.overrideResponse((data, info) => {
+      mockedGetRegistryV01Servers.override((data, info) => {
         capturedUrl = info.request.url;
         return data;
       });
@@ -206,9 +204,9 @@ describe("getServers", () => {
       expect(capturedUrl).toContain("/registry/v0.1/servers");
     });
 
-    // Using override - needed when response depends on request and may return different status codes
+    // Using overrideHandler - needed when response depends on request and may return different status codes
     it("can vary response based on request headers", async () => {
-      mockedGetRegistryV01Servers.override((data, info) => {
+      mockedGetRegistryV01Servers.overrideHandler((data, info) => {
         const authHeader = info.request.headers.get("Authorization");
         if (authHeader?.includes("mock-token")) {
           return HttpResponse.json(data);

src/mocks/autoAPIMock.ts

@@ -3,13 +3,13 @@ import { HttpResponse } from "msw";
 
 type ResponseResolverInfo = Parameters<HttpResponseResolver>[0];
 
-type OverrideFn<T> = (data: T, info: ResponseResolverInfo) => Response;
-type OverrideResponseFn<T> = (data: T, info: ResponseResolverInfo) => T;
+type OverrideHandlerFn<T> = (data: T, info: ResponseResolverInfo) => Response;
+type OverrideFn<T> = (data: T, info: ResponseResolverInfo) => T;
 
 export interface AutoAPIMockInstance<T> {
   generatedHandler: HttpResponseResolver;
   override: (fn: OverrideFn<T>) => AutoAPIMockInstance<T>;
-  overrideResponse: (fn: OverrideResponseFn<T>) => AutoAPIMockInstance<T>;
+  overrideHandler: (fn: OverrideHandlerFn<T>) => AutoAPIMockInstance<T>;
   reset: () => AutoAPIMockInstance<T>;
   defaultValue: T;
 }
@@ -18,31 +18,31 @@ export interface AutoAPIMockInstance<T> {
 const registry: Set<AutoAPIMockInstance<unknown>> = new Set();
 
 export function AutoAPIMock<T>(defaultValue: T): AutoAPIMockInstance<T> {
-  let overrideFn: OverrideFn<T> | null = null;
+  let overrideHandlerFn: OverrideHandlerFn<T> | null = null;
 
   const instance: AutoAPIMockInstance<T> = {
     defaultValue,
 
     generatedHandler(info: ResponseResolverInfo) {
-      if (overrideFn) {
-        return overrideFn(defaultValue, info);
+      if (overrideHandlerFn) {
+        return overrideHandlerFn(defaultValue, info);
       }
       return HttpResponse.json(defaultValue as JsonBodyType);
     },
 
     override(fn: OverrideFn<T>) {
-      overrideFn = fn;
-      return instance;
-    },
-
-    overrideResponse(fn: OverrideResponseFn<T>) {
-      return instance.override((data, info) =>
+      return instance.overrideHandler((data, info) =>
         HttpResponse.json(fn(data, info) as JsonBodyType),
       );
     },
 
+    overrideHandler(fn: OverrideHandlerFn<T>) {
+      overrideHandlerFn = fn;
+      return instance;
+    },
+
     reset() {
-      overrideFn = null;
+      overrideHandlerFn = null;
       return instance;
     },
   };