@bilal-fazlani/mock-server 0.2.1 → 0.3.0

package/.next/standalone/tests/catalog/find.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest'
+import type { Catalog } from '../../src/lib/catalog/find'
+import { findEndpointBySlug } from '../../src/lib/catalog/find'
+
+const catalog: Catalog = {
+  systems: [
+    {
+      name: 'Hello System',
+      slug: 'hello-system',
+      baseUrlEnv: 'HELLO_SYSTEM_URL',
+      endpoints: [
+        {
+          name: 'hello_world',
+          displayName: 'Hello World',
+          method: 'POST',
+          path: '/hello/world',
+          profileIdSelector: '$.customerId',
+          scenarios: { default: { label: 'Hello success' } },
+          resolverScenarios: [],
+        },
+      ],
+    },
+  ],
+}
+
+describe('findEndpointBySlug', () => {
+  it('finds an endpoint by system slug and endpoint name', () => {
+    const match = findEndpointBySlug(catalog, 'hello-system', 'hello_world')
+    expect(match?.system.name).toBe('Hello System')
+    expect(match?.endpoint.name).toBe('hello_world')
+  })
+
+  it('returns null for an unknown system slug', () => {
+    expect(findEndpointBySlug(catalog, 'nope-system', 'hello_world')).toBeNull()
+  })
+
+  it('returns null for an unknown endpoint name', () => {
+    expect(findEndpointBySlug(catalog, 'hello-system', 'goodbye')).toBeNull()
+  })
+})

package/.next/standalone/tests/catalog/load.test.ts

