@junoflow/testkit 0.1.5 → 0.6.0

package/README.md

@@ -58,6 +58,7 @@ plain form works.
 | `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.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.emitted()`                          | `[{ event, payload }]`, in order                                         |
 | `h.logs()`                             | `[{ level, message, data }]`                                             |
 | `h.conformance()`                      | manifest-vs-module problems; `[]` when they agree                        |
@@ -144,6 +145,25 @@ name the handler used, not the `<install>:<name>` id Juno scopes it to on the
 wire. An undeclared name **fails the test**, the same way an undeclared finding
 or event does.
 
+### `h.status()`
+
+```ts
+await h.schedule('fetchForecast');
+expect(h.status()).toEqual({
+  summary: '2.4 °C, cloudy — 96 intervals to 2026-09-27',
+  details: { intervals: 96 },
+});
+```
+
+`ctx.status.set` is on the base context, like `ctx.states.publish`. The report
+is replaced on every write, so `h.status()` is the last one sent, and `null`
+when the handler never reported. That is a result worth asserting too: an
+integration with nothing to say should leave the status absent. `details` is
+left out when the report had none or had an empty map. A report Juno would
+reject **fails the test**: an empty or multi-line summary, a summary longer than
+200 characters, or a detail that is not a string, number or boolean. The error
+names the key.
+
 ### `h.hook(name)`
 
 ```ts
@@ -164,6 +184,8 @@ hook reports through ctx and returns nothing" is what production says too.
   because the runtime always supplies them.
 - `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.
