@junoflow/testkit 0.11.0 → 0.12.0

package/src/bindings.js

@@ -16,12 +16,16 @@ const STATE_VERBS = {
   signal: ['signal', 'retract'],
 };
 const ALL_STATE_VERBS = Object.values(STATE_VERBS).flat();
+/** A flow's state handle constructors, on every binding (the host refuses one with no value). */
+const STATE_WAIT_VERBS = ['when', 'becomes', 'changes'];
 
 /** Every control handle carries all four; the host refuses one the type does not take. */
 const CONTROL_VERBS = ['press', 'activate', 'extend', 'release'];
 
 /** Integrations the broker serves itself; none of their actions is read-only. */
 const BUILT_IN_INTEGRATIONS = ['homeassistant', 'mqtt'];
+/** Target kinds that are not an integration install, and so emit no events. */
+const BUILT_IN_TARGETS = ['homeassistant', 'mqtt', 'flow'];
 
 /**
  * The binding half of flowHarness and appHarness: the state handles, ctx.targets,
@@ -153,12 +157,16 @@ export function createBindings(
   /**
    * The ctx members for one run; refuse is the run's recording fail().
    *
+   * handles is the run's handle table (handles.js), which gives every state
+   * binding when/becomes/changes and every target untilEvent; an app passes
+   * none, since an app cannot wait.
+   *
    * policy is what the host refuses on this run. `{ readOnly: true, handler }`
    * is an app handler declared read_only, and refuses what the host refuses
    * it, in the host's words: claim, release, a control command, and a call on
    * a built-in target. Everything else is the caller's to refuse.
    */
