@botiverse/porthole 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/annotate/types.d.ts +42 -4
  2. package/dist/annotate/types.js +6 -1
  3. package/dist/annotate/validate.d.ts +16 -1
  4. package/dist/annotate/validate.js +33 -3
  5. package/dist/bridge/bridge.js +1 -51
  6. package/dist/bridge/unseen.d.ts +18 -0
  7. package/dist/bridge/unseen.js +71 -0
  8. package/dist/check/page-source.js +1 -1
  9. package/dist/conformance/behavior.js +107 -68
  10. package/dist/conformance/clipboard.js +16 -14
  11. package/dist/conformance/harness-source.js +1 -1
  12. package/dist/conformance/limits.js +117 -64
  13. package/dist/conformance/probes.js +66 -49
  14. package/dist/conformance/served.js +66 -63
  15. package/dist/host/create-host.js +75 -3
  16. package/dist/platform/types.d.ts +12 -1
  17. package/dist/platform/web.js +8 -0
  18. package/dist/react/frame.d.ts +6 -2
  19. package/dist/shell/annotate.d.ts +10 -3
  20. package/dist/shell/annotate.js +610 -39
  21. package/docs/ADOPTING.md +76 -0
  22. package/docs/ARCHITECTURE.md +2 -1
  23. package/docs/DECISIONS.md +516 -1
  24. package/docs/DESIGN.md +178 -20
  25. package/docs/THREAT_MODEL.md +92 -9
  26. package/package.json +1 -1
  27. package/src/annotate/types.ts +39 -5
  28. package/src/annotate/validate.ts +39 -3
  29. package/src/bridge/bridge.ts +1 -60
  30. package/src/bridge/unseen.ts +82 -0
  31. package/src/conformance/behavior.ts +221 -69
  32. package/src/conformance/clipboard.ts +44 -14
  33. package/src/conformance/limits.ts +169 -76
  34. package/src/conformance/probes.ts +97 -49
  35. package/src/conformance/served.ts +112 -63
  36. package/src/host/create-host.ts +75 -3
  37. package/src/platform/types.ts +9 -1
  38. package/src/platform/web.ts +10 -0
  39. package/src/react/frame.tsx +6 -2
  40. package/src/shell/annotate.ts +610 -39
@@ -1,6 +1,7 @@
1
1
  import { expect, type Frame } from "@playwright/test";
2
2
  import { presets } from "../presets/presets.ts";
3
3
  import { resolveTheme } from "../theme/variables.ts";
4
+ import type { ConfirmRequest } from "../bridge/types.ts";
4
5
  import type { LaunchedDisplay } from "./index.ts";
5
6
  import { inline, js, type Probe, type ProbeContext } from "./kit.ts";
6
7
  import { settle } from "./oracles.ts";
@@ -23,10 +24,16 @@ const variable = (frame: Frame, name: string): Promise<string> =>
23
24
  /** Polls the frame element's height until it is `px` (± 1). */
24
25
  async function expectHeight(display: LaunchedDisplay, px: number, message: string): Promise<void> {
25
26
  await expect
26
- .poll(async () => Math.round((await display.box()).height), { message, timeout: 5_000 })
27
+ .poll(async () => Math.round((await display.box()).height), {
28
+ message: `probe: ${message}`,
29
+ timeout: 5_000,
30
+ })
27
31
  .toBeGreaterThanOrEqual(px - 1);
28
32
  await expect
29
- .poll(async () => Math.round((await display.box()).height), { message, timeout: 5_000 })
33
+ .poll(async () => Math.round((await display.box()).height), {
34
+ message: `probe: ${message}`,
35
+ timeout: 5_000,
36
+ })
30
37
  .toBeLessThanOrEqual(px + 1);
31
38
  }
32
39
 
@@ -64,15 +71,41 @@ async function clickAfterLapse(
64
71
  await context.page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
65
72
  }
66
73
 
