@junoflow/testkit 0.1.1 → 0.1.2

package/README.md

@@ -15,7 +15,7 @@ import integration from '../src/integration';
 
 const h = harness({ manifest, integration });
 
-// Mocked routes, the store, problems, events and logs otherwise outlive an
+// 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());
 
@@ -28,7 +28,8 @@ test('sendNotification posts to the API and returns the receipt', async () => {
   expect(await h.action('sendNotification', { message: 'hi' })).toEqual({
     request: 'r1',
   });
-  expect(h.problems()).toEqual([]);
+  // Nothing standing: the success path proved the credentials work.
+  expect(h.findings()).toEqual([]);
 });
 
 test('conforms to its manifest', () => {
@@ -45,21 +46,21 @@ plain form works.
 
 `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` (`get`/`set`/`delete` all land here)    |
-| `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`
 
@@ -102,13 +103,36 @@ 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

package/package.json

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

package/src/index.d.ts

@@ -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;
@@ -103,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 {
@@ -141,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,7 +32,7 @@ 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.
@@ -166,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. */
@@ -178,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();
@@ -230,26 +236,67 @@ function buildContext(manifest, state) {
         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 {