@junoflow/testkit 0.12.0 → 0.13.0

package/README.md

@@ -64,6 +64,8 @@ plain form works.
 | `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.reports()`                          | what `ctx.channels.report` sent, as `{attemptId, status, digit?, option?, reason?}`                                    |
+| `h.replyAnswer({ matched, reply })`    | set what `ctx.channels.reply` answers (default `{ matched: false, reply: null }`)                                      |
+| `h.replies()`                          | what `ctx.channels.reply` sent, as `{channel, address, text}`                                                          |
 | `h.emitted()`                          | `[{ event, payload }]`, in order                                                                                       |
 | `h.logs()`                             | `[{ level, message, data }]`                                                                                           |
 | `h.conformance()`                      | manifest-vs-module problems; `[]` when they agree                                                                      |
@@ -208,6 +210,26 @@ channels, an unknown status, `answered` without exactly one of `digit` and
 attempt does not have. A report on an id the harness never issued is recorded
 rather than refused, so a webhook test can report on a reference it made up.
 
+### `h.replyAnswer({ matched, reply })` and `h.replies()`
+
+```ts
+h.replyAnswer({ matched: false, reply: 'Reply 1 for Yes or 2 for No.' });
+await h.webhook('inboundSms', {
+  body: { From: '+46700000001', Body: 'maybe' },
+});
+expect(h.replies()).toEqual([
+  { channel: 'sms', address: '+46700000001', text: 'maybe' },
+]);
+expect(h.emitted()).toHaveLength(1); // not an answer: the integration's own event
+```
+
+Juno matches a written reply against the questions it holds, which a test does
+not have, so the test says what `ctx.channels.reply` answers: by default
+`{ matched: false, reply: null }` — the message was not an answer. The refusals
+that need no questions fail the test: an install with no channels, and a channel
+that is not declared or does not list `text` in its `answers`. `reset()` clears
+the recorded replies and the answer.
+
 ## What the harness is faithful about
 
 - `ctx.store` round-trips values through JSON, because the real store does. A

package/package.json

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

package/src/ask.js

@@ -23,6 +23,9 @@ const OPTION_KEY = /^[a-z][a-zA-Z0-9]*$/;
 /** The channel an answer came through when the test names none. */
 export const TEST_CHANNEL = 'test:channel';
 
+/** What h.questions.answer takes for an answer. */
+const ANSWER_FIELDS = ['by', 'answer', 'channel', 'text', 'interpreted'];
+
 const runes = (s) => [...s].length;
 
 /** handlekind's quotedNames: sorted, quoted, "none" when empty. */