@@ -0,0 +1,258 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { CatalogLoadError, loadCatalog } from '../../src/lib/catalog/load'
+
+const tmpDirs: string[] = []
+
+function tmpCatalogDir(files: Record<string, unknown>): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mock-catalog-'))
+  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
+}
+
+afterEach(() => {
+  while (tmpDirs.length) fs.rmSync(tmpDirs.pop()!, { recursive: true, force: true })
+})
+
+const SYSTEM_META = { name: 'Test System', baseUrlEnv: 'TEST_URL' }
+const ENDPOINT_META = {
+  displayName: 'Hello World',
+  method: 'POST',
+  path: '/hello/world',
+  profileIdSelector: '$.customerId',
+}
+const FIXTURE = { description: 'Success', status: 200, body: { ok: true } }
+
+describe('loadCatalog', () => {
+  it('loads the example catalog systems', () => {
+    const catalog = loadCatalog(path.join(__dirname, '../../catalog'))
+    expect(catalog.systems.map((s) => s.slug)).toEqual(['hello-system'])
+    expect(catalog.systems.flatMap((s) => s.endpoints.map((e) => `${s.slug}/${e.name}`))).toEqual(
+      expect.arrayContaining(['hello-system/hello_world', 'hello-system/customer_status']),
+    )
+  })
+
+  it('derives scenario descriptions, falling back to the filename', () => {
+    const dir = tmpCatalogDir({
+      'sys/_system.json': SYSTEM_META,
+      'sys/ep/_endpoint.json': ENDPOINT_META,
+      'sys/ep/default.json': { status: 200, body: {} }, // no description
+      'sys/ep/failure.json': { description: 'It failed', status: 500, body: {} },
+    })
+    const catalog = loadCatalog(dir)
+    expect(catalog.systems[0].endpoints[0].scenarios).toEqual({
+      default: { label: 'default' },
+      failure: { label: 'It failed' },
+    })
+  })
+
+  it('derives scenario summaries from JSON fixtures when present', () => {
+    const dir = tmpCatalogDir({
+      'sys/_system.json': SYSTEM_META,
+      'sys/ep/_endpoint.json': ENDPOINT_META,
+      'sys/ep/default.json': { status: 200, body: {} }, // no summary
+      'sys/ep/failure.json': { description: 'It failed', summary: 'Upstream 500', status: 500, body: {} },
+    })
+    const ep = loadCatalog(dir).systems[0].endpoints[0]
+    expect(ep.scenarios).toEqual({
+      default: { label: 'default' },
+      failure: { label: 'It failed', summary: 'Upstream 500' },
+    })
+  })
+
+  it('orders scenarios default-first, then alphabetically', () => {
+    const dir = tmpCatalogDir({
+      'sys/_system.json': SYSTEM_META,
+      'sys/ep/_endpoint.json': ENDPOINT_META,
+      'sys/ep/zeta.json': FIXTURE,
+      'sys/ep/alpha.json': FIXTURE,
+      'sys/ep/default.json': FIXTURE,
+    })
+    const catalog = loadCatalog(dir)
+    expect(Object.keys(catalog.systems[0].endpoints[0].scenarios)).toEqual([
+      'default',
+      'alpha',
+      'zeta',
+    ])
+  })
+
+  it('throws one aggregated error listing every structural problem', () => {
+    const dir = tmpCatalogDir({
+      'stray.json': {}, // loose file in catalog root
+      'no-meta/ep/_endpoint.json': ENDPOINT_META, // system without _system.json
+      'no-meta/ep/default.json': FIXTURE,
+      'sys/_system.json': SYSTEM_META,
+      'sys/loose.json': {}, // loose file in a system dir
+      'sys/ep/default.json': FIXTURE, // endpoint without _endpoint.json
+      'sys/ep2/_endpoint.json': ENDPOINT_META,
+      'sys/ep2/default.json': FIXTURE,
+      'sys/ep2/Bad Name.json': FIXTURE, // invalid scenario filename
+    })
+    let message = ''
+    try {
+      loadCatalog(dir)
+    } catch (err) {
+      expect(err).toBeInstanceOf(CatalogLoadError)
+      message = (err as Error).message
+    }
+    expect(message).toMatch(/stray\.json/)
+    expect(message).toMatch(/_system\.json/)
+    expect(message).toMatch(/loose\.json/)
+    expect(message).toMatch(/_endpoint\.json/)
+    expect(message).toMatch(/Bad Name\.json/)
+  })
+
+  it('flags metadata files with missing fields or invalid JSON', () => {
+    const dir = tmpCatalogDir({
+      'sys/_system.json': { name: 'S' }, // missing baseUrlEnv
+      'sys/ep/_endpoint.json': 'not json {',
+      'sys/ep/default.json': FIXTURE,
+    })
+    let message = ''
+    try {
+      loadCatalog(dir)
+    } catch (err) {
+      message = (err as Error).message
+    }
+    expect(message).toMatch(/baseUrlEnv/)
+    expect(message).toMatch(/not valid JSON/)
+  })
+
+  it('ignores dotfiles at every level', () => {
+    const dir = tmpCatalogDir({
+      '.DS_Store': '',
+      'sys/_system.json': SYSTEM_META,
+      'sys/.DS_Store': '',
+      'sys/ep/_endpoint.json': ENDPOINT_META,
+      'sys/ep/.DS_Store': '',
+      'sys/ep/default.json': FIXTURE,
+    })
+    expect(() => loadCatalog(dir)).not.toThrow()
+  })
+
+  it('throws when the catalog directory does not exist', () => {
+    expect(() => loadCatalog('/nonexistent/catalog')).toThrow(CatalogLoadError)
+  })
+
+  it('loads an endpoint with metadata but zero scenario files as empty scenarios', () => {
+    const dir = tmpCatalogDir({
+      'sys/_system.json': SYSTEM_META,
+      'sys/ep/_endpoint.json': ENDPOINT_META,
+    })
+    const catalog = loadCatalog(dir)
+    expect(catalog.systems[0].endpoints[0].scenarios).toEqual({})
+  })
+
+  it('discovers <slug>.ts scenario files as resolver-backed scenarios', () => {
+    const dir = tmpCatalogDir({
+      'sys/_system.json': SYSTEM_META,
+      'sys/ep/_endpoint.json': ENDPOINT_META,
+      'sys/ep/default.json': FIXTURE,
+      'sys/ep/hold.json': FIXTURE,
+      'sys/ep/by-amount.ts': `export default () => 'default'`,
+    })
+    const catalog = loadCatalog(dir)
+    const ep = catalog.systems[0].endpoints[0]
+    expect(Object.keys(ep.scenarios)).toContain('by-amount')
+    expect(ep.scenarios['by-amount']).toEqual({ label: 'by-amount' }) // label = slug until runtime patches
+    expect(ep.resolverScenarios).toEqual(['by-amount'])
+  })
+
+  it('rejects a slug backed by both x.json and x.ts', () => {
+    const dir = tmpCatalogDir({
+      'sys/_system.json': SYSTEM_META,
+      'sys/ep/_endpoint.json': ENDPOINT_META,
+      'sys/ep/default.json': FIXTURE,
+      'sys/ep/hold.json': FIXTURE,
+      'sys/ep/hold.ts': `export default () => 'default'`,
+    })
+    expect(() => loadCatalog(dir)).toThrowError(/backed by both[\s\S]*hold\.json and hold\.ts/)
+  })
+
+  it('allows default.ts in place of default.json', () => {
+    const dir = tmpCatalogDir({
+      'sys/_system.json': SYSTEM_META,
+      'sys/ep/_endpoint.json': ENDPOINT_META,
+      'sys/ep/default.ts': `export default () => 'success'`,
+      'sys/ep/success.json': FIXTURE,
+    })
+    const ep = loadCatalog(dir).systems[0].endpoints[0]
+    expect(ep.resolverScenarios).toEqual(['default'])
+    expect(Object.keys(ep.scenarios)).toEqual(['default', 'success'])
+  })
+
+  it('loads captureProfileKeys from endpoint metadata', () => {
+    const dir = tmpCatalogDir({
+      'sys/_system.json': SYSTEM_META,
+      'sys/ep/_endpoint.json': {
+        ...ENDPOINT_META,
+        captureProfileKeys: [{ namespace: 'event-id', keySelector: '$.eventID' }],
+      },
+      'sys/ep/default.json': FIXTURE,
+    })
+    const endpoint = loadCatalog(dir).systems[0].endpoints[0]
+    expect(endpoint).toMatchObject({
+      captureProfileKeys: [{ namespace: 'event-id', keySelector: '$.eventID' }],
+    })
+  })
+
+  it('throws when captureProfileKeys metadata is structurally invalid', () => {
+    const dir = tmpCatalogDir({
+      'sys/_system.json': SYSTEM_META,
+      'sys/ep/_endpoint.json': {
+        ...ENDPOINT_META,
+        captureProfileKeys: [{ namespace: 'event-id' }],
+      },
+      'sys/ep/default.json': FIXTURE,
+    })
+
+    expect(() => loadCatalog(dir)).toThrow(CatalogLoadError)
+    expect(() => loadCatalog(dir)).toThrow(/captureProfileKeys/)
+  })
+})
+
+describe('loadCatalog _schema.json', () => {
+  const OP = {
+    responses: { '200': { content: { 'application/json': { schema: { type: 'object' } } } } },
+  }
+
+  it('attaches _schema.json to the endpoint when present', () => {
+    const dir = tmpCatalogDir({
+      'test-system/_system.json': SYSTEM_META,
+      'test-system/hello_world/_endpoint.json': ENDPOINT_META,
+      'test-system/hello_world/default.json': FIXTURE,
+      'test-system/hello_world/_schema.json': OP,
+    })
+    const catalog = loadCatalog(dir)
+    const ep = catalog.systems[0].endpoints[0]
+    expect(ep.schema).toEqual(OP)
+    expect(Object.keys(ep.scenarios)).toEqual(['default']) // _schema.json is not a scenario
+  })
+
+  it('leaves schema undefined when the file is absent', () => {
+    const dir = tmpCatalogDir({
+      'test-system/_system.json': SYSTEM_META,
+      'test-system/hello_world/_endpoint.json': ENDPOINT_META,
+      'test-system/hello_world/default.json': FIXTURE,
+    })
+    expect(loadCatalog(dir).systems[0].endpoints[0].schema).toBeUndefined()
+  })
+
+  it('fails hard on a malformed _schema.json', () => {
+    const dir = tmpCatalogDir({
+      'test-system/_system.json': SYSTEM_META,
+      'test-system/hello_world/_endpoint.json': ENDPOINT_META,
+      'test-system/hello_world/default.json': FIXTURE,
+      'test-system/hello_world/_schema.json': '{not json',
+    })
+    expect(() => loadCatalog(dir)).toThrow(CatalogLoadError)
+    expect(() => loadCatalog(dir)).toThrow(/_schema\.json/)
+  })
+})

