@junoflow/testkit 0.10.0 → 0.11.0

package/README.md

@@ -47,24 +47,25 @@ plain form works.
 
 `harness({ manifest, integration })` returns:
 
-| Member                                 | Does                                                                     |
-| -------------------------------------- | ------------------------------------------------------------------------ |
-| `h.config(values)`                     | set non-credential slots (manifest defaults are already applied)         |
-| `h.credentials(values)`                | set credential slots                                                     |
-| `h.action(name, params)`               | run an action, returns its result                                        |
-| `h.webhook(name, request?)`            | run a webhook; `request` defaults to `POST /` with an empty body         |
-| `h.schedule(name, event?)`             | run a schedule handler                                                   |
-| `h.hook(name)`                         | run a declared lifecycle hook (e.g. `activated`)                         |
-| `h.listen({ until, events, timeout })` | run the listener until the condition holds, then abort                   |
-| `h.store`                              | the KV, as a plain `Map` (`get`/`set`/`delete` all land here)            |
-| `h.findings()`                         | what `ctx.findings` asserted, as `{slug, key, severity, text, standing}` |
-| `h.states()`                           | values `ctx.states.publish` has sent, keyed by local name                |
-| `h.status()`                           | the last `ctx.status.set` report, or `null` if it never reported         |
-| `h.emitted()`                          | `[{ event, payload }]`, in order                                         |
-| `h.logs()`                             | `[{ level, message, data }]`                                             |
-| `h.conformance()`                      | manifest-vs-module problems; `[]` when they agree                        |
-| `h.http`                               | the request mock, below                                                  |
-| `h.reset()`                            | clear recorded state, keeping config and credentials                     |
+| Member                                 | Does                                                                                                                   |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `h.config(values)`                     | set non-credential slots (manifest defaults are already applied)                                                       |
+| `h.credentials(values)`                | set credential slots                                                                                                   |
+| `h.webhookUrls(values)`                | set `ctx.webhooks.<slot>.url`; each slot starts at `https://juno.test/webhooks/test-<slot>`, `null` is "no public URL" |
+| `h.action(name, params)`               | run an action, returns its result                                                                                      |
+| `h.webhook(name, request?)`            | run a webhook; `request` defaults to a `POST` with an empty body, to the slot's URL                                    |
+| `h.schedule(name, event?)`             | run a schedule handler                                                                                                 |
+| `h.hook(name)`                         | run a declared lifecycle hook (e.g. `activated`)                                                                       |
+| `h.listen({ until, events, timeout })` | run the listener until the condition holds, then abort                                                                 |
+| `h.store`                              | the KV, as a plain `Map` (`get`/`set`/`delete` all land here)                                                          |
+| `h.findings()`                         | what `ctx.findings` asserted, as `{slug, key, severity, text, standing}`                                               |
+| `h.states()`                           | values `ctx.states.publish` has sent, keyed by local name                                                              |
+| `h.status()`                           | the last `ctx.status.set` report, or `null` if it never reported                                                       |
+| `h.emitted()`                          | `[{ event, payload }]`, in order                                                                                       |
+| `h.logs()`                             | `[{ level, message, data }]`                                                                                           |
+| `h.conformance()`                      | manifest-vs-module problems; `[]` when they agree                                                                      |
+| `h.http`                               | the request mock, below                                                                                                |
+| `h.reset()`                            | clear recorded state, keeping config and credentials                                                                   |
 
 ### `h.http`
 
