@junoflow/testkit 0.1.0 → 0.1.1

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,17 +10,23 @@ 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, problems, 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(await h.action('sendNotification', { message: 'hi' })).toEqual({
+    request: 'r1',
   });
   expect(h.problems()).toEqual([]);
 });
@@ -30,25 +36,10 @@ 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
 
@@ -62,7 +53,7 @@ manifest says one thing and the code does another.
 | `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.store`                              | the KV, as a plain `Map` (`get`/`set`/`delete` all land here)    |
 | `h.problems()`                         | what `ctx.problems.report` recorded                              |
 | `h.emitted()`                          | `[{ event, payload }]`, in order                                 |
 | `h.logs()`                             | `[{ level, message, data }]`                                     |
@@ -83,9 +74,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`
 
@@ -113,3 +109,7 @@ is one fix, not four runs.
 - 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.
+- 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.1",
+  "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;
@@ -72,7 +72,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
@@ -110,7 +115,7 @@ export interface EmittedEvent {
 }
 
 export interface LogEntry {
-  level: 'debug' | 'warn' | 'error';
+  level: 'debug' | 'info' | 'warn' | 'error';
   message: string;
   data?: unknown;
 }

package/src/index.js

@@ -35,6 +35,10 @@ export function harness({ manifest, integration } = {}) {
     problems: [],
     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),
@@ -190,6 +198,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 +209,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,6 +223,12 @@ 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 = {}) {
@@ -257,6 +277,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 +307,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) {