67
- /** The attribute `name` of the frame's body, once set. */
68
- async function bodyData(display: LaunchedDisplay, name: string, timeout = 5_000): Promise<string> {
74
+ /**
75
+ * The attribute `name` of the frame's body, once set. Where it is a gate's answer to the content,
76
+ * `verdict` is the probe's: an answer that never comes (a call left waiting on a gate that should
77
+ * have refused it) fails the probe's verdict, not its setup (P096).
78
+ */
79
+ async function bodyData(
80
+ display: LaunchedDisplay,
81
+ name: string,
82
+ verdict?: string,
83
+ timeout = 5_000,
84
+ ): Promise<string> {
69
85
  const frame = await display.frame();
70
86
  await expect
71
- .poll(() => frame.locator("body").getAttribute(`data-${name}`), { timeout })
87
+ .poll(() => frame.locator("body").getAttribute(`data-${name}`), {
88
+ timeout,
89
+ ...(verdict === undefined ? {} : { message: verdict }),
90
+ })
72
91
  .not.toBeNull();
73
92
  return (await frame.locator("body").getAttribute(`data-${name}`)) ?? "";
74
93
  }
75
94
 
95
+ /**
96
+ * The next confirmation, answered, where the gate must ask one now: none coming
97
+ * (`answerNextConfirmation` rejects) is the probe's verdict failing, `verdict` (P096).
98
+ */
99
+ async function answered(
100
+ display: LaunchedDisplay,
101
+ accept: boolean,
102
+ verdict: string,
103
+ ): Promise<ConfirmRequest> {
104
+ const request = await display.answerNextConfirmation(accept).catch(() => undefined);
105
+ expect(request, verdict).toBeDefined();
106
+ return request!;
107
+ }
108
+
76
109
  /** A model context update (P100): what the view says the person is looking at. */
77
110
  const CONTEXT_UPDATE = {
78
111
  content: [{ type: "text", text: "The person is looking at March's signups." }],
@@ -128,7 +161,7 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
128
161
  1;
129
162
  });
130
163
  await display.setContent(step2, { partial: true });
131
- await expect(frame.locator("#r2")).toHaveText("two");
164
+ await expect(frame.locator("#r2"), "probe: the next draft is drawn").toHaveText("two");
132
165
  expect(
133
166
  await read(frame, () => ({
134
167
  kept: (document.getElementById("img") as HTMLElement & { portholeMark?: number })
@@ -138,17 +171,29 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
138
171
  handler: document.getElementById("b")?.getAttribute("onclick") ?? null,
139
172
  scripts: document.querySelectorAll("#porthole-root script").length,
140
173
  })),
174
+ "probe: a draft keeps what was drawn and is inert",
141
175
  ).toEqual({ kept: 1, ran: null, href: null, handler: null, scripts: 0 });
142
176
 
143
177
  await display.setContent(whole);
144
- await expect(frame.locator("body")).toHaveAttribute("data-ran", "1");
145
- expect(await frame.locator("#b").getAttribute("onclick")).not.toBeNull();
178
+ await expect(frame.locator("body"), "probe: the whole ran once").toHaveAttribute(
179
+ "data-ran",
180
+ "1",
181
+ );
182
+ expect(
183
+ await frame.locator("#b").getAttribute("onclick"),
184
+ "probe: the whole keeps its handlers",
185
+ ).not.toBeNull();
146
186
  // The whole goes once: sending it again, or a late draft, changes nothing.
147
187
  await display.setContent(whole);
148
188
  await display.setContent(head, { partial: true });
149
189
  await settle(400);
150
- await expect(frame.locator("body")).toHaveAttribute("data-ran", "1");
151
- await expect(frame.locator("#r2")).toHaveText("two");
190
+ await expect(frame.locator("body"), "probe: the whole ran only once").toHaveAttribute(
191
+ "data-ran",
192
+ "1",
193
+ );
194
+ await expect(frame.locator("#r2"), "probe: a late draft changed what was drawn").toHaveText(
195
+ "two",
196
+ );
152
197
  },
