@bilal-fazlani/mock-server 0.2.1 → 0.3.0

package/.next/standalone/tests/global-mocks/actions.test.ts

@@ -0,0 +1,192 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const upsertGlobalMockScenarioMock = vi.fn()
+const clearGlobalMockScenarioMock = vi.fn()
+const resetDynamicHistoryMock = vi.fn()
+const revalidatePathMock = vi.fn()
+
+vi.mock('../../src/lib/profiles/store', () => ({
+  getDb: vi.fn(async () => ({})),
+  upsertGlobalMockScenario: (...args: unknown[]) => upsertGlobalMockScenarioMock(...args),
+  clearGlobalMockScenario: (...args: unknown[]) => clearGlobalMockScenarioMock(...args),
+}))
+
+vi.mock('../../src/lib/dynamic/history-store', () => ({
+  resetDynamicHistory: (...args: unknown[]) => resetDynamicHistoryMock(...args),
+}))
+
+vi.mock('next/cache', () => ({
+  revalidatePath: (...args: unknown[]) => revalidatePathMock(...args),
+}))
+
+const redirectMock = vi.fn((url: string) => {
+  throw new Error(`REDIRECT:${url}`)
+})
+vi.mock('next/navigation', () => ({
+  redirect: (url: string) => redirectMock(url),
+}))
+
+let passthroughAsDefault = false
+vi.mock('../../src/lib/runtime', () => ({
+  getRuntime: () => ({
+    passthroughAsDefault,
+    catalog: {
+      systems: [
+        {
+          name: 'Hello System',
+          slug: 'hello-system',
+          baseUrlEnv: 'HELLO_SYSTEM_URL',
+          endpoints: [
+            {
+              name: 'oauth_token',
+              displayName: 'OAuth Token',
+              method: 'POST',
+              path: '/oauth/token',
+              mockType: 'global',
+              scenarios: { default: 'Token', expired: 'Expired' },
+              resolverScenarios: [],
+            },
+            {
+              name: 'account_balance',
+              displayName: 'Account Balance',
+              method: 'POST',
+              path: '/accounts/balance',
+              mockType: 'global',
+              scenarios: { default: 'Settled', pending: 'Pending', dynamic: 'dynamic' },
+              resolverScenarios: ['dynamic'],
+            },
+            {
+              name: 'profiled_endpoint',
+              displayName: 'Profiled Endpoint',
+              method: 'POST',
+              path: '/profiled',
+              profileIdSelector: '$.customerId',
+              scenarios: { default: 'Success' },
+              resolverScenarios: [],
+            },
+          ],
+        },
+      ],
+    },
+  }),
+}))
+
+const { saveGlobalMocks, resetGlobalDynamicHistoryAction } = await import(
+  '../../src/app/ui/global-mocks/actions'
+)
+
+function formData(fields: Record<string, string>): FormData {
+  const fd = new FormData()
+  for (const [k, v] of Object.entries(fields)) fd.set(k, v)
+  return fd
+}
+
+beforeEach(() => {
+  upsertGlobalMockScenarioMock.mockClear()
+  clearGlobalMockScenarioMock.mockClear()
+  resetDynamicHistoryMock.mockClear()
+  revalidatePathMock.mockClear()
+  redirectMock.mockClear()
+  passthroughAsDefault = false
+})
+
+describe('saveGlobalMocks', () => {
+  it('clears default when passthrough is not the configured default', async () => {
+    await expect(
+      saveGlobalMocks(formData({ 'scenario:hello-system:oauth_token': 'default' })),
+    ).rejects.toThrow('REDIRECT:')
+
+    expect(clearGlobalMockScenarioMock).toHaveBeenCalledWith(
+      expect.anything(),
+      'hello-system',
+      'oauth_token',
+    )
+    expect(upsertGlobalMockScenarioMock).not.toHaveBeenCalled()
+  })
+
+  it('stores real when passthrough is not the configured default', async () => {
+    await expect(
+      saveGlobalMocks(formData({ 'scenario:hello-system:oauth_token': 'real' })),
+    ).rejects.toThrow('REDIRECT:')
+
+    expect(upsertGlobalMockScenarioMock).toHaveBeenCalledWith(expect.anything(), {
+      system: 'hello-system',
+      endpoint: 'oauth_token',
+      scenario: 'real',
+    })
+  })
+
+  it('clears real when passthrough is the configured default', async () => {
+    passthroughAsDefault = true
+    await expect(
+      saveGlobalMocks(formData({ 'scenario:hello-system:oauth_token': 'real' })),
+    ).rejects.toThrow('REDIRECT:')
+
+    expect(clearGlobalMockScenarioMock).toHaveBeenCalledWith(
+      expect.anything(),
+      'hello-system',
+      'oauth_token',
+    )
+  })
+
+  it('stores default when passthrough is the configured default', async () => {
+    passthroughAsDefault = true
+    await expect(
+      saveGlobalMocks(formData({ 'scenario:hello-system:oauth_token': 'default' })),
+    ).rejects.toThrow('REDIRECT:')
+
+    expect(upsertGlobalMockScenarioMock).toHaveBeenCalledWith(expect.anything(), {
+      system: 'hello-system',
+      endpoint: 'oauth_token',
+      scenario: 'default',
+    })
+  })
+
+  it('rejects undeclared fixture scenarios', async () => {
+    await expect(
+      saveGlobalMocks(formData({ 'scenario:hello-system:oauth_token': 'ghost' })),
+    ).rejects.toThrow(/not declared/)
+    expect(upsertGlobalMockScenarioMock).not.toHaveBeenCalled()
+    expect(clearGlobalMockScenarioMock).not.toHaveBeenCalled()
+  })
+
+  it('stores "dynamic" on a resolver-backed global endpoint', async () => {
+    await expect(
+      saveGlobalMocks(formData({ 'scenario:hello-system:account_balance': 'dynamic' })),
+    ).rejects.toThrow('REDIRECT:')
+
+    expect(upsertGlobalMockScenarioMock).toHaveBeenCalledWith(expect.anything(), {
+      system: 'hello-system',
+      endpoint: 'account_balance',
+      scenario: 'dynamic',
+    })
+  })
+
+  it('rejects "dynamic" on a global endpoint without a resolver', async () => {
+    await expect(
+      saveGlobalMocks(formData({ 'scenario:hello-system:oauth_token': 'dynamic' })),
+    ).rejects.toThrow(/not declared/)
+    expect(upsertGlobalMockScenarioMock).not.toHaveBeenCalled()
+    expect(clearGlobalMockScenarioMock).not.toHaveBeenCalled()
+  })
+})
+
+describe('resetGlobalDynamicHistoryAction', () => {
+  it('resets the global dynamic history and revalidates the page', async () => {
+    await resetGlobalDynamicHistoryAction('hello-system', 'oauth_token')
+
+    expect(resetDynamicHistoryMock).toHaveBeenCalledWith(
+      expect.anything(),
+      'global',
+      'hello-system',
+      'oauth_token',
+    )
+    expect(revalidatePathMock).toHaveBeenCalledWith('/ui/global-mocks')
+  })
+
+  it('rejects a missing system or endpoint', async () => {
+    await expect(resetGlobalDynamicHistoryAction('', 'oauth_token')).rejects.toThrow()
+    await expect(resetGlobalDynamicHistoryAction('hello-system', '')).rejects.toThrow()
+    expect(resetDynamicHistoryMock).not.toHaveBeenCalled()
+  })
+})