package/.next/standalone/tests/catalog/path-template.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import {
+  matchPath,
+  parsePathTemplate,
+  PathTemplateError,
+  templatesOverlap,
+} from '../../src/lib/catalog/path-template'
+
+describe('parsePathTemplate', () => {
+  it('parses literal and param segments', () => {
+    const t = parsePathTemplate('/customers/{customerId}/bookings')
+    expect(t.segments).toEqual([
+      { type: 'literal', value: 'customers' },
+      { type: 'param', name: 'customerId' },
+      { type: 'literal', value: 'bookings' },
+    ])
+  })
+
+  it('rejects templates that do not start with /', () => {
+    expect(() => parsePathTemplate('hello/world')).toThrow(PathTemplateError)
+  })
+
+  it('rejects malformed param segments and empty segments', () => {
+    expect(() => parsePathTemplate('/a/{bad')).toThrow(PathTemplateError)
+    expect(() => parsePathTemplate('/a/b{c}')).toThrow(PathTemplateError)
+    expect(() => parsePathTemplate('/a//b')).toThrow(PathTemplateError)
+  })
+
+  it('tolerates a single trailing slash, normalizing it away', () => {
+    const t = parsePathTemplate('/transfer/{customerId}/')
+    expect(t.raw).toBe('/transfer/{customerId}')
+    expect(t.segments).toEqual([
+      { type: 'literal', value: 'transfer' },
+      { type: 'param', name: 'customerId' },
+    ])
+  })
+
+  it('still rejects a doubled trailing slash and root slash', () => {
+    expect(() => parsePathTemplate('/a//')).toThrow(PathTemplateError)
+    expect(() => parsePathTemplate('/')).toThrow(PathTemplateError)
+  })
+})
+
+describe('matchPath', () => {
+  const t = parsePathTemplate('/customers/{customerId}/bookings')
+
+  it('matches and captures params (URL-decoded)', () => {
+    expect(matchPath(t, '/customers/cus%2D42/bookings')).toEqual({ customerId: 'cus-42' })
+  })
+
+  it('returns null on literal mismatch or segment-count mismatch', () => {
+    expect(matchPath(t, '/customers/cus-42/orders')).toBeNull()
+    expect(matchPath(t, '/customers/cus-42')).toBeNull()
+    expect(matchPath(t, '/customers/cus-42/bookings/extra')).toBeNull()
+  })
+
+  it('matches literal-only templates with no params', () => {
+    const hello = parsePathTemplate('/hello/world')
+    expect(matchPath(hello, '/hello/world')).toEqual({})
+    expect(matchPath(hello, '/hello/mars')).toBeNull()
+  })
+})
+
+describe('templatesOverlap', () => {
+  it('detects overlap between a param and a literal in the same position', () => {
+    const a = parsePathTemplate('/customers/{id}')
+    const b = parsePathTemplate('/customers/recent')
+    expect(templatesOverlap(a, b)).toBe(true)
+  })
+
+  it('no overlap when literals differ or lengths differ', () => {
+    expect(
+      templatesOverlap(parsePathTemplate('/a/b'), parsePathTemplate('/a/c')),
+    ).toBe(false)
+    expect(
+      templatesOverlap(parsePathTemplate('/a/{x}'), parsePathTemplate('/a/{x}/y')),
+    ).toBe(false)
+  })
+})

