@frontera-sdk/functions 1.49.0

package/src/testing.ts

@@ -0,0 +1,323 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import {
+  duplicateStepMessage,
+  duplicateSubmissionMessage,
+  emptySubmissionKeyMessage,
+  missingGrantMessage,
+  submitOutsideStepMessage,
+} from './messages'
+import type {
+  ActionSubmission,
+  ActionSubmitResult,
+  AutomationContext,
+  BlueprintQueryOptions,
+  BlueprintQueryResult,
+  Grant,
+  HttpRequest,
+  HttpResponse,
+  PluginCallResult,
+} from './types'
+
+/**
+ * A `ctx` you can hand your handler in a unit test.
+ *
+ * Until this existed the only way to find out whether an automation worked was
+ * to deploy it and run it — a loop measured in tens of seconds, against real
+ * data, for a question as small as "does the empty branch return the right
+ * shape".
+ *
+ * It enforces what the platform enforces, in the platform's own words: a
+ * missing grant and a repeated step name fail here exactly as they fail in
+ * production, so a green test means something.
+ *
+ * What it does NOT simulate is resumption. In production a handler is re-entered
+ * after every step, so code outside a step runs many times; here the handler is
+ * called once, straight through. Steps still memoize by name within the run, and
+ * everything the handler did is recorded on `calls`.
+ */
+
+/**
+ * A call REFUSED before it happened is not recorded.
+ *
+ * A missing grant, a missing stub, a submit outside a step, a duplicate
+ * submission — none of these appear in `calls`, because none of them did
+ * anything. A real run differs here in one direction worth knowing: it writes
+ * an errored ctx-call row for a refused `ctx.action.submit`, so the Console
+ * trace shows the attempt where this list does not. Assert on the thrown error
+ * for a refusal, and on `calls` for what ran.
+ */
+export interface TestCall {
+  kind: 'step' | 'log' | 'agent' | 'plugin' | 'http' | 'blueprint' | 'action' | 'file'
+  /** Step name, log message, agent slug, `install:capability`, URL, object type, or Action apiName. */
+  label: string
+  /** Present on a step: how it ended. */
+  status?: 'ok' | 'error'
+}
+
+
+export interface TestContextOptions {
+  runId?: string
+  workspaceId?: string
+  /** What the run was started with. Passed through verbatim — a unit test
+   *  states exactly what the handler sees; defaults are `startRun`'s job. */
+  input?: Record<string, unknown>
+  /**
+   * The grants the manifest declares.
+   *
+   * Given, they are enforced — which is the point: a missing grant is one of
+   * the few automation bugs that only shows up in a deployed run, and it is
+   * exactly the kind a unit test should catch.
+   *
+   * Omitted, nothing is refused, so an existing test does not have to enumerate
+   * grants to keep passing.
+   */
+  grants?: readonly Grant[]
+  /** Per-slug agent answers. An unstubbed agent throws rather than answering. */
+  agents?: Record<string, (prompt: string) => Promise<{ text: string }> | { text: string }>
+  /** Per-fileId answers for `ctx.file`: what the resolved handle should carry.
+   *  An unstubbed fileId throws — a fabricated handle is a false pass. */
+  files?: Record<string, { signedUrl: string; mimeType: string; sizeBytes: number; name: string | null }>
+  /**
+   * Per-install, per-capability plugin answers: `{ crm: { create_ticket: (input) => ({ data }) } }`.
+   * An unstubbed capability throws rather than answering — a fabricated
+   * `{ data: {} }` is a test that passes while asserting nothing.
+   */
+  plugins?: Record<
+    string,
+    Record<string, (input: Record<string, unknown>) => Promise<PluginCallResult> | PluginCallResult>
+  >
+  /** Answers outbound requests. Unstubbed, `ctx.http.fetch` throws. */
+  http?: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse
+  /** Rows per object type. An unstubbed type returns no rows, which is a real
+   *  answer and usually the branch worth testing. */
+  blueprint?: Record<string, BlueprintQueryResult<never> | BlueprintQueryResult<Record<string, unknown>>>
+  /**
+   * Per-apiName Action outcomes. An unstubbed Action throws rather than
+   * answering.
+   *
+   * Throws for the same reason the agent stub does, and the reason is sharper
+   * here: the returned `lifecycle` is a branch an author writes code against —
+   * `awaiting_approval` means a human still has to decide — so inventing
+   * `ready` would silently pick one arm and pass.
+   */
+  actions?: Record<
+    string,
+    (request: ActionSubmission) => Promise<ActionSubmitResult> | ActionSubmitResult
+  >
+}
+
+export interface TestContext {
+  ctx: AutomationContext
+  /** Everything the handler did, in order. */
+  calls: TestCall[]
+  /** Step names, in the order they ran. */
+  steps: string[]
+  logs: Array<{ message: string; data?: Record<string, unknown> }>
+}
+
+export function createTestContext(options: TestContextOptions = {}): TestContext {
+  const calls: TestCall[] = []
+  const steps: string[] = []
+  const logs: TestContext['logs'] = []
+  const seenNames = new Set<string>()
+  /**
+   * Which step the running code is inside.
+   *
+   * `AsyncLocalStorage`, matching the real context exactly, and NOT a stack.
+   * A stack gets the concurrent case wrong in the direction that matters:
+   * `Promise.all([ctx.step.run('a', …), ctx.action.submit(…)])` is legal, and
+   * with a shared mutable stack the bare submit sees `a` open and is allowed —
+   * so the test double passes what production refuses, which is the one failure
+   * mode a test double must not have.
+   *
+   * Enforced here for the same reason grants and duplicate names are: a rule
+   * the unit test does not apply is a rule the author meets for the first time
+   * in a deployed run.
+   */
+  const stepScope = new AsyncLocalStorage<{ stepName: string; submitted: Set<string> }>()
+
+  const requireGrant = (grant: string): void => {
+    // No grant list means the test is not about grants. Enforcing an empty list
+    // would fail every existing test for a reason its author never chose.
+    if (!options.grants) return
+    if (!options.grants.includes(grant as Grant)) throw new Error(missingGrantMessage(grant))
+  }
+
+  const ctx: AutomationContext = {
+    runId: options.runId ?? 'test-run',
+    workspaceId: options.workspaceId ?? 'test-workspace',
+    input: options.input ?? {},
+
+    step: {
+      async run<T>(name: string, fn: () => Promise<T>): Promise<T> {
+        if (seenNames.has(name)) throw new Error(duplicateStepMessage(name))
+        seenNames.add(name)
+        steps.push(name)
+        return await stepScope.run({ stepName: name, submitted: new Set<string>() }, async () => {
+          try {
+            const out = await fn()
+            calls.push({ kind: 'step', label: name, status: 'ok' })
+            return out
+          } catch (err) {
+            calls.push({ kind: 'step', label: name, status: 'error' })
+            throw err
+          }
+        })
+      },
+
+      async sleep(name: string): Promise<void> {
+        if (seenNames.has(name)) throw new Error(duplicateStepMessage(name))
+        seenNames.add(name)
+        steps.push(name)
+        // Recorded, never waited: a test suite that really slept out its
+        // backoffs would take minutes to say nothing.
+        calls.push({ kind: 'step', label: name, status: 'ok' })
+      },
+    },
+
+    async log(message, data) {
+      logs.push({ message, ...(data ? { data } : {}) })
+      calls.push({ kind: 'log', label: message })
+    },
+
+    async file(ref: { fileId: string }) {
+      calls.push({ kind: 'file', label: ref.fileId })
+      const stub = options.files?.[ref.fileId]
+      // Throwing beats a fabricated handle: a test that reads a file it never
+      // stubbed would otherwise pass on made-up bytes.
+      if (!stub) {
+        throw new Error(
+          `No file stub for "${ref.fileId}". Pass files: { '${ref.fileId}': { signedUrl: '…', ` +
+            "mimeType: '…', sizeBytes: 0, name: null } } to createTestContext.",
+        )
+      }
+      return { fileId: ref.fileId, ...stub }
+    },
+
+    agent(slug: string) {
+      return {
+        async run(prompt: string) {
+          requireGrant(`agent:${slug}:run`)
+          calls.push({ kind: 'agent', label: slug })
+          const stub = options.agents?.[slug]
+          // Throwing beats answering with an empty string: a test whose agent
+          // silently returns '' passes while asserting nothing about the step
+          // that matters most.
+          if (!stub) {
+            throw new Error(
+              `No agent stub for "${slug}". Pass agents: { '${slug}': () => ({ text: '…' }) } ` +
+                'to createTestContext.',
+            )
+          }
+          return await stub(prompt)
+        },
+      }
+    },
+
+    plugin(install: string) {
+      return {
+        async call<T = unknown>(capability: string, input?: Record<string, unknown>) {
+          requireGrant(`plugin:${install}:${capability}`)
+          const stub = options.plugins?.[install]?.[capability]
+          // Before the record, matching the contract on `TestCall` and the
+          // `action` arm. (`agent` and `http` record first — a pre-existing
+          // divergence.)
+          if (!stub) {
+            throw new Error(
+              `No plugin stub for "${install}".${capability}. Pass ` +
+                // Quoted, unlike a bare identifier: an install name defaults to
+                // the catalog kind (kebab, e.g. "github-prod") and a capability
+                // can be dotted ("run.query") — neither survives as an object
+                // key without quotes, so the unquoted form the author would
+                // paste back in does not parse.
+                `plugins: { '${install}': { '${capability}': () => ({ data: … }) } } to createTestContext.`,
+            )
+          }
+          calls.push({ kind: 'plugin', label: `${install}:${capability}` })
+          return (await stub(input ?? {})) as PluginCallResult<T>
+        },
+      }
+    },
+
+    http: {
+      async fetch(req: HttpRequest) {
+        let host: string
+        try {
+          host = new URL(req.url).hostname.toLowerCase()
+        } catch {
+          throw new Error(`ctx.http: invalid URL ${req.url}`)
+        }
+        requireGrant(`http:${host}`)
+        calls.push({ kind: 'http', label: req.url })
+        // Same reasoning as the agent: a fabricated 200 is a false pass.
+        if (!options.http) {
+          throw new Error(
+            `No http stub. Pass http: (req) => ({ status: 200, headers: {}, body: '' }) ` +
+              'to createTestContext.',
+          )
+        }
+        return await options.http(req)
+      },
+    },
+
+    action: {
+      async submit(request: ActionSubmission): Promise<ActionSubmitResult> {
+        const scope = stepScope.getStore()
+        if (!scope) throw new Error(submitOutsideStepMessage(request.action))
+        // The batch loop is the shape this catches, and a one-row fixture never
+        // reaches it — so the double has to enforce it or an author meets it
+        // for the first time on their second production row, after the first
+        // has already been applied.
+        if (request.submissionKey !== undefined && request.submissionKey.length === 0) {
+          throw new Error(emptySubmissionKeyMessage(request.action))
+        }
+        requireGrant(`governed:${request.action}`)
+        const stub = options.actions?.[request.action]
+        // Both refusals that mean "this never happened" come BEFORE the
+        // reservation, matching the runtime's grant check: reserving first left
+        // an author who fixed the missing stub and re-ran a loop facing a
+        // duplicate accusation for a call that never answered.
+        if (!stub) {
+          throw new Error(
+            `No action stub for "${request.action}". Pass actions: { '${request.action}': ` +
+              "() => ({ requestId: 'req-1', lifecycle: 'ready' }) } to createTestContext.",
+          )
+        }
+        const submissionIdentity = `${request.action}\u0000${request.submissionKey ?? ''}`
+        // Reserved synchronously and released on failure, matching the runtime
+        // exactly. A double that checked and recorded across an await would let
+        // `Promise.all([submit(x), submit(x)])` through — and a double that
+        // permits what production refuses is the one failure mode a double must
+        // not have.
+        if (scope.submitted.has(submissionIdentity)) {
+          throw new Error(duplicateSubmissionMessage(request.action))
+        }
+        scope.submitted.add(submissionIdentity)
+        calls.push({ kind: 'action', label: request.action })
+        try {
+          return await stub(request)
+        } catch (err) {
+          // A throwing stub stands in for a submission that never landed.
+          scope.submitted.delete(submissionIdentity)
+          throw err
+        }
+      },
+    },
+
+    blueprint: {
+      async query<T = Record<string, unknown>>(
+        objectType: string,
+        _options?: BlueprintQueryOptions,
+      ): Promise<BlueprintQueryResult<T>> {
+        requireGrant('blueprint:read')
+        calls.push({ kind: 'blueprint', label: objectType })
+        const stub = options.blueprint?.[objectType]
+        // Empty is a real answer, and the branch an author most often forgets
+        // to test — so this one defaults rather than throwing.
+        return (stub ?? { rows: [], hasMore: false }) as BlueprintQueryResult<T>
+      },
+    },
+  }
+
+  return { ctx, calls, steps, logs }
+}