package/.next/standalone/tests/lib/config-catalog-dir.test.ts

@@ -0,0 +1,17 @@
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { resolveCatalogDir } from '../../src/lib/config'
+
+describe('resolveCatalogDir', () => {
+  it('defaults to <cwd>/catalog when unset', () => {
+    expect(resolveCatalogDir(undefined)).toBe(path.resolve('catalog'))
+  })
+
+  it('resolves a relative path against cwd', () => {
+    expect(resolveCatalogDir('./fixtures/catalog')).toBe(path.resolve('fixtures/catalog'))
+  })
+
+  it('passes an absolute path through unchanged', () => {
+    expect(resolveCatalogDir('/srv/catalog')).toBe('/srv/catalog')
+  })
+})

package/.next/standalone/tests/lib/config.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest'
+import {
+  ConfigError,
+  parseConsoleLogLevel,
+  parseResolverHistoryLimit,
+  parsePassthroughAsDefault,
+  parseRequestLogTtlSeconds,
+  parseUnmockedUsers,
+} from '../../src/lib/config'
+
+describe('parsePassthroughAsDefault', () => {
+  it('defaults to false when unset', () => {
+    expect(parsePassthroughAsDefault(undefined)).toBe(false)
+  })
+
+  it('accepts true and false values, case-insensitively', () => {
+    expect(parsePassthroughAsDefault('true')).toBe(true)
+    expect(parsePassthroughAsDefault('TRUE')).toBe(true)
+    expect(parsePassthroughAsDefault('false')).toBe(false)
+    expect(parsePassthroughAsDefault('FALSE')).toBe(false)
+  })
+
+  it('throws ConfigError for an unrecognized value', () => {
+    expect(() => parsePassthroughAsDefault('YES')).toThrow(ConfigError)
+  })
+})
+
+describe('parseUnmockedUsers', () => {
+  it('defaults to ERROR when unset', () => {
+    expect(parseUnmockedUsers(undefined)).toBe('ERROR')
+  })
+
+  it('accepts the three valid values, case-insensitively', () => {
+    expect(parseUnmockedUsers('error')).toBe('ERROR')
+    expect(parseUnmockedUsers('default_mock')).toBe('DEFAULT_MOCK')
+    expect(parseUnmockedUsers('REAL')).toBe('REAL')
+  })
+
+  it('throws ConfigError for an unrecognized value', () => {
+    expect(() => parseUnmockedUsers('MAYBE')).toThrow(ConfigError)
+  })
+})
+
+describe('parseConsoleLogLevel', () => {
+  it('defaults to info when unset', () => {
+    expect(parseConsoleLogLevel(undefined)).toBe('info')
+  })
+
+  it('accepts info, warn, and error values case-insensitively', () => {
+    expect(parseConsoleLogLevel('INFO')).toBe('info')
+    expect(parseConsoleLogLevel('warn')).toBe('warn')
+    expect(parseConsoleLogLevel('Error')).toBe('error')
+  })
+
+  it('throws ConfigError for an unrecognized value', () => {
+    expect(() => parseConsoleLogLevel('debug')).toThrow(ConfigError)
+  })
+})
+
+describe('parseResolverHistoryLimit', () => {
+  it('defaults to 10 when unset', () => {
+    expect(parseResolverHistoryLimit(undefined)).toBe(10)
+  })
+  it('parses a positive integer', () => {
+    expect(parseResolverHistoryLimit('25')).toBe(25)
+  })
+  it('rejects zero, negatives, and non-integers', () => {
+    expect(() => parseResolverHistoryLimit('0')).toThrow(ConfigError)
+    expect(() => parseResolverHistoryLimit('-3')).toThrow(ConfigError)
+    expect(() => parseResolverHistoryLimit('abc')).toThrow(ConfigError)
+    expect(() => parseResolverHistoryLimit('1.5')).toThrow(ConfigError)
+  })
+})
+
+describe('parseRequestLogTtlSeconds', () => {
+  it('defaults to 1 day (86400s) when unset or empty', () => {
+    expect(parseRequestLogTtlSeconds(undefined)).toBe(86400)
+    expect(parseRequestLogTtlSeconds('')).toBe(86400)
+  })
+
+  it('parses each supported unit into seconds', () => {
+    expect(parseRequestLogTtlSeconds('45s')).toBe(45)
+    expect(parseRequestLogTtlSeconds('30m')).toBe(1800)
+    expect(parseRequestLogTtlSeconds('24h')).toBe(86400)
+    expect(parseRequestLogTtlSeconds('7d')).toBe(604800)
+    expect(parseRequestLogTtlSeconds('1d')).toBe(86400)
+  })
+
+  it('rejects zero, missing unit, unsupported unit, and malformed values', () => {
+    expect(() => parseRequestLogTtlSeconds('0h')).toThrow(ConfigError)
+    expect(() => parseRequestLogTtlSeconds('100')).toThrow(ConfigError)
+    expect(() => parseRequestLogTtlSeconds('7w')).toThrow(ConfigError)
+    expect(() => parseRequestLogTtlSeconds('1d12h')).toThrow(ConfigError)
+    expect(() => parseRequestLogTtlSeconds('-3d')).toThrow(ConfigError)
+    expect(() => parseRequestLogTtlSeconds('1.5h')).toThrow(ConfigError)
+    expect(() => parseRequestLogTtlSeconds('abc')).toThrow(ConfigError)
+    expect(() => parseRequestLogTtlSeconds('h')).toThrow(ConfigError)
+  })
+})

