@junoflow/testkit 0.6.0 → 0.9.0

package/src/findings.js

@@ -0,0 +1,49 @@
+import { fail } from './assert.js';
+import { names } from './names.js';
+
+/**
+ * The one call behind open/clear/set, mirroring the SDK and the host: the verbs
+ * differ only in whether the boolean is already decided, and the answer is the
+ * transition this call made. Both false means it refreshed an instance that was
+ * already standing, or retracted one that was already absent.
+ *
+ * The name is checked against the manifest for the same reason emit's is: Juno
+ * rejects an undeclared finding at runtime, and finding that out from an
+ * installer is not a test.
+ */
+export function setFinding(manifest, state, slug, standing, opts) {
+  const declared = manifest.findings?.[slug];
+  if (!declared) {
+    fail(
+      `ctx.findings — "${slug}" is not declared in manifest.json (have: ${names(manifest.findings)}). ` +
+        'Juno rejects an undeclared finding at runtime.'
+    );
+  }
+  const key = opts.key ?? '';
+  const existing = state.findings.find((f) => f.slug === slug && f.key === key);
+
+  if (!standing) {
+    // A retraction says nothing about severity or text, and clearing what was
+    // never open is a no-op here exactly as it is in the store.
+    if (!existing || !existing.standing)
+      return { opened: false, cleared: false };
+    existing.standing = false;
+    return { opened: false, cleared: true };
+  }
+
+  const severity = opts.severity ?? declared.severity ?? 'error';
+  if (!['info', 'warn', 'error'].includes(severity)) {
+    fail(
+      `ctx.findings severity must be "info", "warn" or "error", got ${JSON.stringify(severity)}`
+    );
+  }
+  const text = opts.text ?? '';
+  if (existing) {
+    // Refresh in place — never a second instance for the same (slug, key).
+    const opened = !existing.standing;
+    Object.assign(existing, { severity, text, standing: true });
+    return { opened, cleared: false };
+  }
+  state.findings.push({ slug, key, severity, text, standing: true });
+  return { opened: true, cleared: false };
+}

package/src/flow-conformance.js

@@ -0,0 +1,43 @@
+/** The only key a flow's default export carries (BaseFlow in flow-api.d.ts). */
+const FLOW_KEYS = ['triggers'];
+
+/**
+ * Checks a flow's manifest and module against each other and returns a list of
+ * problems, empty when they agree — conformance.js's pairing, for triggers.
+ *
+ * A trigger declared and not implemented fails its first run in production
+ * ("no handler for trigger"); one implemented and not declared never runs at
+ * all. Neither is visible until the house does something.
+ */
+export function flowConformance(manifest, flow) {
+  const problems = [];
+
+  for (const key of Object.keys(flow ?? {})) {
+    if (!FLOW_KEYS.includes(key)) {
+      problems.push(
+        `default export has an unknown key "${key}" (expected ${FLOW_KEYS.join(', ')})`
+      );
+    }
+  }
+  if (typeof flow?.triggers !== 'object' || flow.triggers === null) {
+    problems.push('default export has no "triggers" object');
+  }
+
+  const declared = Object.keys(manifest?.triggers ?? {});
+  for (const name of declared) {
+    if (typeof flow?.triggers?.[name] !== 'function') {
+      problems.push(
+        `trigger "${name}" is declared in manifest.json but not implemented`
+      );
+    }
+  }
+  for (const name of Object.keys(flow?.triggers ?? {})) {
+    if (!declared.includes(name)) {
+      problems.push(
+        `trigger "${name}" is implemented but not declared in manifest.json — Juno will never call it`
+      );
+    }
+  }
+
+  return problems;
+}

package/src/flow.js