+- `ctx.status.set` details round-trip through JSON before validation, as they do
+  on the wire, so a `NaN` shows up as `null` and is rejected there as well.
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoflow/testkit",
-  "version": "0.1.5",
+  "version": "0.6.0",
   "description": "Test harness for Juno integrations",
   "license": "MIT",
   "repository": {

package/src/index.d.ts

@@ -94,6 +94,7 @@ export interface WebhookRequestInit {
   /** A string is sent as-is; anything else is JSON.stringify'd. */
   body?: unknown;
   url?: string;
+  subpath?: string;
 }
 
 export interface WebhookResult {
@@ -154,6 +155,13 @@ export interface RecordedFinding {
   standing: boolean;
 }
 
+/** The install's status report, as ctx.status.set last replaced it. */
+export interface RecordedStatus {
+  summary: string;
+  /** Absent when the report carried none, or an empty map. */
+  details?: Record<string, string | number | boolean>;
+}
+
 export interface EmittedEvent {
   event: string;
   payload: unknown;
@@ -191,6 +199,8 @@ export interface Harness {
   findings(): RecordedFinding[];
   /** Values ctx.states.publish has sent so far, keyed by local name. */
   states(): Record<string, unknown>;
+  /** The last ctx.status.set report, or null when the handler never reported. */
+  status(): RecordedStatus | null;
   emitted(): EmittedEvent[];
   logs(): LogEntry[];
   /** Manifest-vs-module problems; empty when they agree. */

package/src/index.js

@@ -39,6 +39,9 @@ export function harness({ manifest, integration } = {}) {
     // publish of the same name overwrites rather than accumulates — h.states()
     // is the current picture, not a log.
     publishedStates: new Map(),
+    // The last ctx.status.set report, or null before the first. One slot, not
+    // a list: the host replaces the report on every write.
+    status: null,
     // 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.
@@ -206,6 +209,15 @@ export function harness({ manifest, integration } = {}) {
     findings: () => state.findings.map((f) => ({ ...f })),
     /** Values ctx.states.publish has sent so far, keyed by local name. */
     states: () => Object.fromEntries(state.publishedStates),
+    /**
+     * The last report ctx.status.set sent, or null when the handler never
+     * reported — absence is a legitimate outcome, not an empty report.
+     */
+    status: () =>
+      state.status && {
+        ...state.status,
+        ...(state.status.details && { details: { ...state.status.details } }),
+      },
     /** Events the handler put on the bus, in order. */
     emitted: () => state.emitted.slice(),
     /** Everything the handler logged, with its level. */
@@ -220,6 +232,7 @@ export function harness({ manifest, integration } = {}) {
       state.emitted.length = 0;
       state.logs.length = 0;
       state.publishedStates.clear();
+      state.status = null;
       state.store.clear();
       http.reset();
       return h;
@@ -285,6 +298,11 @@ function buildContext(manifest, state) {
         publishStates(manifest, state, values);
       },
     },
+    status: {
+      async set(report) {
+        setStatus(state, report);
+      },
+    },
   };
 }
 
@@ -357,6 +375,53 @@ function publishStates(manifest, state, values) {
   }
 }
 
+/** The longest summary the host accepts, in characters (registry.MaxStatusSummary). */
+const MAX_STATUS_SUMMARY = 200;
+
+/**
+ * The one call behind ctx.status.set, applying the checks registry.ValidateStatus
+ * applies: a non-empty one-line summary of at most 200 characters, and details
+ * whose values are all scalars. Details round-trip through JSON first, as they
+ * do on the wire — a NaN arrives as null and is rejected there too. An empty
+ * details map is stored as none, the way the host writes NULL for it.
+ */
+function setStatus(state, report) {
+  const summary = report?.summary;
+  if (typeof summary !== 'string' || summary.trim() === '') {
+    fail('ctx.status.set — status summary is required');
+  }
+  if (/[\r\n]/.test(summary)) {
+    fail(
+      'ctx.status.set — status summary must be one line; put the rest in details'
+    );
+  }
+  // Counted in code points, as the host counts runes.
+  const length = [...summary].length;
+  if (length > MAX_STATUS_SUMMARY) {
+    fail(
+      `ctx.status.set — status summary is ${length} characters, the limit is ${MAX_STATUS_SUMMARY}; put the rest in details`
+    );
+  }
+  const details =
+    report.details == null ? {} : JSON.parse(JSON.stringify(report.details));
+  for (const [key, value] of Object.entries(details)) {
+    if (!['string', 'number', 'boolean'].includes(typeof value)) {
+      fail(
+        `ctx.status.set — status detail ${JSON.stringify(key)} must be a string, number or boolean, got ${describeJSON(value)}`
+      );
+    }
+  }
+  state.status = Object.keys(details).length
+    ? { summary, details }
+    : { summary };
+}
+
+function describeJSON(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return typeof value === 'object' ? 'an object' : typeof value;
+}
+
 /** Adds ctx.emit, which every surface but an action has. */
 function emitting(baseCtx, manifest, state) {
   return {
@@ -437,18 +502,50 @@ function requireHandler(integration, surface, name, kind) {
 }
 
 function buildWebhookRequest(request) {
+  const body =
+    typeof request.body === 'string'
+      ? request.body
+      : JSON.stringify(request.body ?? '');
+  const headers = request.headers ?? {};
   return {
     method: (request.method ?? 'POST').toUpperCase(),
-    headers: request.headers ?? {},
+    headers,
     query: request.query ?? {},
-    body:
-      typeof request.body === 'string'
-        ? request.body
-        : JSON.stringify(request.body ?? ''),
+    body,
+    json: parseJSONOrNull(body),
     url: request.url ?? '/',
+    subpath: request.subpath ?? '',
+    form: parseFormOrNull(headers, body),
   };
 }
 
+// The host's rule: lower-cased content-type, media type
+// application/x-www-form-urlencoded (a charset parameter is ignored), first
+// value per key — else null.
+function parseFormOrNull(headers, body) {
+  const contentType = (headers['content-type'] ?? headers['Content-Type'] ?? '')
+    .toLowerCase()
+    .split(';')[0]
+    .trim();
+  if (contentType !== 'application/x-www-form-urlencoded') return null;
+  const form = {};
+  for (const [key, value] of new URLSearchParams(body)) {
+    if (!(key in form)) form[key] = value;
+  }
+  return form;
+}
+
+// The host's rule (cmd/control-plane readWebhookRequest): whatever parses is
+// parsed, whatever does not is null — content-type is not consulted.
+function parseJSONOrNull(body) {
+  if (body === '') return null;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+
 /** A webhook returns nothing, or the {status, headers, body} control shape. */
 function assertWebhookResponse(name, result) {
   if (result === undefined || result === null) return;