-  function ctx(refuse, policy = {}) {
+  function ctx(refuse, policy = {}, handles = undefined) {
     const readOnly = policy.readOnly
       ? (what) =>
           refuse(
@@ -166,19 +174,19 @@ export function createBindings(
           )
       : () => {};
     return {
-      [statesRoot]: stateProxy(refuse, readOnly),
+      [statesRoot]: stateProxy(refuse, readOnly, handles),
       targets: namedProxy(
         targets,
         (name) =>
           `ctx.targets.${name} — "${name}" is not declared in manifest.json (have: ${names(targets)})`,
-        (name, target) => targetHandle(refuse, name, target, policy),
+        (name, target) => targetHandle(refuse, name, target, policy, handles),
         refuse
       ),
       controls: namedProxy(
         controls,
         (name) =>
           `ctx.controls.${name} — "${name}" is not declared in manifest.json (have: ${names(controls)})`,
-        (name) => controlHandle(refuse, name, readOnly),
+        (name) => controlHandle(refuse, name, readOnly, handles),
         refuse
       ),
       findings: {
@@ -223,7 +231,7 @@ export function createBindings(
     return kind;
   }
 
-  function stateProxy(refuse, readOnly) {
+  function stateProxy(refuse, readOnly, handles) {
     const own = {};
     if (scoped) {
       own.scoped = async (name, initial) => {
@@ -247,7 +255,7 @@ export function createBindings(
             `ctx.${statesRoot}.${prop} — "${prop}" is not declared in manifest.json (have: ${names(states)})`
           );
         }
-        return stateHandle(refuse, readOnly, prop, binding);
+        return stateHandle(refuse, readOnly, prop, binding, handles);
       },
     });
   }
@@ -257,7 +265,7 @@ export function createBindings(
    * not granted is refused here, as the host refuses it, rather than left for
    * the generated types to have caught.
    */
-  function stateHandle(refuse, readOnly, name, binding) {
+  function stateHandle(refuse, readOnly, name, binding, handles) {
     const where = `ctx.${statesRoot}.${name}`;
     const kind = bindingKind(binding);
     const granted = STATE_VERBS[kind];
@@ -329,20 +337,60 @@ export function createBindings(
         return { retracted };
       },
     };
+    if (handles) {
+      Object.assign(handle, waitConstructors(refuse, name, binding, handles));
+    }
     return verbProxy(
       handle,
-      ALL_STATE_VERBS,
+      handles ? [...ALL_STATE_VERBS, ...STATE_WAIT_VERBS] : ALL_STATE_VERBS,
       (prop) =>
         `${where}.${prop} — not a state verb; "${name}" grants ${granted.join(', ')}`,
       refuse
     );
   }
 
+  /**
+   * when/becomes/changes on one binding. A binding that grants no value
+   * access is the host's refusal, in its words, reported as the host's are:
+   * at the next wait or when the handler returns.
+   */
+  function waitConstructors(refuse, name, binding, handles) {
+    const kind = bindingKind(binding);
+    const error = (mode) =>
+      kind === 'slot' || kind === 'signal'
+        ? `${mode}: state binding "${name}" grants no value access; it is a ${kind === 'slot' ? 'claim-slot' : 'signal'} binding on "${binding.control ?? binding.state}"`
+        : undefined;
+    const current = (mode) => () => {
+      if (!rec.values.has(name)) {
+        refuse(
+          `ctx.${statesRoot}.${name}.${mode}() — the test gave "${name}" no value; seed it with h.states({ ${name}: … })`
+        );
+      }
+      return jsonCopy(rec.values.get(name));
+    };
+    const open =
+      (mode) =>
+      (...args) =>
+        handles.stateHandle(mode, `${statesRoot}.${name}.${mode}`, args, {
+          current: current(mode),
+          error: error(mode),
+        });
+    return {
+      when: open('when'),
+      becomes: open('becomes'),
+      changes: open('changes'),
+    };
+  }
+
   // ─── targets ───────────────────────────────────────────────────────────────
 
-  function targetHandle(refuse, name, target, policy) {
+  function targetHandle(refuse, name, target, policy, handles) {
     const handle = {};
+    if (handles && (target?.flow?.flow_id || target?.flow?.label)) {
+      Object.assign(handle, flowTargetMethods(refuse, name, target, handles));
+    }
     for (const method of targetMethods(target)) {
+      if (handle[method]) continue;
       handle[method] = async (params, opts) => {
         // The broker's refusal. An integration action's read_only is the
         // integration manifest's to say, which the harness does not have, so
@@ -375,18 +423,160 @@ export function createBindings(
         );
       };
     }
+    const methods = Object.keys(handle);
+    if (handles) {
+      // Every target answers untilEvent here, so a non-integration one gets
+      // the host's refusal rather than a TypeError.
+      handle.untilEvent = (...args) => {
+        if (BUILT_IN_TARGETS.includes(target?.integration)) {
+          refuse(
+            `untilEvent: target "${name}" is a ${target.integration} target; only an integration target emits events`
+          );
+        }
+        return handles.eventHandle(`targets.${name}.untilEvent`, args);
+      };
+    }
     return verbProxy(
       handle,
       Object.keys(handle),
       (prop) =>
-        `ctx.targets.${name}.${prop} — target "${name}" has no method "${prop}" (have: ${Object.keys(handle).join(', ') || '(none)'})`,
+        `ctx.targets.${name}.${prop} — target "${name}" has no method "${prop}" (have: ${methods.join(', ') || '(none)'})`,
       refuse
     );
   }
 
+  /**
+   * A flow target's start/invoke, or a label target's startAll/invokeAll, as
+   * buildTargets in sdk/src/context.ts builds them over run handles: invoke
+   * opens the child and a timer and cancels both, invokeAll opens one handle.
+   * The harness starts no child: a run handle fires at open with the
+   * `.start` answer wrapped as an InvokeResult, or the `.startAll` answer
+   * whole. invoke and invokeAll answer from their own key when the test set
+   * one, else from that one, as today's invoke did.
+   */
+  function flowTargetMethods(refuse, name, target, handles) {
+    const flowID = target.flow.flow_id;
+    const record = (method, input, opts) => {
+      const sent = jsonCopy(
+        input ?? null,
+        `ctx.targets.${name}.${method}()`,
+        refuse
+      );
+      const call = { target: name, action: method, params: sent };
+      if (opts !== undefined) call.opts = { ...opts };
+      rec.targetCalls.push(call);
+      return sent;
+    };
+    const unanswered = (key) =>
+      `target call ${key} was not answered — h.targets.answer('${key}', result)`;
+    // The answer for key: its value, or its $error thrown.
+    const answer = (key, sent) =>
+      answerFor(refuse, rec.targetAnswers, key, unanswered(key), sent);
+
+    if (flowID) {
+      const startKey = `${name}.start`;
+      const openChild = (method, input, opts, value) =>
+        handles.runHandle(`targets.${name}.${method}`, [input, opts], {
+          label: opts?.label,
+          value,
+        });
+      return {
+        start(input, opts) {
+          const sent = record('start', input, opts);
+          if (!rec.targetAnswers.has(startKey)) refuse(unanswered(startKey));
+          return openChild('start', input, opts, startValue(startKey, sent));
+        },
+        async invoke(input, opts) {
+          const sent = record('invoke', input, opts);
+          const own = `${name}.invoke`;
+          const key = rec.targetAnswers.has(own) ? own : startKey;
+          if (!rec.targetAnswers.has(key)) refuse(unanswered(own));
+          let value;
+          let thrown;
+          try {
+            value = await answer(key, sent);
+          } catch (err) {
+            thrown = err;
+          }
+          const child = openChild(
+            'invoke',
+            input,
+            undefined,
+            thrown === undefined
+              ? { flow_id: flowID, run_id: 'harness', ok: true, value }
+              : {
+                  flow_id: flowID,
+                  run_id: 'harness',
+                  ok: false,
+                  error: thrown?.message,
+                }
+          );
+          const timer = handles.after(opts?.timeout ?? '5m');
+          child.cancel();
+          timer.cancel();
+          handles.settle();
+          // The answer's $error is what invoke throws, verbatim.
+          if (thrown !== undefined) throw thrown;
+          return value;
+        },
+      };
+    }
+
+    const allKey = `${name}.startAll`;
+    const openAll = (method, input, opts, fields) =>
+      handles.runHandle(`targets.${name}.${method}`, [input, opts], {
+        label: opts?.label,
+        ...fields,
+      });
+    return {
+      startAll(input, opts) {
+        const sent = record('startAll', input, opts);
+        if (!rec.targetAnswers.has(allKey)) refuse(unanswered(allKey));
+        return openAll('startAll', input, opts, startAllFields(allKey, sent));
+      },
+      async invokeAll(input, opts) {
+        const sent = record('invokeAll', input, opts);
+        const own = `${name}.invokeAll`;
+        const key = rec.targetAnswers.has(own) ? own : allKey;
+        if (!rec.targetAnswers.has(key)) refuse(unanswered(own));
+        const results = await answer(key, sent);
+        const all = openAll('invokeAll', input, undefined, { value: results });
+        all.cancel();
+        handles.settle();
+        return results;
+      },
+    };
+
+    // The value a start handle fires with, from an answer resolved now.
+    function startValue(key, sent) {
+      const r = rec.targetAnswers.resolveSync(key, sent, refuse);
+      if ('error' in r) {
+        return {
+          flow_id: flowID,
+          run_id: 'harness',
+          ok: false,
+          error: r.error,
+        };
+      }
+      return {
+        flow_id: flowID,
+        run_id: 'harness',
+        ok: true,
+        value: jsonCopy(r.value, `the answer for ${key}`, refuse),
+      };
+    }
+
+    // A startAll's answer is its value whole; its $error is the host's refusal.
+    function startAllFields(key, sent) {
+      const r = rec.targetAnswers.resolveSync(key, sent, refuse);
+      if ('error' in r) return { error: r.error };
+      return { value: jsonCopy(r.value, `the answer for ${key}`, refuse) };
+    }
+  }
+
   // ─── controls ──────────────────────────────────────────────────────────────
 
-  function controlHandle(refuse, name, readOnly) {
+  function controlHandle(refuse, name, readOnly, handles) {
     const command = async (verb, fields) => {
       readOnly('command controls');
       const call = { binding: name, verb };
@@ -422,11 +612,19 @@ export function createBindings(
       extend: () => command('extend', {}),
       release: () => command('release', {}),
     };
+    // A flow's binding can be waited on for its next press. The harness has
+    // no control catalog, so whether the binding is a button is the host's to
+    // refuse, as it is for the verbs above; a press never fires in a test.
+    const verbs = handles ? [...CONTROL_VERBS, 'untilPressed'] : CONTROL_VERBS;
+    if (handles) {
+      handle.untilPressed = (...args) =>
+        handles.pressHandle(`controls.${name}.untilPressed`, args);
+    }
     return verbProxy(
       handle,
-      CONTROL_VERBS,
+      verbs,
       (prop) =>
-        `ctx.controls.${name}.${prop} — not a control verb (have: ${CONTROL_VERBS.join(', ')})`,
+        `ctx.controls.${name}.${prop} — not a control verb (have: ${verbs.join(', ')})`,
       refuse
     );
   }
@@ -549,7 +747,14 @@ export function createWorld(harnessName, harness) {
     if (solar !== undefined) h.solar(solar);
   }
 
-  return { h, ctx, init };
+  /** The clock's instant in epoch milliseconds, or undefined with no clock. */
+  function instant() {
+    return world.now === undefined
+      ? undefined
+      : resolveInstant(world.now, world.timezone);
+  }
+
+  return { h, ctx, init, instant };
 }
 
 /**
@@ -559,8 +764,8 @@ export function createWorld(harnessName, harness) {
  * else (each action verbatim).
  */
 export function targetMethods(target) {
-  if (target?.flow?.flow_id) return ['invoke'];
-  if (target?.flow?.label) return ['invokeAll'];
+  if (target?.flow?.flow_id) return ['start', 'invoke'];
+  if (target?.flow?.label) return ['startAll', 'invokeAll'];
   if (target?.integration === 'mqtt') return ['publish'];
   if (target?.integration === 'homeassistant') {
     return ['getState', ...(target.actions ?? []).map(actionToMethodName)];
@@ -638,6 +843,21 @@ export function createAnswers() {
   // How many calls each key has answered since it was set; $replay reads it.
   const calls = new Map();
 
+  // The answer for the next call to key: its $replay item, or the answer.
+  function next(key, refuse) {
+    const answer = answers.get(key);
+    const n = (calls.get(key) ?? 0) + 1;
+    calls.set(key, n);
+    if (reservedForm(answer) !== '$replay') return answer;
+    const items = answer.$replay;
+    if (n > items.length) {
+      refuse(
+        `${key} answered ${items.length} call${items.length === 1 ? '' : 's'} in the scenario; this was call ${n}`
+      );
+    }
+    return items[n - 1];
+  }
+
   return {
     set(key, answer, where) {
       checkAnswerForm(answer, `${where}('${key}')`);
@@ -647,21 +867,27 @@ export function createAnswers() {
     has: (key) => answers.has(key),
     /** The answer for one call: its $replay item, $error thrown, a function called. */
     async resolve(key, args, refuse) {
-      let answer = answers.get(key);
-      const n = (calls.get(key) ?? 0) + 1;
-      calls.set(key, n);
-      if (reservedForm(answer) === '$replay') {
-        const items = answer.$replay;
-        if (n > items.length) {
-          refuse(
-            `${key} answered ${items.length} call${items.length === 1 ? '' : 's'} in the scenario; this was call ${n}`
-          );
-        }
-        answer = items[n - 1];
-      }
+      const answer = next(key, refuse);
       if (reservedForm(answer) === '$error') throw new Error(answer.$error);
       return typeof answer === 'function' ? await answer(args) : answer;
     },
+    /**
+     * The answer for one call made by a synchronous constructor (a run
+     * handle): `{ value }`, or `{ error }` for a $error. A function answer is
+     * called and must not return a promise.
+     */
+    resolveSync(key, args, refuse) {
+      const answer = next(key, refuse);
+      if (reservedForm(answer) === '$error') return { error: answer.$error };
+      if (typeof answer !== 'function') return { value: answer };
+      const value = answer(args);
+      if (typeof value?.then === 'function') {
+        refuse(
+          `the answer for ${key} returned a promise; ${key} opens its handle at once, so answer it with a value or a function returning one`
+        );
+      }
+      return { value };
+    },
     clear() {
       answers.clear();
       calls.clear();

package/src/conformance.js

@@ -7,7 +7,14 @@ import { schemaError } from './schema.js';
  * declared/implemented pairing loop below the way actions/webhooks/schedules/
  * hooks do.
  */
-const SURFACES = ['actions', 'webhooks', 'schedules', 'listener', 'hooks'];
+const SURFACES = [
+  'actions',
+  'webhooks',
+  'schedules',
+  'listener',
+  'hooks',
+  'channels',
+];
 
 /**
  * The lifecycle moments the host knows how to reach — mirrors
@@ -79,6 +86,24 @@ export function conformance(manifest, integration) {
     );
   }
 
+  // A channel is an object of handlers rather than one function: deliver is
+  // what Juno calls to reach a person and is required, withdraw is optional.
+  const implementedChannels = integration?.channels ?? {};
+  for (const name of Object.keys(manifest.channels ?? {})) {
+    if (typeof implementedChannels[name]?.deliver !== 'function') {
+      problems.push(
+        `channel "${name}" is declared in manifest.json but its deliver is not implemented`
+      );
+    }
+  }
+  for (const name of Object.keys(implementedChannels)) {
+    if (!manifest.channels?.[name]) {
+      problems.push(
+        `channel "${name}" is implemented but not declared in manifest.json — Juno will never call it`
+      );
+    }
+  }
+
   for (const name of Object.keys(manifest.hooks ?? {})) {
     if (!HOOK_NAMES.includes(name)) {
       problems.push(

package/src/flow.js

@@ -1,3 +1,4 @@
+import { createPeople } from './ask.js';
 import { fail } from './assert.js';
 import {
   createAnswers,
@@ -6,6 +7,7 @@ import {
   jsonCopy,
 } from './bindings.js';
 import { flowConformance } from './flow-conformance.js';
+import { createHandleTable } from './handles.js';
 import { names } from './names.js';
 import { applyScenario } from './scenario.js';
 import { createWebhookEndpoints } from './webhooks.js';
@@ -42,11 +44,15 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
     steps: [],
     logs: [],
     llm: createAnswers(),
+    // The last run's handle table, for h.handles().
+    handles: null,
     // The last scenario's event, for an h.trigger(name) that gives none.
     event: undefined,
   };
   // Chainable setters on the binding half return the harness itself.
   const bindings = createBindings(manifest, () => h);
+  // ctx.ask and ctx.notify, and h.questions / h.notifications / h.unreachable.
+  const people = createPeople(manifest, () => h);
   // ctx.webhooks is keyed by the webhook ids the triggers name, each once.
   const webhooks = createWebhookEndpoints(
     [
@@ -98,8 +104,14 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
         result = await handler(ctx);
       } catch (err) {
         // A refusal the handler caught and turned into something else is
-        // still the cause; report it rather than whatever it became.
+        // still the cause; report it rather than whatever it became. A
+        // refused handle open is one of these: the shim reports it when the
+        // handler returns, in place of the handler's own error.
         throw run.failures[0] ?? err;
+      } finally {
+        // The run is over either way, and the engine cancels what it left
+        // open.
+        rec.handles.close();
       }
       // A handler that swallowed a refusal (try/catch around a target call,
       // say) must not turn it into a green test.
@@ -123,7 +135,7 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
 
     /**
      * Applies a scenario through the setters: now, timezone, solar, states,
-     * controls, targets, credentials and llm, and keeps its event for an
+     * controls, targets, credentials, llm, questions and unreachable, and keeps its event for an
      * h.trigger(name) that gives none. Ignores trigger, expect and
      * flow_version; fails on any other key.
      */
@@ -147,12 +159,19 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
 
     /** Every step.run and step.llm, in order, as the journal records them. */
     steps: () => rec.steps.map((s) => ({ ...s })),
+    /**
+     * The last h.trigger's handles, in open order: `{ id, kind, label,
+     * status }`. A handle still open when the run ended reads `cancelled`, as
+     * the engine closes it.
+     */
+    handles: () => (rec.handles ? rec.handles.list() : []),
     /** Everything handlers logged, with its level. */
     logs: () => rec.logs.slice(),
     /** Manifest-vs-module problems; empty when they agree. */
     conformance: () => flowConformance(manifest, flow),
 
     ...bindings.h,
+    ...people.h,
 
     /**
      * Sets ctx.webhooks['<id>'].url. Every webhook a trigger names starts at a
@@ -165,14 +184,16 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
     },
 
     /**
-     * Clears recordings, answers, seeded states, the scenario's event and
-     * scoped memory; keeps the clock, timezone, solar, credentials and
-     * webhook URLs.
+     * Clears recordings, answers (questions and unreachable people included),
+     * seeded states, the scenario's event and scoped memory; keeps the clock,
+     * timezone, solar, credentials and webhook URLs.
      */
     reset() {
+      people.reset();
       rec.steps.length = 0;
       rec.logs.length = 0;
       rec.llm.clear();
+      rec.handles = null;
       rec.event = undefined;
       bindings.reset();
       return h;
@@ -206,6 +227,14 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
       return seen === 0 ? id : `${id}#${seen}`;
     };
 
+    const handles = createHandleTable({
+      refuse,
+      instant: world.instant,
+      render: renderArgs,
+      harnessName: 'flowHarness',
+    });
+    rec.handles = handles;
+
     const log = (message, data) =>
       rec.logs.push({ level: 'debug', message, data });
     log.warn = (message, data) =>
@@ -215,7 +244,7 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
 
     return {
       event: flattenTriggerEvent({ trigger, payload }),
-      ...bindings.ctx(refuse),
+      ...bindings.ctx(refuse, {}, handles),
       webhooks: webhooks.ctx(),
 
       step: {
@@ -264,16 +293,16 @@ export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
         }),
       },
 
-      async sleep(...args) {
-        refuse(
-          `a handler cannot suspend in a test: sleep(${renderArgs(args)})`
-        );
-      },
+      after: handles.after,
+      at: handles.at,
+      all: handles.all,
+      wait: handles.wait,
+      ...people.ctx(refuse, handles, world.instant),
 
-      async waitForEvent(...args) {
-        refuse(
-          `a handler cannot suspend in a test: waitForEvent(${renderArgs(args)})`
-        );
+      // sleep(d, label) is wait([after(d)], label) in the shim, so it refuses
+      // the way that wait does.
+      async sleep(duration, label) {
+        await handles.wait([handles.after(duration)], label);
       },
 
       log,