docs(js/testing): demonstrate queue, error injection, toolResponses, and interrupts in the sample

Extend testing-sample so the sample app exercises the features added
during review, not just the base mockModel/echoModel:

- a confirmBooking interrupt tool shows a human-in-the-loop pause/resume
  round-trip (via restart). The app now imports genkit/beta since
  interrupts are a beta feature; everything else is unchanged.
- response-queue scripting (respond: [...]) for a concise two-turn tool
  interaction with no branching callback.
- error injection via a queued Error.
- model.toolResponses to assert which tools ran and what they returned,
  replacing manual message digging.

Covered under both node:test (10) and vitest (6); README updated.

Author: cabljac

js/testapps/testing-sample/README.md

@@ -10,7 +10,10 @@ streaming deterministically, without a live model, network, or API key.
 - a `recommendDish` flow that asks for a **structured** recommendation, then
   applies its own logic — validating the result and deriving `withinBudget`;
 - a `streamRecommendation` flow that streams the model's tokens out through the
-  flow's own stream.
+  flow's own stream;
+- a `confirmBooking` tool that `interrupt()`s for human confirmation
+  (human-in-the-loop). This is why the app imports `genkit/beta` — interrupts
+  are a beta feature; everything else works identically on the stable `genkit`.
 
 `createMenuApp()` is a factory so each test builds a fresh, isolated app. The
 default model is referenced by name only (`'menuModel'`), so tests register a
@@ -24,7 +27,16 @@ mock under that name and the app code runs unchanged.
   *your* code, not the model.
 - **Error paths** — script an invalid response and assert the flow rejects it.
 - **Tool round-trip** — return `toolRequests` from the mock; the framework
-  dispatches the real tool and calls the model again with the result.
+  dispatches the real tool and calls the model again with the result. Assert
+  what ran via `model.toolResponses` (the tool results fed back to the model).
+- **Scripting with a queue** — pass `respond: [...]` an array consumed one item
+  per call (last repeating), so a multi-turn tool interaction needs no branching
+  callback.
+- **Injected failures** — a queued `Error` (`respond: [new Error(...)]`) is
+  thrown when reached, to test how a flow handles a model failure.
+- **Human-in-the-loop** — the model requests `confirmBooking`, the tool
+  interrupts, generation pauses (`response.interrupts`), then `restart` resumes
+  it with the human's decision so the tool books the dish.
 - **Streaming through a flow** — drive `flow.stream(...)`, emit chunks via
   `sendChunk`, and assert chunks arrive through the flow plus the final output.
 - **`echoModel`** — a zero-config model that echoes the whole assembled request
