@junoflow/testkit 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,8 @@
 # @junoflow/testkit
 
 Test harness for [Juno](https://github.com/boivie/juno) integrations. It runs
-your handlers with the same `ctx` the sandbox builds, and **checks every
-crossing against your manifest**.
+your handlers with the same `ctx` the sandbox builds, but with a different
+implementation for tests.
 
 ```bash
 npm install --save-dev @junoflow/testkit
@@ -10,19 +10,26 @@ npm install --save-dev @junoflow/testkit
 
 ```ts
 import { harness } from '@junoflow/testkit';
-import manifest from '../manifest.json' with { type: 'json' };
+import manifest from '../manifest.json';
 import integration from '../src/integration';
 
 const h = harness({ manifest, integration });
 
-test('notify posts to the API and returns the receipt', async () => {
-  h.credentials({ appToken: 'tok' });
-  h.http.post('https://api.pushover.net/1/messages.json', { receipt: 'r1' });
+// Mocked routes, the store, findings, events and logs otherwise outlive an
+// `it`, and the test that fails is whichever one ran second.
+beforeEach(() => h.reset());
 
-  expect(await h.action('notify', { message: 'hi' })).toEqual({
-    receipt: 'r1',
+test('sendNotification posts to the API and returns the receipt', async () => {
+  h.credentials({ appToken: 'tok', userKey: 'usr' });
+  h.http.post('https://api.pushover.net/1/messages.json', {
+    json: { status: 1, request: 'r1' },
   });
-  expect(h.problems()).toEqual([]);
+
+  expect(await h.action('sendNotification', { message: 'hi' })).toEqual({
+    request: 'r1',
+  });
+  // Nothing standing: the success path proved the credentials work.
+  expect(h.findings()).toEqual([]);
 });
 
 test('conforms to its manifest', () => {
@@ -30,45 +37,30 @@ test('conforms to its manifest', () => {
 });
 ```
 
-Runner-agnostic: plain functions and thrown `AssertionError`s, no runner
-imported. vitest is what the scaffold uses; `node:test` and jest work unchanged.
-
-## Why the manifest checking matters
-
-Juno checks the contract when it **runs** an integration, which is too late to
-be a test — an installer finds out instead. The harness moves that forward:
-
-| Crossing                     | Checked against                      |
-| ---------------------------- | ------------------------------------ |
-| action params in             | the action's `params` schema         |
-| action result out            | the action's `response` schema       |
-| `ctx.emit(name, …)`          | `events` — an undeclared name throws |
-| emitted payload              | the event's `payload` schema         |
-| webhook return value         | `{ status?, headers?, body? }`       |
-| `h.config` / `h.credentials` | the declared slot, and its kind      |
-
-The failure mode this catches is the one that actually bites installers: the
-manifest says one thing and the code does another.
+Note the plain `import manifest from '../manifest.json'` — the shared
+`tsconfig.base.json` compiles as CommonJS, where an import attribute
+(`with { type: 'json' }`) is a TS2823 error. `resolveJsonModule` is on, so the
+plain form works.
 
 ## API
 
 `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.poll(name)`                         | run a poll                                                       |
-| `h.listen({ until, events, timeout })` | run the listener until the condition holds, then abort           |
-| `h.store`                              | the KV, as a plain `Map`                                         |
-| `h.problems()`                         | what `ctx.problems.report` recorded                              |
-| `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.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.poll(name)`                         | run a poll                                                               |
+| `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.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`
 
@@ -83,9 +75,14 @@ h.http.post('https://api.example.com/send', (req) => ({ echoed: req.body }));
 h.http.requests; // every request a handler made, in order
 ```
 
-An **unmatched request throws**, naming the URL and listing what is mocked. A
-test that silently reaches the real internet is the worst outcome here, so there
-is no passthrough mode.
+An **unmatched request throws**, to ensure that all HTTP calls are expected.
+
+A canned answer is either the upstream's JSON body verbatim, or the envelope
+`{ status?, headers?, json?, body? }`. The two are told apart by an _exclusive_
+key match: an object is an envelope only when **every** key it has is one of
+those four. So an upstream payload that happens to contain `status` — Pushover's
+`{ status: 1, request: '…' }` — is a body, as written. When a payload consists
+only of envelope keys, say so: `{ json: { status: 1 } }`.
 
 ### `h.listen`
 
@@ -106,10 +103,37 @@ webhook or poll to produce them, and every schema compiling. Returns all
 problems rather than the first — "you declared six actions and implemented four"
 is one fix, not four runs.
 
+### `h.findings()`
+
+```ts
+expect(h.findings()).toEqual([
+  {
+    slug: 'badCredentials',
+    key: '',
+    severity: 'error',
+    text: 'Pushover rejected the credentials',
+    standing: true,
+  },
+]);
+```
+
+`open`, `clear` and `set` all land here, each returning the transition it made
+(`{ opened, cleared }`, both false when it refreshed or retracted nothing). An
+undeclared name **fails the test**, naming the declared ones — Juno rejects it
+at runtime, and hearing that from an installer is not a test. An instance the
+handler retracted stays in the list with `standing: false`; one that was never
+open records nothing at all, so `expect(h.findings()).toEqual([])` is the
+success-path assertion for a handler written with `set()`.
+
 ## What the harness is faithful about
 
 - `ctx.store` round-trips values through JSON, because the real store does. A
   `Date` comes back as a string here exactly as it would in production.
 - Config defaults declared in the manifest are applied before your test runs,
   because the runtime always supplies them.
-- `ctx.problems.report` upserts by key, as the server does.
+- `ctx.findings` refreshes in place on `(slug, key)`, as the store does, and
+  rejects a name the manifest does not declare, as the host does.
+- A required slot must be set before a handler runs. An install cannot start
+  with one empty, so a handler never sees one — a test that skipped
+  `h.credentials(...)` would be green for a state production forbids, with
+  `undefined` sitting where the generated types promise a `string`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@junoflow/testkit",
-  "version": "0.1.0",
-  "description": "Test harness for Juno integrations: runs your handlers with a real context and checks every crossing against your manifest.",
+  "version": "0.1.2",
+  "description": "Test harness for Juno integrations",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -20,12 +20,6 @@
     "src",
     "README.md"
   ],
-  "keywords": [
-    "juno",
-    "junoflow",
-    "testing",
-    "integration"
-  ],
   "scripts": {
     "test": "node --test \"test/**/*.test.js\""
   },

package/src/http.js

@@ -74,19 +74,31 @@ function matches(pattern, url) {
   return pattern === url;
 }
 
+/** The keys an envelope is allowed to have, and nothing else. */
+const ENVELOPE_KEYS = ['status', 'headers', 'json', 'body'];
+
 /**
  * Accepts the two shapes a test wants to write: a bare object (200 JSON, the
  * overwhelmingly common case) or a full {status, headers, json|body}.
+ *
+ * The two are told apart by an *exclusive* key match — every key must be an
+ * envelope key — rather than by asking whether any envelope key is present.
+ * `status` is one of the most common keys in a REST payload (Pushover answers
+ * `{"status": 1, "request": "…"}`), and sniffing for it meant the natural mock
+ * for such an API was silently read as an envelope: `{status: 1}` threw a
+ * RangeError from undici pointing at the author's fetch call, and `{status:
+ * 200, …}` was worse, quietly delivering an empty body to correct code. An
+ * upstream payload almost never consists solely of envelope keys; when it does,
+ * the range guard below names the fix rather than letting undici do it.
  */
 function toResponse(answer) {
   if (answer instanceof Response) return answer;
   const isEnvelope =
     answer !== null &&
     typeof answer === 'object' &&
-    ('status' in answer ||
-      'json' in answer ||
-      'body' in answer ||
-      'headers' in answer);
+    !Array.isArray(answer) &&
+    Object.keys(answer).length > 0 &&
+    Object.keys(answer).every((k) => ENVELOPE_KEYS.includes(k));
 
   const {
     status = 200,
@@ -94,6 +106,14 @@ function toResponse(answer) {
     json,
     body,
   } = isEnvelope ? answer : { json: answer };
+  if (!Number.isInteger(status) || status < 100 || status > 599) {
+    fail(
+      `mock response has status ${JSON.stringify(status)}, which is not an HTTP status.\n` +
+        `Every key of ${JSON.stringify(answer)} happens to be an envelope key, so it was read as ` +
+        `{status, headers, json, body} rather than as a body.\n` +
+        `If it is the upstream's payload, wrap it: { json: ${JSON.stringify(answer)} }.`
+    );
+  }
   if (json !== undefined) {
     return new Response(JSON.stringify(json), {
       status,

package/src/index.d.ts

@@ -20,7 +20,7 @@ export interface ManifestConfigSlot {
   type: string;
   title?: string;
   description?: string;
-  docs_url?: string;
+  docsUrl?: string;
   default?: unknown;
   required?: boolean;
   credential?: boolean;
@@ -37,6 +37,10 @@ export interface Manifest {
     { params?: object; response?: object; [k: string]: unknown }
   >;
   events?: Record<string, { payload?: object; [k: string]: unknown }>;
+  findings?: Record<
+    string,
+    { title?: string; severity?: string; ttl?: string; [k: string]: unknown }
+  >;
   webhooks?: Record<string, unknown>;
   polls?: Record<string, unknown>;
   [k: string]: unknown;
@@ -72,7 +76,12 @@ export interface RecordedRequest {
   body: BodyInit | null;
 }
 
-/** A canned answer: a bare object is 200 JSON, the common case. */
+/**
+ * A canned answer: the upstream's JSON body verbatim (the common case), or the
+ * `{status, headers, json, body}` envelope — recognised only when *every* key
+ * is one of those four, so a payload that merely contains `status` stays a
+ * body. Wrap one that does not: `{ json: { status: 1 } }`.
+ */
 export type MockResponse =
   | object
   | Response
@@ -98,10 +107,18 @@ export interface HttpMock {
   reset(): HttpMock;
 }
 
-export interface ReportedProblem {
+/**
+ * One instance of a declared finding, as the harness recorded it. A retracted
+ * instance stays in the list with `standing: false`; one that was never opened
+ * is absent entirely.
+ */
+export interface RecordedFinding {
+  /** The name as the manifest declares it — the harness does not prefix the install. */
+  slug: string;
   key: string;
-  message: string;
-  severity: 'error' | 'warning';
+  severity: 'info' | 'warn' | 'error';
+  text: string;
+  standing: boolean;
 }
 
 export interface EmittedEvent {
@@ -110,7 +127,7 @@ export interface EmittedEvent {
 }
 
 export interface LogEntry {
-  level: 'debug' | 'warn' | 'error';
+  level: 'debug' | 'info' | 'warn' | 'error';
   message: string;
   data?: unknown;
 }
@@ -136,7 +153,7 @@ export interface Harness {
   listen(options?: ListenOptions): Promise<void>;
   /** The integration's KV, as an ordinary Map. */
   readonly store: Map<string, unknown>;
-  problems(): ReportedProblem[];
+  findings(): RecordedFinding[];
   emitted(): EmittedEvent[];
   logs(): LogEntry[];
   /** Manifest-vs-module problems; empty when they agree. */

package/src/index.js

@@ -32,9 +32,13 @@ export function harness({ manifest, integration } = {}) {
     config: defaultConfig(manifest),
     credentials: {},
     store: new Map(),
-    problems: [],
+    findings: [],
     emitted: [],
     logs: [],
+    // ctx.signal for every surface but the listener, which brings its own.
+    // Never aborted here: the host aborts it on a timeout or a shutdown, and a
+    // test has neither.
+    abort: new AbortController(),
   };
 
   const http = createHttpMock();
@@ -63,6 +67,7 @@ export function harness({ manifest, integration } = {}) {
         );
       }
       const handler = requireHandler(integration, 'actions', name, 'action');
+      assertRequiredSlots(manifest, state);
       assertValid(declared.params, params, `params for action "${name}"`);
 
       const result = await withFetch(http.fetch, () => handler(params, ctx));
@@ -79,6 +84,7 @@ export function harness({ manifest, integration } = {}) {
         );
       }
       const handler = requireHandler(integration, 'webhooks', name, 'webhook');
+      assertRequiredSlots(manifest, state);
       const req = buildWebhookRequest(request);
 
       const result = await withFetch(http.fetch, () =>
@@ -95,6 +101,7 @@ export function harness({ manifest, integration } = {}) {
         );
       }
       const handler = requireHandler(integration, 'polls', name, 'poll');
+      assertRequiredSlots(manifest, state);
       const result = await withFetch(http.fetch, () =>
         handler(emitting(ctx, manifest, state))
       );
@@ -114,6 +121,7 @@ export function harness({ manifest, integration } = {}) {
       if (typeof integration.listener !== 'function') {
         fail('the default export has no listener function');
       }
+      assertRequiredSlots(manifest, state);
       const controller = new AbortController();
       const listenerCtx = {
         ...emitting(ctx, manifest, state),
@@ -158,8 +166,14 @@ export function harness({ manifest, integration } = {}) {
 
     /** The integration's KV, as an ordinary Map. */
     store: state.store,
-    /** Problems the handler reported through ctx.problems. */
-    problems: () => state.problems.slice(),
+    /**
+     * Findings the handler asserted through ctx.findings, in the order they
+     * were first asserted. An instance the handler retracted stays in the list
+     * with `standing: false` — that a handler cleared what it opened is itself
+     * worth asserting — while a retraction of something never open records
+     * nothing, exactly as the host no-ops it.
+     */
+    findings: () => state.findings.map((f) => ({ ...f })),
     /** Events the handler put on the bus, in order. */
     emitted: () => state.emitted.slice(),
     /** Everything the handler logged, with its level. */
@@ -170,7 +184,7 @@ export function harness({ manifest, integration } = {}) {
 
     /** Clears everything a handler recorded, keeping config and credentials. */
     reset() {
-      state.problems.length = 0;
+      state.findings.length = 0;
       state.emitted.length = 0;
       state.logs.length = 0;
       state.store.clear();
@@ -190,6 +204,8 @@ export function harness({ manifest, integration } = {}) {
 function buildContext(manifest, state) {
   const log = (message, data) =>
     state.logs.push({ level: 'debug', message, data });
+  log.info = (message, data) =>
+    state.logs.push({ level: 'info', message, data });
   log.warn = (message, data) =>
     state.logs.push({ level: 'warn', message, data });
   log.error = (message, data) =>
@@ -199,6 +215,10 @@ function buildContext(manifest, state) {
     config: state.config,
     credentials: state.credentials,
     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;
+    // h.listen replaces it with one it controls.
+    signal: state.abort.signal,
     store: {
       async get(key) {
         return state.store.has(key) ? state.store.get(key) : null;
@@ -209,27 +229,74 @@ function buildContext(manifest, state) {
         // that passes on an object production never sees.
         state.store.set(key, JSON.parse(JSON.stringify(value ?? null)));
       },
+      async delete(key) {
+        // Deleting an absent key is not an error here either — the host
+        // answers {ok} for both, and a handler must not learn to branch on a
+        // difference that does not exist.
+        state.store.delete(key);
+      },
     },
-    problems: {
-      async report(key, message, opts = {}) {
-        const severity = opts.severity ?? 'error';
-        if (severity !== 'error' && severity !== 'warning') {
-          fail(
-            `ctx.problems.report severity must be "error" or "warning", got ${JSON.stringify(severity)}`
-          );
-        }
-        const existing = state.problems.find((p) => p.key === key);
-        if (existing) Object.assign(existing, { message, severity });
-        else state.problems.push({ key, message, severity });
+    findings: {
+      async open(slug, opts = {}) {
+        return setFinding(manifest, state, slug, true, opts);
+      },
+      async clear(slug, opts = {}) {
+        return setFinding(manifest, state, slug, false, opts);
       },
-      async clear(key) {
-        const at = state.problems.findIndex((p) => p.key === key);
-        if (at >= 0) state.problems.splice(at, 1);
+      async set(slug, standing, opts = {}) {
+        return setFinding(manifest, state, slug, standing === true, opts);
       },
     },
   };
 }
 
+/**
+ * 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.
+ */
+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 };
+}
+
 /** Adds ctx.emit, which every surface but an action has. */
 function emitting(baseCtx, manifest, state) {
   return {
@@ -257,6 +324,29 @@ function defaultConfig(manifest) {
   return out;
 }
 
+/**
+ * Fails when a required slot is unset, before the handler runs.
+ *
+ * An install cannot start with a required slot empty, so a handler never sees
+ * one — but nothing stopped a test from running that way, and the generated
+ * types say `string` while the value is `undefined`. That combination produces
+ * a green test for a state production forbids, and a crash on the first
+ * `token.trim()` the types promised was safe.
+ */
+function assertRequiredSlots(manifest, state) {
+  for (const [name, slot] of Object.entries(manifest.config ?? {})) {
+    if (!slot.required) continue;
+    const held = slot.credential ? state.credentials : state.config;
+    if (held[name] !== undefined) continue;
+    const setter = slot.credential ? 'credentials' : 'config';
+    fail(
+      `required ${slot.credential ? 'credential' : 'config'} slot "${name}" is not set — ` +
+        `an install with it empty is rejected, so a handler never runs without it. ` +
+        `Set it with h.${setter}({ ${name}: … }).`
+    );
+  }
+}
+
 /** Rejects a slot name the manifest never declared, or one of the wrong kind. */
 function assertSlots(manifest, values, wantCredential) {
   const kind = wantCredential ? 'credential' : 'config';
@@ -264,7 +354,7 @@ function assertSlots(manifest, values, wantCredential) {
     const slot = manifest.config?.[name];
     if (!slot) {
       fail(
-        `"${name}" is not a config slot declared in manifest.json (have: ${names(manifest.config)})`
+        `"${name}" is not a ${kind} slot declared in manifest.json (have: ${names(manifest.config)})`
       );
     }
     if (Boolean(slot.credential) !== wantCredential) {