153
198
  },
154
199
 
@@ -174,7 +219,7 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
174
219
  frame,
175
220
  () => document.documentElement.scrollHeight > document.documentElement.clientHeight,
176
221
  ),
177
- "past its height, the content scrolls inside",
222
+ "probe: past its height, the content scrolls inside",
178
223
  ).toBe(true);
179
224
  await frame.evaluate(() => (window as unknown as { setBox(px: number): void }).setBox(5));
180
225
  await expectHeight(display, 30, "shrinks to minHeightPx");
@@ -183,9 +228,11 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
183
228
  );
184
229
  // The first size is the content's: an empty shell reports none (it would make the host
185
230
  // forget the height it remembered, and the frame jump).
186
- expect(sizes[0]).toBe(150);
187
- expect(sizes).toEqual(expect.arrayContaining([150, 300, 400, 30]));
188
- expect(Math.max(...sizes)).toBe(400);
231
+ expect(sizes[0], "probe: the first size reported is the content's").toBe(150);
232
+ expect(sizes, "probe: each size was reported").toEqual(
233
+ expect.arrayContaining([150, 300, 400, 30]),
234
+ );
235
+ expect(Math.max(...sizes), "probe: no size past maxHeightPx was reported").toBe(400);
189
236
  },
190
237
  },
191
238
  {
@@ -200,11 +247,13 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
200
247
  await expectHeight(display, 500, "follows the page");
201
248
  const frame = await display.frame();
202
249
  await expect(frame.locator("#page")).toHaveText("page");
203
- await expect(frame.locator("body"), "the page's own load event fires").toHaveAttribute(
250
+ await expect(frame.locator("body"), "probe: the page's own load event fires").toHaveAttribute(
204
251
  "data-loaded",
205
252
  "1",
206
253
  );
207
- expect(await read(frame, () => document.title)).toBe("Report");
254
+ expect(await read(frame, () => document.title), "probe: the page keeps its own title").toBe(
255
+ "Report",
256
+ );
208
257
  },
209
258
  },
210
259
 
@@ -225,19 +274,27 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
225
274
  });
226
275
  const frame = await display.frame();
227
276
  await expect(frame.locator("p")).toHaveText("themed");
228
- expect(await variable(frame, "--color-text-primary")).toBe(light["--color-text-primary"]);
277
+ expect(
278
+ await variable(frame, "--color-text-primary"),
279
+ "probe: the content takes the light theme",
280
+ ).toBe(light["--color-text-primary"]);
229
281
  const flips = () => read(frame, () => (window as unknown as { flips: string[] }).flips);
230
282
  // Mounting, and a host telling it the scheme it already has, are no flip: no event (#3).
231
283
  await settle(400);
232
- expect(await flips(), "no theme event at mount").toEqual([]);
284
+ expect(await flips(), "probe: no theme event at mount").toEqual([]);
233
285
  await display.setTheme("light");
234
286
  await settle(400);
235
- expect(await flips(), "no theme event for the scheme it has").toEqual([]);
287
+ expect(await flips(), "probe: no theme event for the scheme it has").toEqual([]);
236
288
  await display.setTheme("dark");
237
289
  await expect
238
- .poll(() => variable(frame, "--color-text-primary"))
290
+ .poll(() => variable(frame, "--color-text-primary"), {
291
+ message: "probe: the content is re-themed dark",
292
+ })
239
293
  .toBe(dark["--color-text-primary"]);
240
- expect(await variable(frame, "--color-chart-1")).toBe(dark["--color-chart-1"]);
294
+ expect(
295
+ await variable(frame, "--color-chart-1"),
296
+ "probe: the chart colors are re-themed dark",
297
+ ).toBe(dark["--color-chart-1"]);
241
298
  expect(
242
299
  await read(frame, () => ({
243
300
  kept: (window as unknown as { kept?: string }).kept,
@@ -245,19 +302,23 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
245
302
  theme: document.documentElement.dataset.theme,
246
303
  scheme: document.documentElement.style.colorScheme,
247
304
  })),
305
+ "probe: the running content is re-themed in place and told once",
248
306
  ).toEqual({ kept: "yes", flips: ["dark"], theme: "dark", scheme: "dark" });