@@ -0,0 +1,290 @@
+import { fail } from './assert.js';
+import {
+  createAnswers,
+  createBindings,
+  createWorld,
+  jsonCopy,
+} from './bindings.js';
+import { flowConformance } from './flow-conformance.js';
+import { names } from './names.js';
+import { applyScenario } from './scenario.js';
+
+/**
+ * flowHarness({ manifest, flow }) builds the ctx the flow shim builds, in
+ * process, and runs one trigger handler against it.
+ *
+ * Strict where the shim is permissive, on purpose. Production refuses an
+ * undeclared name and asks the world for everything else, and neither is
+ * something a test should find out from the house. So a name the manifest does
+ * not declare fails here, and so does any read of the world — the clock, the
+ * sun, a step.llm — that the test did not answer.
+ */
+export function flowHarness({ manifest, flow, now, timezone, solar } = {}) {
+  if (!manifest || typeof manifest !== 'object') {
+    fail(
+      "flowHarness({ manifest, flow }): manifest is required — import manifest from '../manifest.json'"
+    );
+  }
+  if (!flow || typeof flow !== 'object') {
+    fail(
+      "flowHarness({ manifest, flow }): flow is required — import flow from '../src/flow'"
+    );
+  }
+  const triggers = manifest.triggers ?? {};
+
+  // What the test said about the world: h.now, h.timezone, h.solar.
+  const world = createWorld('flowHarness', () => h);
+
+  // What handlers did, and the answers the test gave for this test. Cleared
+  // by reset().
+  const rec = {
+    steps: [],
+    logs: [],
+    llm: createAnswers(),
+    // 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);
+
+  const h = {
+    /**
+     * Runs the handler for a declared trigger and resolves to what it returned.
+     * `event` is the payload, flattened onto ctx.event as the shim flattens it;
+     * without one, the scenario's `event` is, the same way.
+     */
+    async trigger(name, options = {}) {
+      const def = triggers[name];
+      if (!def) {
+        fail(
+          `trigger "${name}" is not declared in manifest.json (have: ${names(triggers)})`
+        );
+      }
+      for (const key of Object.keys(options ?? {})) {
+        if (key !== 'event') {
+          fail(
+            `h.trigger("${name}", …) takes { event } — got "${key}"; pass the payload as { event: { … } }`
+          );
+        }
+      }
+      const handler = flow.triggers?.[name];
+      if (typeof handler !== 'function') {
+        fail(
+          `trigger "${name}" is declared in manifest.json but the default export does not implement it`
+        );
+      }
+
+      const payload = Object.hasOwn(options ?? {}, 'event')
+        ? options.event
+        : jsonCopy(rec.event);
+
+      const run = { failures: [] };
+      const ctx = buildContext(run, name, payload);
+
+      let result;
+      try {
+        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.
+        throw run.failures[0] ?? err;
+      }
+      // A handler that swallowed a refusal (try/catch around a target call,
+      // say) must not turn it into a green test.
+      if (run.failures.length) throw run.failures[0];
+
+      if (def.type === 'call') {
+        // The shim's check before it sends the result: a call's return value
+        // crosses as JSON, and one that cannot fails the run.
+        try {
+          JSON.stringify(result);
+        } catch (err) {
+          throw new Error(
+            `call handler return value is not JSON-serializable: ${err}`
+          );
+        }
+      }
+      return result;
+    },
+
+    ...world.h,
+
+    /**
+     * Applies a scenario through the setters: now, timezone, solar, states,
+     * controls, targets, credentials and llm, and keeps its event for an
+     * h.trigger(name) that gives none. Ignores trigger, expect and
+     * flow_version; fails on any other key.
+     */
+    scenario(s) {
+      applyScenario(h, s, { kind: 'flow' });
+      if (s.event !== undefined) {
+        rec.event = jsonCopy(s.event, 'h.scenario — "event"');
+      }
+      return h;
+    },
+
+    /**
+     * What step.llm(id, …) answers: a string, or a function of the options
+     * that returns one. `id` is the id the source says and answers every
+     * occurrence; `id#N` answers only that occurrence and wins over it.
+     */
+    llm(id, answer) {
+      rec.llm.set(id, answer, 'h.llm');
+      return h;
+    },
+
+    /** Every step.run and step.llm, in order, as the journal records them. */
+    steps: () => rec.steps.map((s) => ({ ...s })),
+    /** Everything handlers logged, with its level. */
+    logs: () => rec.logs.slice(),
+    /** Manifest-vs-module problems; empty when they agree. */
+    conformance: () => flowConformance(manifest, flow),
+
+    ...bindings.h,
+
+    /**
+     * Clears recordings, answers, seeded states, the scenario's event and
+     * scoped memory; keeps the clock, timezone, solar and credentials.
+     */
+    reset() {
+      rec.steps.length = 0;
+      rec.logs.length = 0;
+      rec.llm.clear();
+      rec.event = undefined;
+      bindings.reset();
+      return h;
+    },
+  };
+
+  world.init({ now, timezone, solar });
+
+  /**
+   * One run's ctx, as buildContext in sdk/src/context.ts builds it. Built per
+   * trigger call because the step occurrence counters are per run.
+   */
+  function buildContext(run, trigger, payload) {
+    // Every refusal from inside the handler goes through here, so h.trigger
+    // can rethrow one the handler caught.
+    const refuse = (message) => {
+      try {
+        fail(message);
+      } catch (err) {
+        run.failures.push(err);
+        throw err;
+      }
+    };
+
+    // stepJournalID in the SDK: the first occurrence keeps the bare id, the
+    // second is id#1, the third id#2.
+    const stepCounts = new Map();
+    const stepJournalID = (id) => {
+      const seen = stepCounts.get(id) ?? 0;
+      stepCounts.set(id, seen + 1);
+      return seen === 0 ? id : `${id}#${seen}`;
+    };
+
+    const log = (message, data) =>
+      rec.logs.push({ level: 'debug', message, data });
+    log.warn = (message, data) =>
+      rec.logs.push({ level: 'warn', message, data });
+    log.error = (message, data) =>
+      rec.logs.push({ level: 'error', message, data });
+
+    return {
+      event: flattenTriggerEvent({ trigger, payload }),
+      ...bindings.ctx(refuse),
+
+      step: {
+        async run(id, fn) {
+          const stepId = stepJournalID(id);
+          const result = await fn();
+          const output = result !== undefined ? result : null;
+          let json;
+          try {
+            json = JSON.stringify(output);
+          } catch (err) {
+            throw new Error(
+              `step.run("${stepId}") result is not JSON-serializable: ${err}`
+            );
+          }
+          // The journal holds what crossed the wire, not the live object.
+          rec.steps.push({ id: stepId, output: JSON.parse(json) });
+          return result;
+        },
+
+        async llm(id, options) {
+          const stepId = stepJournalID(id);
+          const key = rec.llm.has(stepId) ? stepId : id;
+          if (!rec.llm.has(key)) {
+            refuse(
+              `step.llm("${stepId}") was not answered — h.llm('${id}', text)`
+            );
+          }
+          const output = await rec.llm.resolve(key, options, refuse);
+          if (typeof output !== 'string') {
+            refuse(
+              `step.llm("${stepId}") was answered with ${typeof output}; an LLM step returns a string`
+            );
+          }
+          rec.steps.push({ id: stepId, output });
+          return output;
+        },
+      },
+
+      status: {
+        ok: (text) => ({ kind: 'ok', text }),
+        error: (text) => ({ kind: 'error', text }),
+        skip: (reason) => ({
+          kind: 'skip',
+          text: reason != null ? `Skipped: ${reason}` : 'Skipped',
+        }),
+      },
+
+      async sleep(...args) {
+        refuse(
+          `a handler cannot suspend in a test: sleep(${renderArgs(args)})`
+        );
+      },
+
+      async waitForEvent(...args) {
+        refuse(
+          `a handler cannot suspend in a test: waitForEvent(${renderArgs(args)})`
+        );
+      },
+
+      log,
+      ...world.ctx(refuse),
+    };
+  }
+
+  return h;
+}
+
+/**
+ * ctx.event, built as the shim builds it: flattenTriggerEvent in
+ * sdk/src/event.ts applied to a wire event carrying only the trigger name and
+ * the test's payload. A plain object is spread onto the event; null or absent
+ * (every timer edge) adds nothing; an array (batch) or any other primitive
+ * stays under `payload`. Nothing the test did not give is synthesized.
+ */
+export function flattenTriggerEvent({
+  payload,
+  source: _s,
+  type: _t,
+  ...rest
+}) {
+  if (payload === null || payload === undefined) return { ...rest };
+  if (typeof payload === 'object' && !Array.isArray(payload)) {
+    return { ...rest, ...payload };
+  }
+  return { ...rest, payload };
+}
+
+/** A call's arguments as the source would spell them, for a refusal. */
+function renderArgs(args) {
+  const given = args.slice();
+  while (given.length && given[given.length - 1] === undefined) given.pop();
+  return given
+    .map((a) => (a === undefined ? 'undefined' : JSON.stringify(a)))
+    .join(', ');
+}