jsdoc for mock scenarios

Author: kantord

docs/mocks.md

@@ -224,18 +224,19 @@ export const mockedGetRegistryV01Servers = AutoAPIMock<GetRegistryV01ServersResp
 Then use them in tests:
 
 ```typescript
+import { MockScenarios } from "@mocks";
 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");
+    mockedGetRegistryV01Servers.useScenario(MockScenarios.EmptyServers);
 
     const servers = await getServers();
     expect(servers).toEqual([]);
   });
 
   it("throws on 500 server error", async () => {
-    mockedGetRegistryV01Servers.useScenario("server-error");
+    mockedGetRegistryV01Servers.useScenario(MockScenarios.ServerError);
 
     await expect(getServers()).rejects.toBeDefined();
   });
@@ -247,14 +248,14 @@ describe("getServers", () => {
 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 { activateMockScenario, MockScenarios } 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");
+    activateMockScenario(MockScenarios.ServerError);
 
     // Test that the app handles the error state correctly
     render(<App />);
@@ -263,7 +264,7 @@ describe("error handling", () => {
 
   it("handles partial failures gracefully", async () => {
     // Start with all APIs returning errors
-    activateMockScenario("server-error");
+    activateMockScenario(MockScenarios.ServerError);
 
     // Then customize specific endpoints to succeed
     mockedGetRegistryV01Servers.override((data) => data);
@@ -275,4 +276,4 @@ describe("error handling", () => {
 });
 ```
 
-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.
+Scenario names are defined in `src/mocks/scenarioNames.ts` via the `MockScenarios` object, which provides autocomplete and JSDoc documentation. Global scenarios are automatically reset before each test via `resetAllAutoAPIMocks()` in the test setup.

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

@@ -1,5 +1,4 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { activateMockScenario } from "@/mocks";
 import { getServerDetails } from "./actions";
 
 // Mock the auth to bypass authentication
@@ -48,7 +47,6 @@ 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/index.ts

@@ -5,3 +5,4 @@ export {
   resetAllAutoAPIMocks,
 } from "./autoAPIMock";
 export type { MockScenarioName } from "./scenarioNames";
+export { MockScenarios } from "./scenarioNames";

src/mocks/scenarioNames.ts

@@ -1,19 +1,18 @@
 /**
  * Global scenario names for API mocks.
  *
- * Define scenario names here so they can be reused across different mocks
- * with consistent naming and documentation.
+ * Use `MockScenarios.X` for autocomplete with documentation,
+ * or use the string literals directly.
  */
-
-/** Empty state - API returns no data */
-export type EmptyServers = "empty-servers";
-
-/** API returns 500 Internal Server Error */
-export type ServerError = "server-error";
+export const MockScenarios = {
+  /** Empty state - API returns no data */
+  EmptyServers: "empty-servers",
+  /** API returns 500 Internal Server Error */
+  ServerError: "server-error",
+} as const;
 
 /**
  * Union of all available mock scenario names.
- *
- * Add new scenario types above and include them in this union.
  */
-export type MockScenarioName = EmptyServers | ServerError;
+export type MockScenarioName =
+  (typeof MockScenarios)[keyof typeof MockScenarios];