simple way to activate same scenario across multipl mocks

Author: kantord

docs/mocks.md

@@ -240,3 +240,39 @@ describe("getServers", () => {
     await expect(getServers()).rejects.toBeDefined();
   });
 });
+```
+
+### Global Scenario Activation
+
+Use `activateMockScenario` to activate a scenario across all registered mocks at once. This is useful for setting up a consistent state across multiple endpoints, with the option to further customize individual mocks afterwards.
+
+```typescript
+import { activateMockScenario } from "@mocks";
+import { mockedGetRegistryV01Servers } from "@mocks/fixtures/registry_v0_1_servers/get";
+
+describe("error handling", () => {
+  it("shows error page when all APIs fail", async () => {
+    // Activate "server-error" on all mocks that define it
+    // Mocks without this scenario will use their default response
+    activateMockScenario("server-error");
+
+    // Test that the app handles the error state correctly
+    render(<App />);
+    expect(screen.getByText("Something went wrong")).toBeVisible();
+  });
+
+  it("handles partial failures gracefully", async () => {
+    // Start with all APIs returning errors
+    activateMockScenario("server-error");
+
+    // Then customize specific endpoints to succeed
+    mockedGetRegistryV01Servers.override((data) => data);
+
+    // Now only other endpoints return errors, servers endpoint works
+    render(<Dashboard />);
+    expect(screen.getByText("Servers loaded")).toBeVisible();
+  });
+});
+```
+
+Scenario names are defined in `src/mocks/scenarioNames.ts` and provide autocomplete and documentation across all mocks. Global scenarios are automatically reset before each test via `resetAllAutoAPIMocks()` in the test setup.

src/app/catalog/[repoName]/[serverName]/[version]/actions.test.ts

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { activateMockScenario } from "@/mocks";
 import { getServerDetails } from "./actions";
 
 // Mock the auth to bypass authentication
@@ -47,6 +48,7 @@ describe("getServerDetails", () => {
 
   describe("error handling", () => {
     it("returns 404 for non-existent server", async () => {
+      activateMockScenario("empty-servers");
       const result = await getServerDetails("non-existent/server", "1.0.0");
 
       expect(result.response.status).toBe(404);

src/mocks/autoAPIMock.ts

@@ -10,6 +10,11 @@ type ScenarioFn<T> = (
   instance: AutoAPIMockInstance<T>,
 ) => AutoAPIMockInstance<T>;
 
+export interface UseScenarioOptions {
+  /** If true, silently falls back to default when scenario doesn't exist. Default: false (throws) */
+  fallbackToDefault?: boolean;
+}
+
 export interface AutoAPIMockInstance<T> {
   generatedHandler: HttpResponseResolver;
   override: (fn: OverrideFn<T>) => AutoAPIMockInstance<T>;
@@ -18,7 +23,10 @@ export interface AutoAPIMockInstance<T> {
     name: MockScenarioName,
     fn: ScenarioFn<T>,
   ) => AutoAPIMockInstance<T>;
-  useScenario: (name: MockScenarioName) => AutoAPIMockInstance<T>;
+  useScenario: (
+    name: MockScenarioName,
+    options?: UseScenarioOptions,
+  ) => AutoAPIMockInstance<T>;
   reset: () => AutoAPIMockInstance<T>;
   defaultValue: T;
 }
@@ -56,9 +64,12 @@ export function AutoAPIMock<T>(defaultValue: T): AutoAPIMockInstance<T> {
       return instance;
     },
 
-    useScenario(name: MockScenarioName) {
+    useScenario(name: MockScenarioName, options?: UseScenarioOptions) {
       const scenarioFn = scenarios.get(name);
       if (!scenarioFn) {
+        if (options?.fallbackToDefault) {
+          return instance;
+        }
         throw new Error(
           `Scenario "${name}" not found. Available scenarios: ${[...scenarios.keys()].join(", ") || "(none)"}`,
         );
@@ -82,3 +93,14 @@ export function resetAllAutoAPIMocks(): void {
     instance.reset();
   }
 }
+
+/**
+ * Activate a scenario globally across all registered mocks.
+ * Mocks that don't have the scenario defined will silently use their default.
+ */
+export function activateMockScenario(name: MockScenarioName): void {
+  for (const instance of registry) {
+    // biome-ignore lint/correctness/useHookAtTopLevel: useScenario is not a React hook
+    instance.useScenario(name, { fallbackToDefault: true });
+  }
+}

src/mocks/index.ts

@@ -1,3 +1,7 @@
-export type { AutoAPIMockInstance } from "./autoAPIMock";
-export { AutoAPIMock, resetAllAutoAPIMocks } from "./autoAPIMock";
+export type { AutoAPIMockInstance, UseScenarioOptions } from "./autoAPIMock";
+export {
+  AutoAPIMock,
+  activateMockScenario,
+  resetAllAutoAPIMocks,
+} from "./autoAPIMock";
 export type { MockScenarioName } from "./scenarioNames";