package/.next/standalone/tests/lib/environment.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+import type { Catalog } from '../../src/lib/catalog/types'
+import { buildEnvironmentRows } from '../../src/lib/environment'
+
+const catalog: Catalog = {
+  systems: [
+    {
+      name: 'Hello System',
+      slug: 'hello-system',
+      baseUrlEnv: 'HELLO_SYSTEM_URL',
+      endpoints: [],
+    },
+    {
+      name: 'Orders',
+      slug: 'orders',
+      baseUrlEnv: 'ORDERS_URL',
+      endpoints: [],
+    },
+    {
+      name: 'Orders Duplicate',
+      slug: 'orders-duplicate',
+      baseUrlEnv: 'ORDERS_URL',
+      endpoints: [],
+    },
+  ],
+}
+
+describe('buildEnvironmentRows', () => {
+  it('renders app env vars and catalog upstream env vars without leaking the Mongo connection string value', () => {
+    const rows = buildEnvironmentRows(catalog, {
+      MONGODB_CONNECTION_STRING: 'mongodb://user:pass@localhost:27017',
+      MONGODB_DB: 'mockDB',
+      PASSTHROUGH_AS_DEFAULT: 'true',
+      UNMOCKED_USERS: 'REAL',
+      MOCK_CONSOLE_LOG_LEVEL: 'warn',
+      PASSTHROUGH_TIMEOUT_MS: '1000',
+      NODE_ENV: 'test',
+      HELLO_SYSTEM_URL: 'http://hello.test',
+      ORDERS_URL: 'http://orders.test',
+    })
+
+    expect(rows.map((row) => row.name)).toEqual([
+      'CATALOG_PATH',
+      'MONGODB_CONNECTION_STRING',
+      'MONGODB_DB',
+      'PASSTHROUGH_AS_DEFAULT',
+      'UNMOCKED_USERS',
+      'MOCK_CONSOLE_LOG_LEVEL',
+      'PASSTHROUGH_TIMEOUT_MS',
+      'RESOLVER_HISTORY_LIMIT',
+      'HELLO_SYSTEM_URL',
+      'ORDERS_URL',
+    ])
+    expect(rows.find((row) => row.name === 'MONGODB_CONNECTION_STRING')).toMatchObject({
+      category: 'System',
+      status: 'set',
+      value: 'Hidden',
+    })
+    expect(rows.find((row) => row.name === 'MONGODB_CONNECTION_STRING')?.value).not.toContain(
+      'mongodb://user:pass@localhost:27017',
+    )
+    expect(rows.find((row) => row.name === 'NODE_ENV')).toBeUndefined()
+    expect(rows.find((row) => row.name === 'ORDERS_URL')?.value).toBe('http://orders.test')
+  })
+
+  it('includes possible values for enum environment variables', () => {
+    const rows = buildEnvironmentRows(catalog, {})
+
+    expect(rows.find((row) => row.name === 'PASSTHROUGH_AS_DEFAULT')?.possibleValues).toEqual([
+      'true',
+      'false',
+    ])
+    expect(rows.find((row) => row.name === 'UNMOCKED_USERS')?.possibleValues).toEqual([
+      'ERROR',
+      'DEFAULT_MOCK',
+      'REAL',
+    ])
+    expect(rows.find((row) => row.name === 'MOCK_CONSOLE_LOG_LEVEL')?.possibleValues).toEqual([
+      'info',
+      'warn',
+      'error',
+    ])
+    expect(rows.find((row) => row.name === 'MONGODB_DB')?.possibleValues).toBeUndefined()
+  })
+
+  it('groups app variables into their display categories', () => {
+    const rows = buildEnvironmentRows(catalog, {})
+
+    expect(rows.find((row) => row.name === 'MONGODB_DB')?.category).toBe('System')
+    expect(rows.find((row) => row.name === 'MONGODB_CONNECTION_STRING')?.category).toBe('System')
+    expect(rows.find((row) => row.name === 'MOCK_CONSOLE_LOG_LEVEL')?.category).toBe('System')
+    expect(rows.find((row) => row.name === 'PASSTHROUGH_TIMEOUT_MS')?.category).toBe('Routing')
+    expect(rows.find((row) => row.name === 'PASSTHROUGH_AS_DEFAULT')?.category).toBe('Routing')
+    expect(rows.find((row) => row.name === 'HELLO_SYSTEM_URL')?.category).toBe('Upstream')
+  })
+
+  it('marks unset optional values with their default', () => {
+    const rows = buildEnvironmentRows(catalog, {})
+
+    expect(rows.find((row) => row.name === 'MONGODB_DB')).toMatchObject({
+      value: '(default: mockDB)',
+      status: 'default',
+    })
+    expect(rows.find((row) => row.name === 'HELLO_SYSTEM_URL')).toMatchObject({
+      value: '(not set)',
+      status: 'unset',
+    })
+  })
+
+  it('includes RESOLVER_HISTORY_LIMIT with a default of 10', () => {
+    const rows = buildEnvironmentRows({ systems: [] }, {})
+    const row = rows.find((r) => r.name === 'RESOLVER_HISTORY_LIMIT')
+    expect(row?.value).toBe('(default: 10)')
+  })
+})