package/.next/standalone/tests/catalog/request-example.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest'
+import { buildEndpointRequestExample } from '../../src/lib/catalog/request-example'
+import type { EndpointDef } from '../../src/lib/catalog/types'
+
+function endpoint(overrides: Partial<EndpointDef> = {}): EndpointDef {
+  return {
+    name: 'hello_world',
+    displayName: 'Hello World',
+    method: 'POST',
+    path: '/hello/world',
+    profileIdSelector: '$.customerId',
+    scenarios: { default: { label: 'Success' } },
+    resolverScenarios: [],
+    ...overrides,
+  }
+}
+
+describe('buildEndpointRequestExample', () => {
+  it('builds a body skeleton from a direct body selector', () => {
+    const example = buildEndpointRequestExample(endpoint())
+    expect(example).toEqual({
+      method: 'POST',
+      path: '/hello/world',
+      search: '',
+      headers: {},
+      body: { customerId: '<customerId>' },
+    })
+  })
+
+  it('merges nested selectors and capture keys into one body', () => {
+    const example = buildEndpointRequestExample(
+      endpoint({
+        profileIdSelector: '$.customer.customerId',
+        captureProfileKeys: [{ namespace: 'order-id', keySelector: '$.orderId' }],
+      }),
+    )
+    expect(example.body).toEqual({
+      customer: { customerId: '<customerId>' },
+      orderId: '<orderId>',
+    })
+  })
+
+  it('uses the inner selector of a profileKey lookup', () => {
+    const example = buildEndpointRequestExample(
+      endpoint({ profileIdSelector: 'profileKey:order-id:$.orderId' }),
+    )
+    expect(example.body).toEqual({ orderId: '<orderId>' })
+  })
+
+  it('fills path template params with placeholders', () => {
+    const example = buildEndpointRequestExample(
+      endpoint({
+        method: 'GET',
+        path: '/customers/{customerId}/status',
+        profileIdSelector: 'path:customerId',
+      }),
+    )
+    expect(example.method).toBe('GET')
+    expect(example.path).toBe('/customers/<customerId>/status')
+    expect(example.body).toBeNull()
+  })
+
+  it('puts query selectors into the search string', () => {
+    const example = buildEndpointRequestExample(
+      endpoint({ method: 'GET', path: '/lookup', profileIdSelector: 'query:cid' }),
+    )
+    expect(example.search).toBe('?cid=<cid>')
+    expect(example.body).toBeNull()
+  })
+
+  it('returns an empty body for endpoints without body selectors', () => {
+    const example = buildEndpointRequestExample(
+      endpoint({ mockType: 'global', profileIdSelector: undefined, path: '/oauth/token' }),
+    )
+    expect(example.body).toBeNull()
+  })
+
+  it('adds an authorization header for opaque and JWT-claim bearer selectors', () => {
+    expect(
+      buildEndpointRequestExample(endpoint({ profileIdSelector: 'bearer' })).headers,
+    ).toEqual({ authorization: 'Bearer <profileId>' })
+    expect(
+      buildEndpointRequestExample(endpoint({ profileIdSelector: 'bearer:sub' })).headers,
+    ).toEqual({ authorization: 'Bearer <JWT with sub claim>' })
+  })
+})