@@ -214,7 +217,9 @@ export function createPeople(manifest, harness) {
       /**
        * Answers the question whose label is `key` — or `ask#N`, the Nth ask
        * of the trigger (from 1), for an unlabelled one — with
-       * `{ by, answer, channel? }` or `'unanswered'`.
+       * `{ by, answer, channel?, text?, interpreted? }` or `'unanswered'`.
+       * `channel: 'page'` is an answer from the answer page; `text` a written
+       * reply as written, and `interpreted: true` one the site's LLM mapped.
        */
       answer(key, value) {
         if (typeof key !== 'string' || key === '') {
@@ -231,16 +236,33 @@ export function createPeople(manifest, harness) {
             typeof value.answer === 'string';
           if (!ok) {
             fail(
-              `h.questions.answer('${key}', …) — expected { by, answer, channel? } or 'unanswered', got ${JSON.stringify(value)}`
+              `h.questions.answer('${key}', …) — expected { by, answer, channel?, text?, interpreted? } or 'unanswered', got ${JSON.stringify(value)}`
             );
           }
           for (const k of Object.keys(value)) {
-            if (!['by', 'answer', 'channel'].includes(k)) {
+            if (!ANSWER_FIELDS.includes(k)) {
+              fail(
+                `h.questions.answer('${key}', …) — "${k}" is not part of an answer (have: ${ANSWER_FIELDS.join(', ')})`
+              );
+            }
+          }
+          for (const k of ['channel', 'text']) {
+            if (value[k] !== undefined && typeof value[k] !== 'string') {
               fail(
-                `h.questions.answer('${key}', …) — "${k}" is not part of an answer (have: by, answer, channel)`
+                `h.questions.answer('${key}', …) — ${k} is a string; got ${JSON.stringify(value[k])}`
               );
             }
           }
+          if (value.interpreted !== undefined && value.interpreted !== true) {
+            fail(
+              `h.questions.answer('${key}', …) — interpreted is true or absent; got ${JSON.stringify(value.interpreted)}`
+            );
+          }
+          if (value.interpreted && value.text === undefined) {
+            fail(
+              `h.questions.answer('${key}', …) — interpreted needs the text the LLM read`
+            );
+          }
           declared(`h.questions.answer('${key}', …)`, value.by);
           value = { ...value };
         }
@@ -296,11 +318,15 @@ export function createPeople(manifest, harness) {
               `h.questions.answer('${key}', …) — "${answer.answer}" is not one of the question's options (have: ${Object.keys(q.options).join(', ')})`
             );
           }
+          // The host's AnsweredValue, in its field order: text and
+          // interpreted only when set.
           value = {
             outcome: 'answered',
             answer: answer.answer,
             by: answer.by,
             channel: answer.channel ?? TEST_CHANNEL,
+            ...(answer.text !== undefined && { text: answer.text }),
+            ...(answer.interpreted && { interpreted: true }),
             at: rfc3339(instant() ?? Date.now()),
           };
         }

package/src/index.d.ts

@@ -132,6 +132,19 @@ export interface RecordedReport {
   reason?: string;
 }
 
+/** One ctx.channels.reply call, as the harness recorded it. */
+export interface RecordedReply {
+  channel: string;
+  address: string;
+  text: string;
+}
+
+/** What ctx.channels.reply answers; set with h.replyAnswer. */
+export interface ReplyAnswer {
+  matched: boolean;
+  reply: string | null;
+}
+
 export interface WebhookRequestInit {
   method?: string;
   headers?: Record<string, string>;
@@ -276,6 +289,13 @@ export interface Harness {
   status(): RecordedStatus | null;
   /** What ctx.channels.report sent, in order. Cleared by reset(). */
   reports(): RecordedReport[];
+  /** What ctx.channels.reply sent, in order. Cleared by reset(). */
+  replies(): RecordedReply[];
+  /**
+   * Sets what ctx.channels.reply answers from now on; the default is
+   * {matched: false, reply: null}. Cleared by reset().
+   */
+  replyAnswer(answer?: Partial<ReplyAnswer>): Harness;
   emitted(): EmittedEvent[];
   logs(): LogEntry[];
   /** Manifest-vs-module problems; empty when they agree. */
@@ -560,7 +580,19 @@ export interface RecordedHandle {
  * round over.
  */
 export type QuestionAnswer =
-  | { by: string; answer: string; channel?: string }
+  | {
+      by: string;
+      answer: string;
+      /**
+       * `<install>:<channel>` the answer came through, `'page'` for the
+       * answer page; `test:channel` when omitted.
+       */
+      channel?: string;
+      /** A written reply, as the person wrote it. */
+      text?: string;
+      /** The site's LLM mapped `text` onto `answer` (freeText: 'interpret'). */
+      interpreted?: true;
+    }
   | 'unanswered';
 
 /** A question a handler asked, as the host stores it: defaults applied. */
@@ -594,7 +626,8 @@ export interface FlowQuestions {
   /**
    * Answers the question whose `label` is key — or `ask#N`, the Nth ask of the
    * trigger (from 1), for one without a label. An answer fires the question at
-   * open with `{ outcome: 'answered', answer, by, channel, at }`, `at` being
+   * open with `{ outcome: 'answered', answer, by, channel, text?, interpreted?, at }`
+   * (text and interpreted passed through when given), `at` being
    * h.now() (or the wall clock with none set); `by` must be one of its `to`
    * and `answer` one of its option keys. `'unanswered'` fires it with
    * `{ outcome: 'unanswered', attempts: to.length * rounds }` — the host does

package/src/index.js

@@ -47,6 +47,10 @@ export function harness({ manifest, integration } = {}) {
     status: null,
     // What ctx.channels.report sent, in order. Cleared by reset().
     reports: [],
+    // What ctx.channels.reply sent, in order, and what it answers: the
+    // harness has no questions to match against, so the test says.
+    replies: [],
+    replyAnswer: { matched: false, reply: null },
     // The attempts h.deliver/h.withdraw handed a channel, by id: a report on
     // one of them is checked against its options the way the host checks it.
     attempts: new Map(),
@@ -259,6 +263,17 @@ export function harness({ manifest, integration } = {}) {
       },
     /** What ctx.channels.report sent, in order. */
     reports: () => state.reports.map((r) => ({ ...r })),
+    /** What ctx.channels.reply sent, as {channel, address, text}, in order. */
+    replies: () => state.replies.map((r) => ({ ...r })),
+    /**
+     * Sets what ctx.channels.reply answers from now on (default
+     * {matched: false, reply: null}): Juno matches a reply against the
+     * questions it holds, which a test does not have.
+     */
+    replyAnswer({ matched = false, reply = null } = {}) {
+      state.replyAnswer = { matched: matched === true, reply: reply ?? null };
+      return h;
+    },
     /** Events the handler put on the bus, in order. */
     emitted: () => state.emitted.slice(),
     /** Everything the handler logged, with its level. */
@@ -275,6 +290,8 @@ export function harness({ manifest, integration } = {}) {
       state.publishedStates.clear();
       state.status = null;
       state.reports.length = 0;
+      state.replies.length = 0;
+      state.replyAnswer = { matched: false, reply: null };
       state.attempts.clear();
       state.store.clear();
       http.reset();
@@ -402,6 +419,25 @@ function reportChannel(manifest, state, attemptId, report) {
   });
 }
 
+/**
+ * The one call behind ctx.channels.reply, applying the host's refusals that
+ * need no database: an install with no channels, and a channel that is not
+ * declared or does not take text. It records the message (only the fields the
+ * SDK sends) and answers what h.replyAnswer set.
+ */
+function replyChannel(manifest, state, message) {
+  const install = manifest.id ?? manifest.name;
+  if (Object.keys(manifest.channels ?? {}).length === 0) {
+    fail(`channel.reply: ${install} declares no channels`);
+  }
+  const { channel, address, text } = message ?? {};
+  if (!manifest.channels[channel]?.answers?.includes('text')) {
+    fail(`channel.reply: ${install} has no text channel "${channel}"`);
+  }
+  state.replies.push({ channel, address, text });
+  return { ...state.replyAnswer };
+}
+
 /**
  * The base context, matching what integration-entrypoint.ts builds. Handlers
  * cannot tell the difference, which is the only way a test here means anything
@@ -472,6 +508,9 @@ function buildContext(manifest, state, webhooks) {
       async report(attemptId, report) {
         reportChannel(manifest, state, attemptId, report);
       },
+      async reply(message) {
+        return replyChannel(manifest, state, message);
+      },
     },
   };
 }