249
307
  const element = await frame.frameElement();
250
- expect(await element.evaluate((node) => (node as HTMLElement).style.colorScheme)).toBe(
251
- "dark",
252
- );
308
+ expect(
309
+ await element.evaluate((node) => (node as HTMLElement).style.colorScheme),
310
+ "probe: the frame element takes the dark scheme",
311
+ ).toBe("dark");
253
312
  await display.setTheme("light");
254
313
  await expect
255
- .poll(() => variable(frame, "--color-text-primary"))
314
+ .poll(() => variable(frame, "--color-text-primary"), {
315
+ message: "probe: the content is re-themed light",
316
+ })
256
317
  .toBe(light["--color-text-primary"]);
257
- expect(await read(frame, () => (window as unknown as { flips: string[] }).flips)).toEqual([
258
- "dark",
259
- "light",
260
- ]);
318
+ expect(
319
+ await read(frame, () => (window as unknown as { flips: string[] }).flips),
320
+ "probe: each flip is told once",
321
+ ).toEqual(["dark", "light"]);
261
322
  },
262
323
  },
263
324
  {
@@ -280,9 +341,19 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
280
341
  });
281
342
  const frame = await display.frame();
282
343
  await expect(frame.locator("p")).toHaveText("live");
283
- await expect.poll(() => variable(frame, "--color-text-primary")).toBe("rgb(1, 2, 3)");
284
- expect(await variable(frame, "--color-chart-1")).toBe("rgb(4, 5, 6)");
285
- expect(await variable(frame, "--not-declared")).toBe("");
344
+ await expect
345
+ .poll(() => variable(frame, "--color-text-primary"), {
346
+ message: "probe: the host's spec value reached the frame",
347
+ })
348
+ .toBe("rgb(1, 2, 3)");
349
+ expect(
350
+ await variable(frame, "--color-chart-1"),
351
+ "probe: the host's Porthole value reached the frame",
352
+ ).toBe("rgb(4, 5, 6)");
353
+ expect(
354
+ await variable(frame, "--not-declared"),
355
+ "probe: an undeclared host value reached the frame",
356
+ ).toBe("");
286
357
  },
287
358
  },
288
359
  {
@@ -307,14 +378,17 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
307
378
  input: of("i").borderTopLeftRadius,
308
379
  };
309
380
  });
310
- expect(styles).toEqual({
381
+ expect(
382
+ styles,
383
+ "probe: native controls take the theme, and content's CSS overrides it",
384
+ ).toEqual({
311
385
  radius: resolveTheme(config.theme, "light")["--border-radius-md"],
312
386
  font: true,
313
387
  height: expect.any(Number),
314
388
  overridden: "0px",
315
389
  input: resolveTheme(config.theme, "light")["--border-radius-md"],
316
390
  });
317
- expect(styles.height, "a control is tall enough to tap").toBeGreaterThanOrEqual(44);
391
+ expect(styles.height, "probe: a control is tall enough to tap").toBeGreaterThanOrEqual(44);
318
392
  },
319
393
  },
320
394
 
@@ -344,7 +418,10 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
344
418
  content: page("", "plain"),
345
419
  });
346
420
  // An author's own page, declaring nothing: shown as styled, in light; the variables are there.
