@specbook/core 0.2.0 → 0.4.0

package/src/spec-config.ts

@@ -14,30 +14,33 @@ export interface JsonAuthProfile {
   oauth?: OAuthSettings
 }
 
+/** Gives the address a profile field should carry for a raw URL from the document. */
+type Address = (field: 'authorizationUrl' | 'tokenUrl' | 'openIdConnectUrl', raw: string) => string
+
 /** An OpenID Connect scheme: the discovery document says where to sign in. */
-function discovery(s: any, base: string | undefined): OAuthSettings | undefined {
+function discovery(s: any, address: Address): OAuthSettings | undefined {
   if (typeof s.openIdConnectUrl !== 'string' || s.openIdConnectUrl === '') return undefined
   try {
-    return { openIdConnectUrl: new URL(s.openIdConnectUrl, base).toString() }
+    return { openIdConnectUrl: address('openIdConnectUrl', s.openIdConnectUrl) }
   } catch {
     return undefined
   }
 }
 
 /** The authorization code flow of an OAuth scheme (OpenAPI 3 `flows`, or Swagger 2 `accessCode`). */
-function codeFlow(s: any, base: string | undefined): OAuthSettings | undefined {
+function codeFlow(s: any, address: Address): OAuthSettings | undefined {
   const flow = s.flows?.authorizationCode ?? (s.flow === 'accessCode' ? s : undefined)
   if (!flow?.authorizationUrl || !flow?.tokenUrl) return undefined
-  const abs = (u: string) => {
+  const abs = (field: 'authorizationUrl' | 'tokenUrl', u: string) => {
     try {
-      return new URL(u, base).toString()
+      return address(field, u)
     } catch {
       return u
     }
   }
   return {
-    authorizationUrl: abs(flow.authorizationUrl),
-    tokenUrl: abs(flow.tokenUrl),
+    authorizationUrl: abs('authorizationUrl', flow.authorizationUrl),
+    tokenUrl: abs('tokenUrl', flow.tokenUrl),
     ...(flow.scopes && Object.keys(flow.scopes).length ? { scopes: flow.scopes } : {}),
   }
 }
@@ -48,6 +51,12 @@ export interface SpecAuth {
   secrets: Record<string, Record<string, never>>
   /** the profile requests use unless they say otherwise */
   defaultProfile?: string
+  /**
+   * Sign-in addresses the document gives relative to its servers become variables, so each environment
+   * signs in at its own server: the `live` values here, and one entry per other environment below.
+   */
+  vars: Record<string, string>
+  environmentVars: Record<string, Record<string, string>>
 }
 
 const secretName = (scheme: string) =>
@@ -60,10 +69,41 @@ const secretName = (scheme: string) =>
  * Turns a document's security schemes into auth profiles whose secrets are filled in at run time, so
  * previewing a protected API only needs the user to paste a key. OAuth-style schemes take an access token.
  */
-export function authFromSpec(api: any, source?: string): SpecAuth {
+export function authFromSpec(api: any, source?: string, servers?: ServerEntry[]): SpecAuth {
   const schemes: Record<string, any> =
     api.components?.securitySchemes ?? api.securityDefinitions ?? {}
-  const out: SpecAuth = { auth: {}, secrets: {} }
+  const out: SpecAuth = { auth: {}, secrets: {}, vars: {}, environmentVars: {} }
+  const pageBase = source && isUrl(source) ? source : undefined
+  const resolve = (raw: string, base: string | undefined) => new URL(raw, base).toString()
+  // a relative address follows the server (OpenAPI 3.1): one variable per scheme and field, set per environment
+  const addressFor =
+    (scheme: string): Address =>
+    (field, raw) => {
+      if (!servers?.length || isUrl(raw)) return resolve(raw, pageBase)
+      const name = `${secretName(scheme)
+        .toLowerCase()
+        .replace(/_(.)/g, (_, c) => c.toUpperCase())}${field[0]?.toUpperCase()}${field.slice(1)}`
+      let any = false
+      for (const sv of servers) {
+        try {
+          const abs = resolve(raw, sv.url.endsWith('/') ? sv.url : `${sv.url}/`)
+          if (sv.name === 'live') out.vars[name] = abs
+          else out.environmentVars[sv.name] = { ...out.environmentVars[sv.name], [name]: abs }
+          any = true
+        } catch {
+          /* this server cannot resolve it */
+        }
+      }
+      if (!any) return resolve(raw, pageBase)
+      if (out.vars[name] === undefined) {
+        try {
+          out.vars[name] = resolve(raw, pageBase)
+        } catch {
+          out.vars[name] = raw
+        }
+      }
+      return `{{${name}}}`
+    }
   for (const [name, s] of Object.entries(schemes)) {
     const secret = secretName(name)
     const ref = `{{secrets.${secret}}}`
@@ -88,8 +128,8 @@ export function authFromSpec(api: any, source?: string): SpecAuth {
       title = `${name} (basic auth, paste base64 of user:password)`
     } else if (s.type === 'oauth2' || s.type === 'openIdConnect') {
       apply = { headers: { authorization: `Bearer ${ref}` } }
-      const base = source && isUrl(source) ? source : undefined
-      oauth = s.type === 'oauth2' ? codeFlow(s, base) : discovery(s, base)
+      const address = addressFor(name)
+      oauth = s.type === 'oauth2' ? codeFlow(s, address) : discovery(s, address)
       title = `${name} (OAuth, ${oauth ? 'sign in or ' : ''}paste an access token)`
     }
     if (!apply) continue
@@ -209,6 +249,32 @@ export function openApiServers(
   return { servers, needsBaseUrl, omitted }
 }
 
+/**
+ * What a document's servers become in a config: the first server's address as the variable `varName`, the
+ * others as the same variable in an environment of their own, and a `baseUrl` that reads it.
+ */
+export function environmentsFromServers(
+  servers: ServerEntry[],
+  varName: string,
+): {
+  vars: Record<string, string>
+  environments: Record<string, { description?: string; vars?: Record<string, string> }>
+  baseUrl: string
+} {
+  const vars: Record<string, string> = {}
+  const environments: Record<string, { description?: string; vars?: Record<string, string> }> = {}
+  for (const s of servers) {
+    const description = s.description ? { description: s.description } : {}
+    if (s.name === 'live') {
+      vars[varName] = s.url
+      if (s.description) environments.live = description
+    } else {
+      environments[s.name] = { ...description, vars: { [varName]: s.url } }
+    }
+  }
+  return { vars, environments, baseUrl: `{{${varName}}}` }
+}
+
 /** Where the API lives, from `servers[0]` (OpenAPI 3) or `host`/`basePath` (Swagger 2). */
 export function liveBaseUrl(api: any, source: string): string | undefined {
   return openApiServers(api, source).servers.find((s) => s.name === 'live')?.url

package/src/template.ts

@@ -2,8 +2,13 @@
 
 import { faker } from './faker'
 
-const WHOLE = /^\s*\{\{\s*([\w.$-]+)\s*\}\}\s*$/
-const EMBED = /\{\{\s*([\w.$-]+)\s*\}\}/g
+// a name is words joined by dots, and a position in an array can be a dot (`tags.0.name`) or brackets (`tags[0].name`)
+const NAME = String.raw`[\w.$\[\]-]+`
+const WHOLE = new RegExp(String.raw`^\s*\{\{\s*(${NAME})\s*\}\}\s*$`)
+const EMBED = new RegExp(String.raw`\{\{\s*(${NAME})\s*\}\}`, 'g')
+
+/** The variable a placeholder starts from: `tags` for `tags[0].name`, `pet` for `pet.category.name`. */
+export const rootName = (name: string): string => name.split(/[.[]/, 1)[0] as string
 
 /** Namespaces resolved at the transport boundary, never in the request model. */
 export const DEFERRED_NAMESPACES = ['secrets', 'session'] as const
@@ -39,11 +44,15 @@ export function usesFaker(value: unknown): boolean {
   return [...collectPlaceholders(value)].some(isFakerName)
 }
 
+/** `tags[0].name` is `tags.0.name`: a position in brackets is the same step as one after a dot. */
+const steps = (path: string) => path.replace(/\[(\d+)\]/g, '.$1').split('.')
+
 function lookup(scope: Record<string, unknown>, path: string): { found: boolean; value?: unknown } {
   if (isFakerName(path)) return fromFaker(path)
   let cur: unknown = scope
-  for (const part of path.split('.')) {
-    if (cur !== null && typeof cur === 'object' && part in (cur as object)) {
+  for (const part of steps(path)) {
+    // a value's own properties only: `toString` and `constructor` are not data, so a placeholder cannot reach them
+    if (cur !== null && typeof cur === 'object' && Object.hasOwn(cur as object, part)) {
       cur = (cur as Record<string, unknown>)[part]
     } else {
       return { found: false }

package/src/types.ts

@@ -63,11 +63,6 @@ export type DeepPartial<T> = T extends readonly (infer U)[]
 
 export type Source<T> = Templated<T> | (() => Promise<{ default: Templated<T> }>)
 
-/** Mock overrides are deep-merged over the generated example, so they only need the fields that matter. */
-export type PartialSource<T> =
-  | DeepPartial<Templated<T>>
-  | (() => Promise<{ default: DeepPartial<Templated<T>> }>)
-
 export type Init = Record<string, unknown>
 export type ResolvedInit<I> = { [K in keyof I]: I[K] extends () => infer R ? R : I[K] }
 
@@ -109,6 +104,10 @@ export interface RequestInput<T extends OpTypes, I extends Init = Init, C = {}>
   data?: Source<T['body']>
   encoding?: Encoding
   timeoutMs?: number
+  /** A request that only reads (a POST search, a GraphQL query): allowed in a read-only run. */
+  safe?: boolean
+  /** Labels to select this request by (`specbook test --tag monitor`) and to group it by in the UI. */
+  tags?: string[]
   capture?: { [K in keyof C]: (res: ResponseOf<T>, vars: ResolvedInit<I>) => C[K] }
   assert?: (
     res: ResponseOf<T>,
@@ -120,39 +119,50 @@ export interface RequestInput<T extends OpTypes, I extends Init = Init, C = {}>
       req: RenderedRequest
     },
   ) => void | Promise<void>
-  mock?: MockInput<T, I>
   auth?: AuthProfileName | false
   assertMode?: AssertMode
 }
 
-export interface MockResponse<B> {
-  data?: PartialSource<B>
-  init?: Init
-  headers?: Record<string, string>
-  delayMs?: number
+/** What the request being answered looks like to a mock: its values, as they were sent. */
+export interface MockReq<I> {
+  vars: ResolvedInit<I> & Record<string, unknown>
+  body: unknown
+  query: unknown
+  path: unknown
+  headers: Record<string, string>
 }
 
-export interface MockInput<T extends OpTypes, I> {
-  /**
-   * Echo request values into the generated response (fields it shares with the body, the path id).
-   * Default true; explicit `responses` always win.
-   */
-  reflect?: boolean
-  status?: keyof T['responses'] & number
-  responses?: {
-    [S in keyof T['responses'] & number]?:
-      | PartialSource<T['responses'][S]>
-      | MockResponse<T['responses'][S]>
+/**
+ * The answer a mock is about to give, one shape per status the operation declares so that checking `res.status` narrows
+ * `res.data`. Change `data`, `headers` and `delayMs` in place, or `respond` with another status.
+ */
+export type MockRes<T extends OpTypes> = {
+  [S in keyof T['responses'] & number]: {
+    status: S
+    data: T['responses'][S]
+    headers: Record<string, string>
+    /** Wait this long before answering. */
+    delayMs: number
+    /**
+     * Answer with another status the operation declares: its generated example, with `data` merged over it. Request values
+     * are echoed into a 2xx example as usual.
+     */
+    respond<R extends keyof T['responses'] & number>(
+      status: R,
+      data?: DeepPartial<T['responses'][R]>,
+    ): void
   }
-  when?: (req: {
-    vars: ResolvedInit<I>
-    body: unknown
-    query: unknown
-    path: unknown
-  }) => (keyof T['responses'] & number) | undefined
-}
+}[keyof T['responses'] & number]
+
+/** Runs when the `mock` environment answers this request, after the example is chosen, filled from the request and rendered. */
+export type MockHook<T extends OpTypes, I> = (
+  req: MockReq<I>,
+  res: MockRes<T>,
+) => void | Promise<void>
 
 export interface RequestOverrides<T extends OpTypes, I, C2> {
+  /** Added to the request's own tags. */
+  tags?: string[]
   vars?: Partial<ResolvedInit<I>> & Record<string, unknown>
   path?: Partial<Templated<T['params']['path']>>
   query?: Partial<Templated<T['params']['query']>>
@@ -160,7 +170,6 @@ export interface RequestOverrides<T extends OpTypes, I, C2> {
   data?: DeepPartial<Templated<T['body']>>
   capture?: { [K in keyof C2]: (res: ResponseOf<T>) => C2[K] }
   assert?: RequestInput<T, any, any>['assert']
-  mock?: { status?: keyof T['responses'] & number }
   auth?: AuthProfileName | false
   assertMode?: AssertMode
 }
@@ -171,8 +180,10 @@ export interface RequestDef<T extends OpTypes = AnyOp, I extends Init = Init, C
   readonly input: RequestInput<T, I, C>
   /** Deep-merge patches applied to the rendered data template, in order. */
   readonly dataPatches: readonly unknown[]
-  /** Explicit `.with({ vars })`; beats captures and params, only UI overrides are higher. */
+  /** Explicit `.with({ vars })`; beats captures and inputs, only UI overrides are higher. */
   readonly varOverrides: Readonly<Record<string, unknown>>
+  /** Set by `withMock`: how the mock environment answers this request. */
+  readonly mockHook?: MockHook<T, I>
   /** Phantom: lets sequence steps infer the captured type. */
   readonly _captured?: C
   with<C2 = {}>(o: RequestOverrides<T, I, C2>): RequestDef<T, I, C & C2>
@@ -208,7 +219,7 @@ export interface RenderedRequest {
 /** Where a placeholder's value came from, highest precedence first. */
 export interface VarUse {
   key: string
-  source: 'override' | 'capture' | 'param' | 'init' | 'config'
+  source: 'override' | 'capture' | 'input' | 'init' | 'config'
   /** Step that produced it, for captures. */
   step?: string
   /** A capture replaced a value of another type (e.g. a string id in an integer slot). */
@@ -241,6 +252,12 @@ export interface RunResult {
   seed?: number
   usedDrafts: boolean
   tags: string[]
+  /** The project file the request or flow comes from, relative to the project; set by the CLI. */
+  file?: string
+  /** How many times it was run when retries were allowed (1 = no retry); set by the CLI. */
+  attempts?: number
+  /** It failed, then passed on a retry; set by the CLI. */
+  flaky?: boolean
   status: 'pass' | 'fail' | 'error'
   startedAt: string
   durationMs: number