package/.next/standalone/tests/lib/format.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from 'vitest'
+import { formatUtc } from '../../src/lib/format'
+
+describe('formatUtc', () => {
+  it('formats as YYYY-MM-DD HH:mm UTC', () => {
+    expect(formatUtc(new Date('2026-07-03T14:05:33.123Z'))).toBe('2026-07-03 14:05 UTC')
+  })
+})

package/.next/standalone/tests/lib/runtime.test.ts

@@ -0,0 +1,153 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const originalEnv = { ...process.env }
+const originalCwd = process.cwd()
+
+const tmpDirs: string[] = []
+
+function tmpProjectDir(files: Record<string, unknown>): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mock-runtime-'))
+  tmpDirs.push(dir)
+  for (const [rel, content] of Object.entries(files)) {
+    const full = path.join(dir, rel)
+    fs.mkdirSync(path.dirname(full), { recursive: true })
+    fs.writeFileSync(full, typeof content === 'string' ? content : JSON.stringify(content))
+  }
+  return dir
+}
+
+const SYSTEM_META = { name: 'Test System', baseUrlEnv: 'TEST_URL' }
+const ENDPOINT_META = {
+  displayName: 'Endpoint',
+  method: 'POST',
+  path: '/ep',
+  profileIdSelector: '$.customerId',
+}
+const FIXTURE = { status: 200, body: { ok: true } }
+
+afterEach(() => {
+  process.chdir(originalCwd)
+  process.env = { ...originalEnv }
+  vi.resetModules()
+  while (tmpDirs.length) fs.rmSync(tmpDirs.pop()!, { recursive: true, force: true })
+})
+
+describe('getRuntime', () => {
+  it('ignores legacy STRICT_MODE when parsing current routing config', async () => {
+    process.chdir(__dirname + '/../..')
+    process.env = {
+      ...originalEnv,
+      STRICT_MODE: 'true',
+      PASSTHROUGH_AS_DEFAULT: 'false',
+      UNMOCKED_USERS: 'ERROR',
+      MOCK_CONSOLE_LOG_LEVEL: 'warn',
+    }
+    vi.resetModules()
+    const { getRuntime } = await import('../../src/lib/runtime')
+
+    expect(getRuntime()).toMatchObject({
+      passthroughAsDefault: false,
+      unmockedUsers: 'ERROR',
+      consoleLogLevel: 'warn',
+    })
+  })
+
+  it('compiles a <slug>.ts resolver and serves it via getCompiledResolver, patching the label', async () => {
+    const dir = tmpProjectDir({
+      'catalog/sys/_system.json': SYSTEM_META,
+      'catalog/sys/ep/_endpoint.json': ENDPOINT_META,
+      'catalog/sys/ep/success.json': FIXTURE,
+      'catalog/sys/ep/default.ts': `export const description = 'Routes by amount'\nexport default () => 'success'`,
+    })
+    process.chdir(dir)
+    process.env = { ...originalEnv }
+    vi.resetModules()
+    const { getRuntime } = await import('../../src/lib/runtime')
+
+    const rt = getRuntime()
+    const resolver = rt.getCompiledResolver('sys', 'ep', 'default')
+    expect(resolver).not.toBeNull()
+    expect(resolver!.invoke({ request: { method: 'POST', path: '/ep', pathParams: {}, query: {}, headers: {}, body: null }, history: [], profileId: null }, 100)).toBe('success')
+    expect(rt.resolverHistoryLimit).toBe(10)
+    // The compiled module's `description` export patches the scenario label.
+    const ep = rt.catalog.systems[0].endpoints[0]
+    expect(ep.scenarios.default.label).toBe('Routes by amount')
+    expect(rt.getCompiledResolver('sys', 'ep', 'missing')).toBeNull()
+  })
+
+  it('patches a scenario summary from a resolver summary export', async () => {
+    const dir = tmpProjectDir({
+      'catalog/sys/_system.json': SYSTEM_META,
+      'catalog/sys/ep/_endpoint.json': ENDPOINT_META,
+      'catalog/sys/ep/success.json': FIXTURE,
+      'catalog/sys/ep/default.ts': `export const summary = 'Routes by amount'\nexport default () => 'success'`,
+    })
+    process.chdir(dir)
+    process.env = { ...originalEnv }
+    vi.resetModules()
+    const { getRuntime } = await import('../../src/lib/runtime')
+
+    const ep = getRuntime().catalog.systems[0].endpoints[0]
+    expect(ep.scenarios.default.summary).toBe('Routes by amount')
+  })
+
+  it('serves the resolver from the startup cache in production', async () => {
+    const dir = tmpProjectDir({
+      'catalog/sys/_system.json': SYSTEM_META,
+      'catalog/sys/ep/_endpoint.json': ENDPOINT_META,
+      'catalog/sys/ep/default.json': FIXTURE,
+      'catalog/sys/ep/pick.ts': `export default () => 'default'`,
+    })
+    process.chdir(dir)
+    process.env = { ...originalEnv, NODE_ENV: 'production' }
+    vi.resetModules()
+    const { getRuntime } = await import('../../src/lib/runtime')
+
+    const rt = getRuntime()
+    expect(rt.getCompiledResolver('sys', 'ep', 'pick')).not.toBeNull()
+
+    // Delete the source on disk: the prod cache-read path must keep serving the
+    // compiled resolver built at startup (a per-call re-read would throw/return null).
+    fs.rmSync(path.join(dir, 'catalog/sys/ep/pick.ts'))
+    const resolver = rt.getCompiledResolver('sys', 'ep', 'pick')
+    expect(resolver).not.toBeNull()
+    expect(
+      resolver!.invoke(
+        { request: { method: 'POST', path: '/ep', pathParams: {}, query: {}, headers: {}, body: null }, history: [], profileId: null },
+        100,
+      ),
+    ).toBe('default')
+  })
+
+  it('returns null for a slug that has no <slug>.ts resolver', async () => {
+    const dir = tmpProjectDir({
+      'catalog/sys/_system.json': SYSTEM_META,
+      'catalog/sys/ep/_endpoint.json': ENDPOINT_META,
+      'catalog/sys/ep/default.json': FIXTURE,
+    })
+    process.chdir(dir)
+    process.env = { ...originalEnv }
+    vi.resetModules()
+    const { getRuntime } = await import('../../src/lib/runtime')
+
+    expect(getRuntime().getCompiledResolver('sys', 'ep', 'default')).toBeNull()
+  })
+
+  it('fails startup when a <slug>.ts resolver does not compile', async () => {
+    const dir = tmpProjectDir({
+      'catalog/sys/_system.json': SYSTEM_META,
+      'catalog/sys/ep/_endpoint.json': ENDPOINT_META,
+      'catalog/sys/ep/default.json': FIXTURE,
+      'catalog/sys/ep/pick.ts': `export default (=>`,
+    })
+    process.chdir(dir)
+    process.env = { ...originalEnv }
+    vi.resetModules()
+    const { getRuntime } = await import('../../src/lib/runtime')
+
+    expect(() => getRuntime()).toThrow(/catalog validation failed/)
+  })
+})