347
- expect(await scheme(plain, "plain")).toEqual({
421
+ expect(
422
+ await scheme(plain, "plain"),
423
+ "probe: a page declaring nothing stays as styled",
424
+ ).toEqual({
348
425
  scheme: "normal",
349
426
  theme: null,
350
427
  variable: true,
@@ -352,7 +429,10 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
352
429
  await plain.setTheme("light");
353
430
  await plain.setTheme("dark");
354
431
  await settle(300);
355
- expect(await scheme(plain, "plain")).toEqual({
432
+ expect(
433
+ await scheme(plain, "plain"),
434
+ "probe: a page declaring nothing stays as styled after a flip",
435
+ ).toEqual({
356
436
  scheme: "normal",
357
437
  theme: null,
358
438
  variable: true,
@@ -362,14 +442,25 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
362
442
  scheme: "dark",
363
443
  content: page('<meta name="color-scheme" content="light dark">', "declared"),
364
444
  });
365
- await expect.poll(async () => (await scheme(declared, "declared")).theme).toBe("dark");
366
- expect((await scheme(declared, "declared")).scheme).toBe("dark");
445
+ await expect
446
+ .poll(async () => (await scheme(declared, "declared")).theme, {
447
+ message: "probe: a page declaring its schemes takes the person's",
448
+ })
449
+ .toBe("dark");
450
+ expect(
451
+ (await scheme(declared, "declared")).scheme,
452
+ "probe: a page declaring its schemes takes the person's color scheme",
453
+ ).toBe("dark");
367
454
  const always = await context.launch({
368
455
  config: presets.artifact({ theme: { documents: "always" } }),
369
456
  scheme: "dark",
370
457
  content: page("", "always"),
371
458
  });
372
- await expect.poll(async () => (await scheme(always, "always")).theme).toBe("dark");
459
+ await expect
460
+ .poll(async () => (await scheme(always, "always")).theme, {
461
+ message: "probe: a page the host always themes takes the person's scheme",
462
+ })
463
+ .toBe("dark");
373
464
  },
374
465
  },
375
466
 
@@ -381,10 +472,13 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
381
472
  async run(context) {
382
473
  const display = await context.launch({ config: prompts(), content: PROMPT_CONTENT });
383
474
  expect(
384
- await bodyData(display, "onload"),
385
- "a call made on load is refused by the shell",
475
+ await bodyData(display, "onload", "probe: a call made on load is refused by the shell"),
476
+ "probe: a call made on load is refused by the shell",
386
477
  ).toContain("needs a click");
387
- expect(await display.calls()).toEqual([]);
478
+ expect(
479
+ await display.calls(),
480
+ "probe: a call made on load reached the host's handler",
481
+ ).toEqual([]);
388
482
 
389
483
  // The host's own check needs the frame's click to reach the host page (activation
390
484
  // propagates to ancestors): measured with raw input, after the harness's activation lapsed.
@@ -395,14 +489,27 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
395
489
  `${context.engine}: a click in the frame ${refused.includes("sendPrompt:no-user-activation") ? "does not reach" : "reaches"} the host page's user activation`,
396
490
  );
397
491
  expect(refused, "the frame's click didn't count as a gesture on the host page").toEqual([]);
398
- const declined = await display.answerNextConfirmation(false);
399
- expect(declined).toMatchObject({
492
+ const declined = await answered(
493
+ display,
494
+ false,
495
+ "probe: the person was asked about the prompt",
496
+ );
497
+ expect(declined, "probe: the person was asked about the whole prompt").toMatchObject({
400
498
  capability: "sendPrompt",
401
499
  args: { text: "Explain why signups doubled in March" },
402
500
  display: { title: "Probe" },
403
501
  });
404
- expect(await bodyData(display, "result")).toBe("false");
405
- expect(await display.calls(), "a declined prompt reached the host's handler").toEqual([]);
502
+ expect(
503
+ await bodyData(
504
+ display,
505
+ "result",
506
+ "probe: the content is told a declined prompt wasn't sent",
507
+ ),
508
+ "probe: the content is told a declined prompt wasn't sent",
509
+ ).toBe("false");
510
+ expect(await display.calls(), "probe: a declined prompt reached the host's handler").toEqual(
511
+ [],
512
+ );
406
513
 
407
514
  await click(display, "#ask");
408
515
  await display.answerNextConfirmation(true);
@@ -429,9 +536,16 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
429
536
  });
430
537
  // Nothing is evaluated in the page until the message has been answered.
431
538
  await context.page.waitForTimeout(ACTIVATION_LAPSE_MS + 1_500);
432
- expect(await bodyData(display, "answer")).toBe(JSON.stringify({ isError: true }));
433
- expect(await display.calls()).toEqual([]);
434
- expect(await refusals(display)).toEqual(["sendPrompt:no-user-activation"]);
539
+ expect(
540
+ await bodyData(display, "answer", "probe: a raw ui/message without a click is refused"),
541
+ "probe: a raw ui/message without a click is refused",
542
+ ).toBe(JSON.stringify({ isError: true }));
543
+ expect(await display.calls(), "probe: a raw ui/message reached the host's handler").toEqual(
544
+ [],
545
+ );
546
+ expect(await refusals(display), "probe: the host refused it for no user activation").toEqual([
547
+ "sendPrompt:no-user-activation",
548
+ ]);
435
549
  },
436
550
  },
437
551
  {
@@ -449,8 +563,8 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
449
563
  </script>`,
450
564
  });
451
565
  await click(display, "#web");
452
- const asked = await display.answerNextConfirmation(true);
453
- expect(asked).toMatchObject({
566
+ const asked = await answered(display, true, "probe: the person was asked about the link");
567
+ expect(asked, "probe: the person was asked about the link").toMatchObject({
454
568
  capability: "openLink",
455
569
  args: { url: "https://example.com/report?q=1" },
456
570
  });
@@ -459,11 +573,23 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
459
573
  .toEqual([{ capability: "openLink", args: { url: "https://example.com/report?q=1" } }]);
460
574
  await click(display, "#js");
461
575
  await click(display, "#raw");
462
- expect(await bodyData(display, "raw")).toBe("false");
576
+ expect(
577
+ await bodyData(display, "raw", "probe: openLink of a javascript: URL is refused"),
578
+ "probe: openLink of a javascript: URL is refused",
579
+ ).toBe("false");
463
580
  await settle(300);
464
- expect(await (await display.frame()).locator("body").getAttribute("data-ran")).toBeNull();
465
- expect(await refusals(display)).toContain("openLink:invalid");
466
- expect(await display.calls()).toHaveLength(1);
581
+ expect(
582
+ await (await display.frame()).locator("body").getAttribute("data-ran"),
583
+ "probe: a javascript: link ran",
584
+ ).toBeNull();
585
+ expect(
586
+ await refusals(display),
587
+ "probe: the host refused the javascript: URL as invalid",
588
+ ).toContain("openLink:invalid");
589
+ expect(
590
+ await display.calls(),
591
+ "probe: a non-http(s) link reached the host's handler",
592
+ ).toHaveLength(1);
467
593
  },
468
594
  },
469
595
  {
@@ -477,16 +603,30 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
477
603
  });
478
604
  for (let index = 0; index < 2; index += 1) {
479
605
  await click(display, "#ask");
480
- await display.answerNextConfirmation(false);
481
- expect(await bodyData(display, "result")).toBe("false");
606
+ await answered(display, false, "probe: the display asked before it muted");
607
+ expect(
608
+ await bodyData(
609
+ display,
610
+ "result",
611
+ "probe: the content is told a declined prompt wasn't sent",
612
+ ),
613
+ "probe: the content is told a declined prompt wasn't sent",
614
+ ).toBe("false");
482
615
  }
483
616
  await expect
484
- .poll(async () => (await display.events()).some((event) => event.type === "muted"))
617
+ .poll(async () => (await display.events()).some((event) => event.type === "muted"), {
618
+ message: "probe: the display muted after the declines",
619
+ })
485
620
  .toBe(true);
486
621
  await click(display, "#ask");
487
- expect(await bodyData(display, "result")).toBe("false");
488
- expect(await refusals(display)).toContain("sendPrompt:muted");
489
- expect(await display.calls()).toEqual([]);
622
+ expect(
623
+ await bodyData(display, "result", "probe: a muted display's prompt is refused"),
624
+ "probe: a muted display's prompt is refused",
625
+ ).toBe("false");
626
+ expect(await refusals(display), "probe: the prompt was refused as muted").toContain(
627
+ "sendPrompt:muted",
628
+ );
629
+ expect(await display.calls(), "probe: a prompt reached the host's handler").toEqual([]);
490
630
  },
491
631
  },
492
632
  {
@@ -511,9 +651,17 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
511
651
  "this host always has a confirm function (a default dialog), so a display without one can't be shown; it asked the person instead",
512
652
  );
513
653
  }
514
- expect(await bodyData(display, "result")).toBe("false");
515
- expect(await refusals(display)).toContain("sendPrompt:no-confirm");
516
- expect(await display.calls()).toEqual([]);
654
+ expect(
655
+ await bodyData(display, "result", "probe: a prompt with no one to confirm it is refused"),
656
+ "probe: a prompt with no one to confirm it is refused",
657
+ ).toBe("false");
658
+ expect(await refusals(display), "probe: the prompt was refused for no confirm").toContain(
659
+ "sendPrompt:no-confirm",
660
+ );
661
+ expect(
662
+ await display.calls(),
663
+ "probe: an unconfirmed prompt reached the host's handler",
664
+ ).toEqual([]);
517
665
  },
518
666
  },
519
667
  {
@@ -532,8 +680,8 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
532
680
  }
533
681
  expect(await bodyData(display, "answer")).toBe("{}");
534
682
  const shown = await said();
535
- expect(shown, "the update reached the model unseen").toHaveLength(1);
536
- expect(shown[0]).toMatchObject({
683
+ expect(shown, "probe: the update reached the model unseen").toHaveLength(1);
684
+ expect(shown[0], "probe: the person was shown the whole update").toMatchObject({
537
685
  capability: "setModelContext",
538
686
  args: CONTEXT_UPDATE,
539
687
  display: { title: "Probe" },
@@ -549,9 +697,13 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
549
697
  "this host always has a show function (a default surface), so a display without one can't be shown; it showed the person instead",
550
698
  );
551
699
  }
552
- expect(answer.code, "an update nobody could see was taken").toBe("not_allowed");
553
- expect(await refusals(unseen)).toContain("setModelContext:no-show");
554
- expect(await unseen.calls()).toEqual([]);
700
+ expect(answer.code, "probe: an update nobody could see was taken").toBe("not_allowed");
701
+ expect(await refusals(unseen), "probe: the update was refused for no show").toContain(
702
+ "setModelContext:no-show",
703
+ );
704
+ expect(await unseen.calls(), "probe: an unseen update reached the host's handler").toEqual(
705
+ [],
706
+ );
555
707
  },
556
708
  },
557
709
  ];
@@ -57,10 +57,14 @@ async function click(display: LaunchedDisplay, selector: string): Promise<void>
57
57
  await (await display.frame()).locator(selector).click();
58
58
  }
59
59
 
60
- async function bodyData(display: LaunchedDisplay, name: string): Promise<string> {
60
+ async function bodyData(display: LaunchedDisplay, name: string, verdict?: string): Promise<string> {
61
61
  const frame = await display.frame();
62
+ // A probe's verdict where the answer is a wall's (P096): none coming fails it, not its setup.
62
63
  await expect
63
- .poll(() => frame.locator("body").getAttribute(`data-${name}`), { timeout: 5_000 })
64
+ .poll(() => frame.locator("body").getAttribute(`data-${name}`), {
65
+ timeout: 5_000,
66
+ ...(verdict === undefined ? {} : { message: verdict }),
67
+ })
64
68
  .not.toBeNull();
65
69
  return (await frame.locator("body").getAttribute(`data-${name}`)) ?? "";
66
70
  }
@@ -92,10 +96,21 @@ export const CLIPBOARD_PROBES: readonly Probe[] = [
92
96
  });
93
97
  await seed(context.page, SEED);
94
98
  await click(display, "#go");
95
- expect(await bodyData(display, "text")).toMatch(/^refused/u);
96
- expect(await bodyData(display, "item")).toMatch(/^refused/u);
97
- expect(await bodyData(display, "read")).toMatch(/^refused/u);
98
- expect(await pasted(context.page), "the clipboard still holds the person's own").toBe(SEED);
99
+ expect(
100
+ await bodyData(display, "text", "probe: writeText is refused"),
101
+ "probe: writeText is refused",
102
+ ).toMatch(/^refused/u);
103
+ expect(
104
+ await bodyData(display, "item", "probe: write is refused"),
105
+ "probe: write is refused",
106
+ ).toMatch(/^refused/u);
107
+ expect(
108
+ await bodyData(display, "read", "probe: readText is refused"),
109
+ "probe: readText is refused",
110
+ ).toMatch(/^refused/u);
111
+ expect(await pasted(context.page), "probe: the clipboard still holds the person's own").toBe(
112
+ SEED,
113
+ );
99
114
  },
100
115
  },
101
116
  {
@@ -125,8 +140,13 @@ export const CLIPBOARD_PROBES: readonly Probe[] = [
125
140
  });
126
141
  await seed(context.page, SEED);
127
142
  await click(display, "#go");
128
- expect(await bodyData(display, "copied")).not.toContain("true");
129
- expect(await pasted(context.page), "the clipboard still holds the person's own").toBe(SEED);
143
+ expect(
144
+ await bodyData(display, "copied", "probe: execCommand copied or cut"),
145
+ "probe: execCommand copied or cut",
146
+ ).not.toContain("true");
147
+ expect(await pasted(context.page), "probe: the clipboard still holds the person's own").toBe(
148
+ SEED,
149
+ );
130
150
  },
131
151
  },
132
152
  {
@@ -156,8 +176,14 @@ export const CLIPBOARD_PROBES: readonly Probe[] = [
156
176
  await context.page.keyboard.press("ControlOrMeta+C");
157
177
  await settle(200);
158
178
  // The positive control: the person's own copy works, and copies what they selected.
159
- expect((await pasted(context.page)).trim()).toBe("porthole-selected-text");
160
- expect(await frame.locator("body").getAttribute("data-ran")).toBeNull();
179
+ expect(
180
+ (await pasted(context.page)).trim(),
181
+ "probe: the clipboard holds what the person selected",
182
+ ).toBe("porthole-selected-text");
183
+ expect(
184
+ await frame.locator("body").getAttribute("data-ran"),
185
+ "probe: a copy listener of the content's ran",
186
+ ).toBeNull();
161
187
  },
162
188
  },
163
189
  {
@@ -176,12 +202,16 @@ export const CLIPBOARD_PROBES: readonly Probe[] = [
176
202
  copyText("copied on load").then(${settled("onload")});
177
203
  </script>`,
178
204
  });
179
- expect(await bodyData(display, "onload")).toMatch(/^refused/u);
205
+ expect(
206
+ await bodyData(display, "onload", "probe: copyText without a click is refused"),
207
+ "probe: copyText without a click is refused",
208
+ ).toMatch(/^refused/u);
180
209
  await click(display, "#copy");
181
210
  expect(await bodyData(display, "result")).toBe("true");
182
- expect(await display.calls()).toEqual([
183
- { capability: "copyText", args: { text: "npm test -- --run" } },
184
- ]);
211
+ expect(
212
+ await display.calls(),
213
+ "probe: only the click's whole text reached the host's handler",
214
+ ).toEqual([{ capability: "copyText", args: { text: "npm test -- --run" } }]);
185
215
  },
186
216
  },
187
217
  ];