@@ -234,22 +235,23 @@ it('greets when someone is home', async () => {
 
 `flowHarness({ manifest, flow, now?, timezone?, solar? })` returns:
 
-| Member                                         | Does                                                                                        |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `h.trigger(name, { event })`                   | run a declared trigger; resolves to the handler's return value                              |
-| `h.scenario(s)`                                | set the world from one JSON object (below)                                                  |
-| `h.now(iso)` / `h.timezone(tz)` / `h.solar(v)` | what `ctx.now()` and `ctx.solar()` answer; the timezone is `UTC` unless set                 |
-| `h.states(values)` / `h.state(name)`           | seed a `read` or `read_write` binding; read its current value                               |
-| `h.stateCalls()`                               | `set`, `claim`, `release`, `signal`, `retract`, as `{binding, verb, value?, opts?}`         |
-| `h.targets.answer(key, a)` / `.calls()`        | answer `binding.method` with a value or a function of the params; the calls made            |
-| `h.controls.answer(key, a)` / `.calls()`       | answer `binding.verb`; the commands made                                                    |
-| `h.llm(id, answer)`                            | answer `step.llm(id, …)`; `id#N` answers only that occurrence                               |
-| `h.steps()`                                    | every `step.run` and `step.llm`, as `{id, output}`; repeats are `id`, `id#1`, `id#2`        |
-| `h.findings()`                                 | `{slug, key, severity, text, standing}`, collapsed by `(slug, key)` as the host does        |
-| `h.credentials(values)`                        | set `ctx.credentials` by declared id                                                        |
-| `h.logs()`                                     | `[{ level, message, data }]`                                                                |
-| `h.conformance()`                              | triggers declared vs implemented, both ways; `[]` when they agree                           |
-| `h.reset()`                                    | clear recordings, answers, seeds and scoped state; keep clock, timezone, solar, credentials |
+| Member                                         | Does                                                                                                             |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `h.trigger(name, { event })`                   | run a declared trigger; resolves to the handler's return value                                                   |
+| `h.scenario(s)`                                | set the world from one JSON object (below)                                                                       |
+| `h.now(iso)` / `h.timezone(tz)` / `h.solar(v)` | what `ctx.now()` and `ctx.solar()` answer; the timezone is `UTC` unless set                                      |
+| `h.states(values)` / `h.state(name)`           | seed a `read` or `read_write` binding; read its current value                                                    |
+| `h.stateCalls()`                               | `set`, `claim`, `release`, `signal`, `retract`, as `{binding, verb, value?, opts?}`                              |
+| `h.targets.answer(key, a)` / `.calls()`        | answer `binding.method` with a value or a function of the params; the calls made                                 |
+| `h.controls.answer(key, a)` / `.calls()`       | answer `binding.verb`; the commands made                                                                         |
+| `h.llm(id, answer)`                            | answer `step.llm(id, …)`; `id#N` answers only that occurrence                                                    |
+| `h.steps()`                                    | every `step.run` and `step.llm`, as `{id, output}`; repeats are `id`, `id#1`, `id#2`                             |
+| `h.findings()`                                 | `{slug, key, severity, text, standing}`, collapsed by `(slug, key)` as the host does                             |
+| `h.credentials(values)`                        | set `ctx.credentials` by declared id                                                                             |
+| `h.webhookUrls(values)`                        | set `ctx.webhooks['<id>'].url`; each starts at `https://juno.test/webhooks/test-<id>`, `null` is "no public URL" |
+| `h.logs()`                                     | `[{ level, message, data }]`                                                                                     |
+| `h.conformance()`                              | triggers declared vs implemented, both ways; `[]` when they agree                                                |
+| `h.reset()`                                    | clear recordings, answers, seeds and scoped state; keep clock, timezone, solar, credentials, webhook URLs        |
 
 `h.trigger(name, { event })` sets `event.trigger` and spreads the payload you
 give onto the event, as the sandbox does. An array (a `batch` run) stays under

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoflow/testkit",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Test harnesses for Juno integrations, flows and apps",
   "license": "MIT",
   "repository": {

package/src/flow.js

@@ -8,6 +8,7 @@ import {
 import { flowConformance } from './flow-conformance.js';
 import { names } from './names.js';
 import { applyScenario } from './scenario.js';
+import { createWebhookEndpoints } from './webhooks.js';
 
 /**
  * flowHarness({ manifest, flow }) builds the ctx the flow shim builds, in
@@ -46,6 +47,17 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
   };
   // Chainable setters on the binding half return the harness itself.
   const bindings = createBindings(manifest, () => h);
+  // ctx.webhooks is keyed by the webhook ids the triggers name, each once.
+  const webhooks = createWebhookEndpoints(
+    [
+      ...new Set(
+        Object.values(triggers)
+          .filter((t) => t?.type === 'webhook' && t.webhook?.id)
+          .map((t) => t.webhook.id)
+      ),
+    ],
+    'a webhook id a trigger in manifest.json names'
+  );
 
   const h = {
     /**
@@ -142,9 +154,20 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
 
     ...bindings.h,
 
+    /**
+     * Sets ctx.webhooks['<id>'].url. Every webhook a trigger names starts at a
+     * stand-in URL; null is what the host sends with no public URL. Kept
+     * across reset().
+     */
+    webhookUrls(values = {}) {
+      webhooks.set(values);
+      return h;
+    },
+
     /**
      * Clears recordings, answers, seeded states, the scenario's event and
-     * scoped memory; keeps the clock, timezone, solar and credentials.
+     * scoped memory; keeps the clock, timezone, solar, credentials and
+     * webhook URLs.
      */
     reset() {
       rec.steps.length = 0;
@@ -193,6 +216,7 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
     return {
       event: flattenTriggerEvent({ trigger, payload }),
       ...bindings.ctx(refuse),
+      webhooks: webhooks.ctx(),
 
       step: {
         async run(id, fn) {

package/src/index.d.ts

@@ -93,6 +93,10 @@ export interface WebhookRequestInit {
   query?: Record<string, string>;
   /** A string is sent as-is; anything else is JSON.stringify'd. */
   body?: unknown;
+  /**
+   * Defaults to what the host builds: the slot's ctx.webhooks URL, then
+   * subpath and query — or "/" when the slot's URL is null.
+   */
   url?: string;
   subpath?: string;
 }
@@ -185,6 +189,12 @@ export interface ListenOptions {
 export interface Harness {
   config(values: Record<string, unknown>): Harness;
   credentials(values: Record<string, string>): Harness;
+  /**
+   * Sets ctx.webhooks.<slot>.url by declared slot. Every slot starts at a
+   * stand-in URL (https://juno.test/webhooks/test-<slot>); null is what the
+   * host sends with no public URL or no webhook bound. Kept across reset().
+   */
+  webhookUrls(values: Record<string, string | null>): Harness;
   action(name: string, params?: unknown): Promise<unknown>;
   webhook(
     name: string,
@@ -486,9 +496,16 @@ export interface FlowHarness {
   findings(): RecordedFinding[];
   /** Sets ctx.credentials by declared id. Kept across reset(). */
   credentials(values: Record<string, string>): FlowHarness;
+  /**
+   * Sets ctx.webhooks['<id>'].url for a webhook id a trigger names. Each starts
+   * at a stand-in URL (https://juno.test/webhooks/test-<id>); null is what the
+   * host sends with no public URL. Kept across reset().
+   */
+  webhookUrls(values: Record<string, string | null>): FlowHarness;
   /**
    * Clears recordings, answers, seeded states, the scenario's event and
-   * scoped memory; keeps the clock, timezone, solar and credentials.
+   * scoped memory; keeps the clock, timezone, solar, credentials and webhook
+   * URLs.
    */
   reset(): FlowHarness;
 }

package/src/index.js

@@ -4,6 +4,7 @@ import { names } from './names.js';
 import { conformance } from './conformance.js';
 import { createHttpMock, withFetch } from './http.js';
 import { assertValid } from './schema.js';
+import { createWebhookEndpoints } from './webhooks.js';
 
 /** How long h.listen waits before aborting, when nothing else says. */
 const DEFAULT_LISTEN_TIMEOUT_MS = 1000;
@@ -51,7 +52,11 @@ export function harness({ manifest, integration } = {}) {
   };
 
   const http = createHttpMock();
-  const ctx = buildContext(manifest, state);
+  const webhooks = createWebhookEndpoints(
+    Object.keys(manifest.webhooks ?? {}),
+    'a webhook slot in manifest.json'
+  );
+  const ctx = buildContext(manifest, state, webhooks);
 
   const h = {
     /** Merge values into ctx.config. Rejects a slot the manifest never declared. */
@@ -68,6 +73,16 @@ export function harness({ manifest, integration } = {}) {
       return h;
     },
 
+    /**
+     * Sets ctx.webhooks.<slot>.url. Every declared slot starts at a stand-in
+     * URL; null is what the host sends with no public URL or no webhook bound.
+     * Kept across reset().
+     */
+    webhookUrls(values = {}) {
+      webhooks.set(values);
+      return h;
+    },
+
     async action(name, params) {
       const declared = manifest.actions?.[name];
       if (!declared) {
@@ -94,7 +109,7 @@ export function harness({ manifest, integration } = {}) {
       }
       const handler = requireHandler(integration, 'webhooks', name, 'webhook');
       assertRequiredSlots(manifest, state);
-      const req = buildWebhookRequest(request);
+      const req = buildWebhookRequest(request, webhooks.url(name));
 
       const result = await withFetch(http.fetch, () =>
         handler(req, emitting(ctx, manifest, state))
@@ -249,7 +264,7 @@ export function harness({ manifest, integration } = {}) {
  * cannot tell the difference, which is the only way a test here means anything
  * about how the code runs there.
  */
-function buildContext(manifest, state) {
+function buildContext(manifest, state, webhooks) {
   const log = (message, data) =>
     state.logs.push({ level: 'debug', message, data });
   log.info = (message, data) =>
@@ -262,6 +277,11 @@ function buildContext(manifest, state) {
   return {
     config: state.config,
     credentials: state.credentials,
+    // A getter, so a URL set after the harness was built is what the next
+    // invocation reads — the host resolves it per invocation too.
+    get webhooks() {
+      return webhooks.ctx();
+    },
     log,
     // Present on every surface, as in production. A non-listener test never
     // aborts it, which is also true of an invocation that finishes in time;
@@ -468,7 +488,10 @@ function requireHandler(integration, surface, name, kind) {
   return handler;
 }
 
-function buildWebhookRequest(request) {
+// url defaults to what the host would build: the slot's URL, then the subpath
+// and the query string — so a signature over the URL verifies in a test as it
+// does in production. With no URL for the slot it stays '/'.
+function buildWebhookRequest(request, slotURL) {
   const body =
     typeof request.body === 'string'
       ? request.body
@@ -480,12 +503,18 @@ function buildWebhookRequest(request) {
     query: request.query ?? {},
     body,
     json: parseJSONOrNull(body),
-    url: request.url ?? '/',
+    url: request.url ?? requestURL(slotURL, request),
     subpath: request.subpath ?? '',
     form: parseFormOrNull(headers, body),
   };
 }
 
+function requestURL(slotURL, request) {
+  if (slotURL === null) return '/';
+  const query = new URLSearchParams(request.query ?? {}).toString();
+  return slotURL + (request.subpath ?? '') + (query ? `?${query}` : '');
+}
+
 // The host's rule: lower-cased content-type, media type
 // application/x-www-form-urlencoded (a charset parameter is ignored), first
 // value per key — else null.

package/src/webhooks.js

@@ -0,0 +1,41 @@
+import { fail } from './assert.js';
+
+/**
+ * The URL a webhook has until a test sets one: shaped like Juno's
+ * (`<public URL>/webhooks/<token>`), so a handler's happy path — the one where
+ * the site has a public URL and the webhook is bound — is what runs by default.
+ */
+export function defaultWebhookURL(key) {
+  return `https://juno.test/webhooks/test-${key}`;
+}
+
+/**
+ * ctx.webhooks and the h.webhookUrls() that sets it. keys are what the host
+ * would send: an integration's declared slots, or the webhook ids a flow's
+ * triggers name. Like credentials, the URLs are a fixture: kept across reset().
+ */
+export function createWebhookEndpoints(keys, describe) {
+  const urls = new Map(keys.map((k) => [k, defaultWebhookURL(k)]));
+  return {
+    /** Sets URLs by key; null is the host's answer with no public URL or no binding. */
+    set(values = {}) {
+      for (const [key, url] of Object.entries(values)) {
+        if (!urls.has(key)) {
+          fail(
+            `h.webhookUrls — "${key}" is not ${describe} (have: ${[...urls.keys()].join(', ') || '(none)'})`
+          );
+        }
+        if (url !== null && typeof url !== 'string') {
+          fail(
+            `h.webhookUrls — "${key}" must be a URL string or null, got ${JSON.stringify(url)}`
+          );
+        }
+        urls.set(key, url);
+      }
+    },
+    url: (key) => urls.get(key) ?? null,
+    /** A fresh object per invocation, as init sends one per run. */
+    ctx: () =>
+      Object.fromEntries([...urls].map(([key, url]) => [key, { url }])),
+  };
+}