@@ -34,8 +46,8 @@ mock under that name and the app code runs unchanged.
 - **Inspection** — `model.lastRequest` / `lastRequestMessage` (a genkit
   `Message`, so `.text` / `.media` work like on a response) / `lastRequestText`
   (the full assembled conversation as a string — works on *any* mock, including
-  structured-output paths where `echoModel` can't be used) / `requests` /
-  `requestCount`.
+  structured-output paths where `echoModel` can't be used) / `toolResponses` /
+  `requests` / `requestCount`.
 
 `genkit/testing` is runner-agnostic. The same patterns are shown twice:
 `tests/menu_test.ts` under Node's built-in `node:test`, and

js/testapps/testing-sample/src/menu.ts

@@ -14,7 +14,11 @@
  * limitations under the License.
  */
 
-import { genkit, z } from 'genkit';
+// `genkit/beta` is a superset of `genkit` — used here because the
+// human-in-the-loop `confirmBooking` tool relies on interrupts, a beta feature.
+// Everything else in this app works identically on the stable `genkit` entry.
+import { genkit } from 'genkit/beta';
+import { z } from 'genkit';
 
 /** What we ask the model to produce: a structured recommendation. */
 export const RecommendationSchema = z.object({
@@ -134,9 +138,29 @@ export function createMenuApp() {
     }
   );
 
+  /**
+   * A human-in-the-loop tool: booking a dish needs explicit confirmation, so the
+   * tool `interrupt()`s on first run to hand control back to the caller, and
+   * completes once generation is resumed with the human's answer. Tests drive
+   * the pause -> resume round-trip with `mockModel` (see menu_test.ts).
+   */
+  const confirmBooking = ai.defineTool(
+    {
+      name: 'confirmBooking',
+      description: 'Confirm with the user before booking a dish.',
+      inputSchema: z.object({ dish: z.string() }),
+      outputSchema: z.string(),
+    },
+    async ({ dish }, { interrupt, resumed }) => {
+      if (resumed) return `Booked: ${dish}.`;
+      return interrupt({ dish });
+    }
+  );
+
   return {
     ai,
     dailySpecial,
+    confirmBooking,
     recommendPrompt,
     recommendDish,
     streamRecommendation,
@@ -150,6 +174,7 @@ export function createMenuApp() {
 export const {
   ai,
   dailySpecial,
+  confirmBooking,
   recommendPrompt,
   recommendDish,
   streamRecommendation,

js/testapps/testing-sample/tests/menu.vitest.test.ts

@@ -24,11 +24,12 @@ import { createMenuApp } from '../src/menu.js';
 // unchanged.
 type App = ReturnType<typeof createMenuApp>;
 let ai: App['ai'];
+let confirmBooking: App['confirmBooking'];
 let recommendDish: App['recommendDish'];
 let recommendPrompt: App['recommendPrompt'];
 let streamRecommendation: App['streamRecommendation'];
 beforeEach(() => {
-  ({ ai, recommendDish, recommendPrompt, streamRecommendation } =
+  ({ ai, confirmBooking, recommendDish, recommendPrompt, streamRecommendation } =
     createMenuApp());
 });
 
@@ -105,6 +106,50 @@ describe('recommendDish flow — tool round-trip (vitest)', () => {
 
     expect(out.dish).toBe('Mushroom risotto');
     expect(model.requestCount).toBe(2);
+    expect(model.toolResponses[0]?.name).toBe('dailySpecial');
+  });
+});
+
+describe('human-in-the-loop with interrupts (vitest)', () => {
+  it('pauses on confirmBooking, then resumes to complete the booking', async () => {
+    const model = mockModel(ai, {
+      name: 'menuModel',
+      info: { supports: { tools: true } },
+      // Queued responses: request the interrupting tool, then answer.
+      respond: [
+        {
+          toolRequests: [
+            { name: 'confirmBooking', input: { dish: 'Mushroom risotto' } },
+          ],
+        },
+        { text: 'Enjoy your meal!' },
+      ],
+    });
+
+    const paused = await ai.generate({
+      model,
+      prompt: 'Book the risotto.',
+      tools: [confirmBooking],
+    });
+    expect(paused.interrupts.length).toBe(1);
+    expect(paused.interrupts[0].toolRequest.name).toBe('confirmBooking');
+
+    const done = await ai.generate({
+      model,
+      messages: paused.messages,
+      tools: [confirmBooking],
+      resume: {
+        restart: confirmBooking.restart(paused.interrupts[0], {
+          confirmed: true,
+        }),
+      },
+    });
+
+    expect(done.text).toBe('Enjoy your meal!');
+    expect(model.requestCount).toBe(2);
+    expect(String(model.toolResponses[0]?.output)).toMatch(
+      /Booked: Mushroom risotto/
+    );
   });
 });
 

js/testapps/testing-sample/tests/menu_test.ts

@@ -26,11 +26,12 @@ import { createMenuApp } from '../src/menu.js';
 // shared registry.
 type App = ReturnType<typeof createMenuApp>;
 let ai: App['ai'];
+let confirmBooking: App['confirmBooking'];
 let recommendDish: App['recommendDish'];
 let recommendPrompt: App['recommendPrompt'];
 let streamRecommendation: App['streamRecommendation'];
 beforeEach(() => {
-  ({ ai, recommendDish, recommendPrompt, streamRecommendation } =
+  ({ ai, confirmBooking, recommendDish, recommendPrompt, streamRecommendation } =
     createMenuApp());
 });
 
@@ -209,3 +210,95 @@ describe('streamRecommendation flow — streaming through the flow', () => {
     assert.equal(await output, 'Try the risotto.');
   });
 });
+
+describe('scripting responses with a queue', () => {
+  it('scripts a two-turn tool interaction with an array of responses', async () => {
+    const model = mockModel(ai, {
+      name: 'menuModel',
+      info: { supports: { tools: true } },
+      // Turn 1: ask for the special. Turn 2: return the recommendation. The
+      // array is consumed one item per call, so no branching callback is needed.
+      respond: [
+        {
+          toolRequests: [
+            { name: 'dailySpecial', input: { restaurant: 'Lumen' } },
+          ],
+        },
+        {
+          text: JSON.stringify({
+            dish: 'Mushroom risotto',
+            reason: "It's the daily special.",
+            priceUSD: 22,
+          }),
+        },
+      ],
+    });
+
+    const out = await recommendDish({
+      restaurant: 'Lumen',
+      mood: 'curious',
+      budgetUSD: 40,
+    });
+
+    assert.equal(out.dish, 'Mushroom risotto');
+    assert.equal(model.requestCount, 2);
+    assert.equal(model.toolResponses[0]?.name, 'dailySpecial');
+  });
+});
+
+describe('model failure handling', () => {
+  it('surfaces a model error injected via a queued Error', async () => {
+    // A queued Error is thrown when reached — here on the very first call — so
+    // you can test how a flow behaves when the model fails.
+    mockModel(ai, {
+      name: 'menuModel',
+      respond: [new Error('model overloaded')],
+    });
+
+    await assert.rejects(
+      recommendDish({ restaurant: 'Lumen', mood: 'cozy', budgetUSD: 30 }),
+      /model overloaded/
+    );
+  });
+});
+
+describe('human-in-the-loop with interrupts', () => {
+  it('pauses on confirmBooking, then resumes to complete the booking', async () => {
+    const model = mockModel(ai, {
+      name: 'menuModel',
+      info: { supports: { tools: true } },
+      respond: [
+        {
+          toolRequests: [
+            { name: 'confirmBooking', input: { dish: 'Mushroom risotto' } },
+          ],
+        },
+        { text: 'Enjoy your meal!' },
+      ],
+    });
+
+    // First pass: the tool interrupts, so generation pauses awaiting the human.
+    const paused = await ai.generate({
+      model,
+      prompt: 'Book the risotto.',
+      tools: [confirmBooking],
+    });
+    assert.equal(paused.interrupts.length, 1);
+    assert.equal(paused.interrupts[0].toolRequest.name, 'confirmBooking');
+
+    // The human confirms; `restart` re-runs the tool with the decision (so its
+    // `resumed` branch books the dish), then the model finishes.
+    const done = await ai.generate({
+      model,
+      messages: paused.messages,
+      tools: [confirmBooking],
+      resume: {
+        restart: confirmBooking.restart(paused.interrupts[0], { confirmed: true }),
+      },
+    });
+
+    assert.equal(done.text, 'Enjoy your meal!');
+    assert.equal(model.requestCount, 2);
+    assert.match(String(model.toolResponses[0]?.output), /Booked: Mushroom risotto/);
+  });
+});