allow creating reusable scenarios?

Author: kantord

docs/mocks.md

@@ -94,6 +94,12 @@ interface AutoAPIMockInstance<T> {
   // Override the full handler (for errors, network failures, invalid data)
   overrideHandler(fn: (data: T, info: ResponseResolverInfo) => Response): this;
 
+  // Define a reusable named scenario
+  scenario(name: string, fn: (instance: AutoAPIMockInstance<T>) => AutoAPIMockInstance<T>): this;
+
+  // Activate a named scenario for the current test
+  useScenario(name: string): this;
+
   // Reset to default behavior (called automatically before each test)
   reset(): this;
 
@@ -186,3 +192,51 @@ mockedGetRegistryV01Servers.overrideHandler((data, info) => {
   }
   return HttpResponse.json(data);
 });
+```
+
+### Reusable Scenarios
+
+Define named scenarios in your fixture for commonly used test states:
+
+```typescript
+// src/mocks/fixtures/registry_v0_1_servers/get.ts
+import type { GetRegistryV01ServersResponse } from "@api/types.gen";
+import { AutoAPIMock } from "@mocks";
+import { HttpResponse } from "msw";
+
+export const mockedGetRegistryV01Servers = AutoAPIMock<GetRegistryV01ServersResponse>({
+  servers: [...],
+  metadata: { count: 15 },
+})
+  .scenario("empty-servers", (self) =>
+    self.override(() => ({
+      servers: [],
+      metadata: { count: 0 },
+    })),
+  )
+  .scenario("server-error", (self) =>
+    self.overrideHandler(() =>
+      HttpResponse.json({ error: "Internal Server Error" }, { status: 500 }),
+    ),
+  );
+```
+
+Then use them in tests:
+
+```typescript
+import { mockedGetRegistryV01Servers } from "@mocks/fixtures/registry_v0_1_servers/get";
+
+describe("getServers", () => {
+  it("returns empty array when API returns no servers", async () => {
+    mockedGetRegistryV01Servers.useScenario("empty-servers");
+
+    const servers = await getServers();
+    expect(servers).toEqual([]);
+  });
+
+  it("throws on 500 server error", async () => {
+    mockedGetRegistryV01Servers.useScenario("server-error");
+
+    await expect(getServers()).rejects.toBeDefined();
+  });
+});

src/app/catalog/actions.test.ts

@@ -29,10 +29,7 @@ describe("getServers", () => {
     });
 
     it("returns empty array when API returns no servers", async () => {
-      mockedGetRegistryV01Servers.override(() => ({
-        servers: [],
-        metadata: { count: 0 },
-      }));
+      mockedGetRegistryV01Servers.useScenario("empty-servers");
 
       const servers = await getServers();
 
@@ -52,11 +49,9 @@ describe("getServers", () => {
   });
 
   describe("error handling", () => {
-    // Using overrideHandler - needed for error status codes
+    // Using scenario - reusable error scenario defined in fixture
     it("throws on 500 server error", async () => {
-      mockedGetRegistryV01Servers.overrideHandler(() =>
-        HttpResponse.json({ error: "Internal Server Error" }, { status: 500 }),
-      );
+      mockedGetRegistryV01Servers.useScenario("server-error");
 
       await expect(getServers()).rejects.toBeDefined();
     });

src/mocks/autoAPIMock.ts

@@ -5,11 +5,16 @@ type ResponseResolverInfo = Parameters<HttpResponseResolver>[0];
 
 type OverrideHandlerFn<T> = (data: T, info: ResponseResolverInfo) => Response;
 type OverrideFn<T> = (data: T, info: ResponseResolverInfo) => T;
+type ScenarioFn<T> = (
+  instance: AutoAPIMockInstance<T>,
+) => AutoAPIMockInstance<T>;
 
 export interface AutoAPIMockInstance<T> {
   generatedHandler: HttpResponseResolver;
   override: (fn: OverrideFn<T>) => AutoAPIMockInstance<T>;
   overrideHandler: (fn: OverrideHandlerFn<T>) => AutoAPIMockInstance<T>;
+  scenario: (name: string, fn: ScenarioFn<T>) => AutoAPIMockInstance<T>;
+  useScenario: (name: string) => AutoAPIMockInstance<T>;
   reset: () => AutoAPIMockInstance<T>;
   defaultValue: T;
 }
@@ -19,6 +24,7 @@ const registry: Set<AutoAPIMockInstance<unknown>> = new Set();
 
 export function AutoAPIMock<T>(defaultValue: T): AutoAPIMockInstance<T> {
   let overrideHandlerFn: OverrideHandlerFn<T> | null = null;
+  const scenarios = new Map<string, ScenarioFn<T>>();
 
   const instance: AutoAPIMockInstance<T> = {
     defaultValue,
@@ -41,6 +47,21 @@ export function AutoAPIMock<T>(defaultValue: T): AutoAPIMockInstance<T> {
       return instance;
     },
 
+    scenario(name: string, fn: ScenarioFn<T>) {
+      scenarios.set(name, fn);
+      return instance;
+    },
+
+    useScenario(name: string) {
+      const scenarioFn = scenarios.get(name);
+      if (!scenarioFn) {
+        throw new Error(
+          `Scenario "${name}" not found. Available scenarios: ${[...scenarios.keys()].join(", ") || "(none)"}`,
+        );
+      }
+      return scenarioFn(instance);
+    },
+
     reset() {
       overrideHandlerFn = null;
       return instance;

src/mocks/fixtures/registry_v0_1_servers/get.ts

@@ -1,5 +1,6 @@
 import type { GetRegistryV01ServersResponse } from "@api/types.gen";
 import { AutoAPIMock } from "@mocks";
+import { HttpResponse } from "msw";
 
 export const mockedGetRegistryV01Servers =
   AutoAPIMock<GetRegistryV01ServersResponse>({
@@ -486,4 +487,15 @@ export const mockedGetRegistryV01Servers =
       count: 15,
       nextCursor: "next-page",
     },
-  });
+  })
+    .scenario("empty-servers", (self) =>
+      self.override(() => ({
+        servers: [],
+        metadata: { count: 0 },
+      })),
+    )
+    .scenario("server-error", (self) =>
+      self.overrideHandler(() =>
+        HttpResponse.json({ error: "Internal Server Error" }, { status: 500 }),
+      ),
+    );