package/.next/standalone/tests/lib/scenarios.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import type { EndpointDef } from '../../src/lib/catalog/types'
+import {
+  danglingScenarioLabel,
+  isScenarioDeclared,
+  scenarioOptionsWithDangling,
+  scenariosWithPassthrough,
+} from '../../src/lib/scenarios'
+
+const ep = (over: Partial<EndpointDef> = {}): EndpointDef => ({
+  name: 'ep', displayName: 'Ep', method: 'GET', path: '/ep',
+  scenarios: { default: { label: 'Default' }, frozen: { label: 'Frozen' } },
+  resolverScenarios: [],
+  ...over,
+})
+
+describe('scenariosWithPassthrough', () => {
+  it('appends real last when passthrough is not the default', () => {
+    const keys = Object.keys(scenariosWithPassthrough(ep(), false))
+    expect(keys).toEqual(['default', 'frozen', 'real'])
+  })
+
+  it('prepends real first when passthrough is the default', () => {
+    const keys = Object.keys(scenariosWithPassthrough(ep(), true))
+    expect(keys).toEqual(['real', 'default', 'frozen'])
+  })
+
+  it('no longer injects any synthetic entries beyond real', () => {
+    const endpoint = {
+      name: 'e', displayName: 'E', method: 'GET', path: '/e',
+      scenarios: { default: { label: 'default' }, 'by-amount': { label: 'Routes by amount' } },
+      resolverScenarios: ['by-amount'],
+    } as EndpointDef
+    expect(Object.keys(scenariosWithPassthrough(endpoint, false))).toEqual([
+      'default',
+      'by-amount',
+      'real',
+    ])
+  })
+})
+
+describe('isScenarioDeclared', () => {
+  it('accepts a declared fixture scenario', () => {
+    expect(isScenarioDeclared(ep(), 'frozen')).toBe(true)
+  })
+  it('accepts the "real" passthrough', () => {
+    expect(isScenarioDeclared(ep(), 'real')).toBe(true)
+  })
+  it('rejects an undeclared scenario', () => {
+    expect(isScenarioDeclared(ep(), 'ghost')).toBe(false)
+  })
+  it('accepts a resolver-backed slug like any other declared scenario', () => {
+    const endpoint = ep({ scenarios: { default: { label: 'Default' }, 'by-amount': { label: 'Routes' } }, resolverScenarios: ['by-amount'] })
+    expect(isScenarioDeclared(endpoint, 'by-amount')).toBe(true)
+  })
+})
+
+describe('danglingScenarioLabel', () => {
+  it('renders a generic unavailable label', () => {
+    expect(danglingScenarioLabel('frozen')).toBe('frozen — unavailable')
+  })
+})
+
+describe('scenarioOptionsWithDangling', () => {
+  const offered = { default: 'Default', real: 'Passthrough' }
+
+  it('leaves options untouched when the selection is offered', () => {
+    const r = scenarioOptionsWithDangling(offered, 'default')
+    expect(r.options).toEqual(offered)
+    expect(r.unavailable).toEqual([])
+  })
+
+  it('adds a dangling entry for a missing single selection', () => {
+    const r = scenarioOptionsWithDangling(offered, 'gone')
+    expect(r.options.gone).toBe('gone — unavailable')
+    expect(r.unavailable).toEqual(['gone'])
+  })
+
+  it('adds dangling entries for missing sequence steps', () => {
+    const r = scenarioOptionsWithDangling(offered, ['default', 'gone', 'vanished'])
+    expect(r.unavailable.sort()).toEqual(['gone', 'vanished'])
+    expect(r.options.gone).toBe('gone — unavailable')
+  })
+
+  it('ignores an undefined selection', () => {
+    expect(scenarioOptionsWithDangling(offered, undefined).unavailable).toEqual([])
+  })
+})