@botiverse/porthole 0.9.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.
@@ -16,13 +16,39 @@ async function click(display, selector) {
16
16
  /** What the content recorded in `window.r`, once `done` is set. */
17
17
  async function recorded(display, timeoutMs = 10_000) {
18
18
  const frame = await display.frame();
19
- await expect
20
- .poll(() => frame
21
- .evaluate(() => window.r?.done === true)
22
- .catch(() => false), { timeout: timeoutMs })
23
- .toBe(true);
19
+ // Each look is bounded: a frame a dialog holds (a print dialog, where the sandbox lets one open)
20
+ // answers no evaluation, and the probe fails by its assertion, not a test timeout (P096).
21
+ const done = () => Promise.race([
22
+ frame
23
+ .evaluate(() => window.r?.done === true)
24
+ .catch(() => false),
25
+ new Promise((resolve) => setTimeout(() => resolve(false), 1_000)),
26
+ ]);
27
+ await expect.poll(done, { timeout: timeoutMs }).toBe(true);
24
28
  return frame.evaluate(() => window.r);
25
29
  }
30
+ /**
31
+ * What the content recorded, or, where its document went before it could say, that as the probe's
32
+ * verdict (P096): started again (navigated away), or written over by `document.write` once the
33
+ * shell's lock is gone (its own element `own` gone): the escape itself, not a probe that failed to
34
+ * start.
35
+ */
36
+ async function replacedOrRecorded(display, own) {
37
+ try {
38
+ return await recorded(display);
39
+ }
40
+ catch (error) {
41
+ const restarts = (await display.events()).filter((event) => event.type === "navigated");
42
+ expect(restarts, "probe: the content's document was replaced before it reported").toEqual([]);
43
+ const frame = await display.frame().catch(() => undefined);
44
+ const kept = await frame
45
+ ?.locator(own)
46
+ .count()
47
+ .catch(() => undefined);
48
+ expect(kept, "probe: the content's document was written over before it reported").not.toBe(0);
49
+ throw error;
50
+ }
51
+ }
26
52
  /** Counts what the page shows the person beyond the frame: dialogs, downloads, new windows. */
27
53
  function watch(page) {
28
54
  const seen = { dialogs: [], downloads: [], windows: [] };
@@ -54,16 +80,24 @@ export const LIMIT_PROBES = [
54
80
  });
55
81
  const frame = await display.frame();
56
82
  await expect(frame.locator("#bar")).toBeAttached();
57
- await expect.poll(async () => Math.round((await display.box()).height)).toBe(400);
83
+ await expect
84
+ .poll(async () => Math.round((await display.box()).height), {
85
+ message: "probe: the frame is its box's height",
86
+ })
87
+ .toBe(400);
58
88
  await frame.evaluate(() => window.scrollTo(0, 600));
59
89
  const seen = await frame.evaluate(() => ({
60
90
  scrolled: window.scrollY,
61
91
  scrolls: document.documentElement.scrollHeight > window.innerHeight,
62
92
  barTop: Math.round(document.getElementById("bar").getBoundingClientRect().top),
63
93
  }));
64
- expect(seen).toEqual({ scrolled: 600, scrolls: true, barTop: 0 });
94
+ expect(seen, "probe: the page scrolls itself and position: fixed stays put").toEqual({
95
+ scrolled: 600,
96
+ scrolls: true,
97
+ barTop: 0,
98
+ });
65
99
  await settle(500);
66
- expect(Math.round((await display.box()).height), "it doesn't grow with its content").toBe(400);
100
+ expect(Math.round((await display.box()).height), "probe: it doesn't grow with its content").toBe(400);
67
101
  },
68
102
  },
69
103
  {
@@ -91,11 +125,11 @@ export const LIMIT_PROBES = [
91
125
  events: window.events,
92
126
  prefers: matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light",
93
127
  }));
94
- expect(seen.theme).toBeNull();
95
- expect(seen.text).toBe(light["--color-text-primary"]);
96
- expect(seen.events).toBe(0);
128
+ expect(seen.theme, "probe: the page took a theme").toBeNull();
129
+ expect(seen.text, "probe: the page stays light").toBe(light["--color-text-primary"]);
130
+ expect(seen.events, "probe: the page heard a theme change").toBe(0);
97
131
  const element = await frame.frameElement();
98
- expect(await element.evaluate((node) => node.style.colorScheme)).toBe("light");
132
+ expect(await element.evaluate((node) => node.style.colorScheme), "probe: the frame element stays light").toBe("light");
99
133
  context.measured(`prefers-color-scheme inside, the person on dark: ${seen.prefers}`);
100
134
  },
101
135
  },
@@ -110,12 +144,12 @@ export const LIMIT_PROBES = [
110
144
  content: thrower,
111
145
  });
112
146
  await expect
113
- .poll(async () => (await reported.errors()).some((each) => each.includes("porthole-thrown") || each.includes("Script error")))
147
+ .poll(async () => (await reported.errors()).some((each) => each.includes("porthole-thrown") || each.includes("Script error")), { message: "probe: what content threw reached the host" })
114
148
  .toBe(true);
115
149
  const quiet = await context.launch({ config: inline({ errors: "none" }), content: thrower });
116
150
  await expect((await quiet.frame()).locator("p")).toHaveText("x");
117
151
  await settle(800);
118
- expect(await quiet.errors()).toEqual([]);
152
+ expect(await quiet.errors(), "probe: an error reached a host that didn't declare reportError").toEqual([]);
119
153
  },
120
154
  },
121
155
  {
@@ -143,15 +177,17 @@ export const LIMIT_PROBES = [
143
177
  await context.launch({ config: presets.mcpApp(), content: "", document: page }),
144
178
  ]) {
145
179
  await expect
146
- .poll(async () => (await display.errors()).includes("porthole-after"))
180
+ .poll(async () => (await display.errors()).includes("porthole-after"), {
181
+ message: "probe: every logged error reached the host",
182
+ })
147
183
  .toBe(true);
148
184
  const errors = await display.errors();
149
- expect(errors).toContain('{"name":"porthole-cycle","self":"[Circular]"}');
150
- expect(errors).toContain('{"big":"5n"}');
185
+ expect(errors, "probe: a cycle is reported as bounded text").toContain('{"name":"porthole-cycle","self":"[Circular]"}');
186
+ expect(errors, "probe: a BigInt is reported as text").toContain('{"big":"5n"}');
151
187
  const graph = errors.find((each) => each.startsWith('{"a":{"a":'));
152
- expect(graph, "the shared graph, reported").toBeDefined();
153
- expect(graph).toContain('"b":"[Repeated]"');
154
- expect(graph?.length).toBeLessThanOrEqual(2_000);
188
+ expect(graph, "probe: the shared graph, reported").toBeDefined();
189
+ expect(graph, "probe: a shared graph's repeats are cut").toContain('"b":"[Repeated]"');
190
+ expect(graph?.length, "probe: the shared graph's report is bounded").toBeLessThanOrEqual(2_000);
155
191
  }
156
192
  },
157
193
  },
@@ -174,29 +210,29 @@ export const LIMIT_PROBES = [
174
210
  });
175
211
  const verdict = await context.result(display, 15_000);
176
212
  await settle();
177
- expect(verdict).toMatchObject({
213
+ expect(verdict, "probe: what the sandbox blocks fails quietly in the content").toMatchObject({
178
214
  fetch: "rejected TypeError",
179
215
  image: "failed",
180
216
  script: "undefined",
181
217
  after: "ran",
182
218
  });
183
- expect(canary.requests()).toEqual([]);
184
- expect(seen.dialogs).toEqual([]);
219
+ expect(canary.requests(), "probe: nothing reached the canary").toEqual([]);
220
+ expect(seen.dialogs, "probe: a dialog was shown").toEqual([]);
185
221
  // Where reportError is declared, each block is reported to the host (the manual says where
186
222
  // it goes, by \`errors\`, #4); where it isn't, nothing is.
187
223
  await expect
188
- .poll(async () => (await display.errors()).some((each) => each.startsWith("Blocked by the sandbox:")))
224
+ .poll(async () => (await display.errors()).some((each) => each.startsWith("Blocked by the sandbox:")), { message: "probe: the host heard of each block where reportError is declared" })
189
225
  .toBe(true);
190
226
  const quiet = await context.launch({
191
227
  config: inline({ errors: "none" }),
192
228
  content: attack(`
193
229
  r.fetch = await fetch(${js(`${c}/quiet`)}).then(() => "sent", (e) => "rejected " + e.name);`, `<img src="${c}/quiet.png">`),
194
230
  });
195
- expect(await context.result(quiet, 15_000)).toMatchObject({ fetch: "rejected TypeError" });
231
+ expect(await context.result(quiet, 15_000), "probe: the fetch rejects where reportError isn't declared").toMatchObject({ fetch: "rejected TypeError" });
196
232
  await settle();
197
- expect(await quiet.errors()).toEqual([]);
198
- expect(canary.requests()).toEqual([]);
199
- expect(seen.dialogs).toEqual([]);
233
+ expect(await quiet.errors(), "probe: a block reached a host that didn't declare reportError").toEqual([]);
234
+ expect(canary.requests(), "probe: nothing reached the canary").toEqual([]);
235
+ expect(seen.dialogs, "probe: a dialog was shown").toEqual([]);
200
236
  },
201
237
  },
202
238
  {
@@ -226,8 +262,11 @@ export const LIMIT_PROBES = [
226
262
  (verdict.styled !== "37px" && verdict.styleBlocked === true)) {
227
263
  context.inapplicable("the page's own CSP, which an opaque frame inherits, blocks data: images or inline styles (img-src, style-src): opaque content here can't inline its assets, whatever its config");
228
264
  }
229
- expect(verdict).toMatchObject({ inline: "loaded", styled: "37px" });
230
- expect(canary.requests()).toEqual([]);
265
+ expect(verdict, "probe: inline data: images and <style> CSS work").toMatchObject({
266
+ inline: "loaded",
267
+ styled: "37px",
268
+ });
269
+ expect(canary.requests(), "probe: nothing reached the canary").toEqual([]);
231
270
  },
232
271
  },
233
272
  {
@@ -251,9 +290,13 @@ export const LIMIT_PROBES = [
251
290
  });
252
291
  await click(display, "#go");
253
292
  const verdict = await recorded(display);
254
- expect(verdict).toMatchObject({ alert: "undefined", confirm: "false", prompt: "null" });
255
- expect(verdict.ms).toBeLessThan(1_000);
256
- expect(seen.dialogs).toEqual([]);
293
+ expect(verdict, "probe: alert, confirm and prompt return without asking").toMatchObject({
294
+ alert: "undefined",
295
+ confirm: "false",
296
+ prompt: "null",
297
+ });
298
+ expect(verdict.ms, "probe: a dialog held the content").toBeLessThan(1_000);
299
+ expect(seen.dialogs, "probe: a dialog was shown").toEqual([]);
257
300
  },
258
301
  },
259
302
  {
@@ -273,12 +316,20 @@ export const LIMIT_PROBES = [
273
316
  });
274
317
  </script>`,
275
318
  });
276
- await click(display, "#go");
319
+ // A print dialog holds the click that opened it, and the frame, where the sandbox lets one
320
+ // open (Firefox with allow-modals): the click is bounded (15 s, so a slow click on a busy
321
+ // runner isn't taken for a held one), and a click still held is this probe's verdict
322
+ // failing, not a test timeout (P096).
323
+ const held = await Promise.race([
324
+ click(display, "#go").then(() => false, () => false),
325
+ new Promise((resolve) => setTimeout(() => resolve(true), 15_000)),
326
+ ]);
327
+ expect(held, "probe: print() opened a dialog that held the click").toBe(false);
277
328
  const verdict = await recorded(display);
278
- expect(verdict.print).toBe("undefined");
279
- expect(verdict.beforeprint).toBeUndefined();
280
- expect(verdict.afterprint).toBeUndefined();
281
- expect(seen.dialogs).toEqual([]);
329
+ expect(verdict.print, "probe: print() returns nothing").toBe("undefined");
330
+ expect(verdict.beforeprint, "probe: a print started").toBeUndefined();
331
+ expect(verdict.afterprint, "probe: a print finished").toBeUndefined();
332
+ expect(seen.dialogs, "probe: a dialog was shown").toEqual([]);
282
333
  },
283
334
  },
284
335
  {
@@ -301,7 +352,7 @@ export const LIMIT_PROBES = [
301
352
  await click(display, selector);
302
353
  }
303
354
  await settle(1_000);
304
- expect(seen.downloads).toEqual([]);
355
+ expect(seen.downloads, "probe: a download started").toEqual([]);
305
356
  },
306
357
  },
307
358
  {
@@ -325,9 +376,9 @@ export const LIMIT_PROBES = [
325
376
  r: window.r,
326
377
  form: document.getElementById("form") !== null,
327
378
  }));
328
- expect(state.form, "the frame stayed on its content").toBe(true);
329
- expect(state.r.clicked).toBe(true);
330
- expect(canary.requests()).toEqual([]);
379
+ expect(state.form, "probe: the frame stayed on its content").toBe(true);
380
+ expect(state.r.clicked, "probe: a button's click handler runs").toBe(true);
381
+ expect(canary.requests(), "probe: the form submitted to the canary").toEqual([]);
331
382
  context.measured(`submit event fired: ${JSON.stringify(state.r.submitEvent ?? 0)} time(s)`);
332
383
  },
333
384
  },
@@ -345,9 +396,9 @@ export const LIMIT_PROBES = [
345
396
  await click(display, selector);
346
397
  }
347
398
  await settle(800);
348
- await expect((await display.frame()).locator("#still")).toHaveText("still here");
349
- expect(seen.windows).toEqual([]);
350
- expect(await display.calls(), "nothing went to the host").toEqual([]);
399
+ await expect((await display.frame()).locator("#still"), "probe: the frame stayed on its content").toHaveText("still here");
400
+ expect(seen.windows, "probe: a window opened").toEqual([]);
401
+ expect(await display.calls(), "probe: nothing went to the host").toEqual([]);
351
402
  },
352
403
  },
353
404
  {
@@ -365,24 +416,26 @@ export const LIMIT_PROBES = [
365
416
  const closed = await context.launch({ config: inline(), content });
366
417
  await click(closed, "#open");
367
418
  const verdict = await recorded(closed);
368
- expect(["null", "throws"]).toContain(verdict.open);
419
+ expect(["null", "throws"], "probe: window.open opened a window").toContain(verdict.open);
369
420
  context.measured(`window.open: ${String(verdict.open)}`);
370
421
  await click(closed, "#blank");
371
422
  await settle(800);
372
- expect(seen.windows).toEqual([]);
423
+ expect(seen.windows, "probe: a window opened").toEqual([]);
373
424
  // With openLink declared, the link asks the app instead (the person says no here).
374
425
  const linked = await context.launch({
375
426
  config: inline({ capabilities: { openLink: {} } }),
376
427
  content,
377
428
  });
378
429
  await click(linked, "#blank");
379
- const asked = await linked.answerNextConfirmation(false);
380
- expect(asked).toMatchObject({
430
+ const asked = await linked.answerNextConfirmation(false).catch(() => undefined);
431
+ // A matcher on nothing says nothing of the message: none asked is said first (P096).
432
+ expect(asked, "probe: the link asked the app").toBeDefined();
433
+ expect(asked, "probe: the link asked the app").toMatchObject({
381
434
  capability: "openLink",
382
435
  args: { url: "https://example.com/report" },
383
436
  });
384
437
  await settle(500);
385
- expect(seen.windows).toEqual([]);
438
+ expect(seen.windows, "probe: a window opened after the person said no").toEqual([]);
386
439
  },
387
440
  },
388
441
  {
@@ -421,11 +474,11 @@ export const LIMIT_PROBES = [
421
474
  buffer: Buffer.from("file text"),
422
475
  });
423
476
  const verdict = await recorded(display);
424
- expect(String(verdict.media)).toMatch(/^(rejected|absent)/u);
425
- expect(String(verdict.location)).toMatch(/^(denied 1|absent)$/u);
426
- expect(String(verdict.share)).toMatch(/^(rejected|absent)/u);
427
- expect(verdict.file).toBe("file text");
428
- expect(seen.dialogs).toEqual([]);
477
+ expect(String(verdict.media), "probe: camera and microphone are denied").toMatch(/^(rejected|absent)/u);
478
+ expect(String(verdict.location), "probe: location is denied").toMatch(/^(denied 1|absent)$/u);
479
+ expect(String(verdict.share), "probe: sharing is denied").toMatch(/^(rejected|absent)/u);
480
+ expect(verdict.file, "probe: a chosen file can be read").toBe("file text");
481
+ expect(seen.dialogs, "probe: a dialog was shown").toEqual([]);
429
482
  context.measured(`camera/microphone: ${String(verdict.media)}; share: ${String(verdict.share)}`);
430
483
  },
431
484
  },
@@ -450,9 +503,9 @@ export const LIMIT_PROBES = [
450
503
  if (verdict.worker !== "answered 42" && verdict.blobBlocked === true) {
451
504
  context.inapplicable("the page's own CSP, which an opaque frame inherits, blocks blob: workers (worker-src falls back to its script-src): opaque content here gets no workers, whatever its config");
452
505
  }
453
- expect(verdict.worker).toBe("answered 42");
454
- expect(String(verdict.serviceWorker)).toMatch(/^(absent|rejected|throws)/u);
455
- expect(verdict.rtc).toBe("undefined");
506
+ expect(verdict.worker, "probe: a blob: worker answers").toBe("answered 42");
507
+ expect(String(verdict.serviceWorker), "probe: a service worker was registered").toMatch(/^(absent|rejected|throws)/u);
508
+ expect(verdict.rtc, "probe: WebRTC is there").toBe("undefined");
456
509
  context.measured(`service worker: ${String(verdict.serviceWorker)}`);
457
510
  },
458
511
  },
@@ -479,7 +532,7 @@ export const LIMIT_PROBES = [
479
532
  if (verdict.clicked !== "played" && verdict.mediaBlocked === true) {
480
533
  context.inapplicable("the page's own CSP, which an opaque frame inherits, blocks data: media (media-src): opaque content here plays no inline sound, whatever its config");
481
534
  }
482
- expect(verdict.clicked, "play() in a click's handler").toBe("played");
535
+ expect(verdict.clicked, "probe: play() in a click's handler").toBe("played");
483
536
  context.measured(`play() without a click: ${String(verdict.unasked)}`);
484
537
  },
485
538
  },
@@ -495,7 +548,7 @@ export const LIMIT_PROBES = [
495
548
  r.search = location.search;
496
549
  r.hash = location.hash;`),
497
550
  });
498
- expect(await context.result(display)).toMatchObject({
551
+ expect(await context.result(display), "probe: the address is about:srcdoc with no query or hash").toMatchObject({
499
552
  href: "about:srcdoc",
500
553
  search: "",
501
554
  hash: "",
@@ -524,13 +577,13 @@ export const LIMIT_PROBES = [
524
577
  </script>`,
525
578
  });
526
579
  await click(display, "#go");
527
- expect(await recorded(display)).toMatchObject({
580
+ expect(await replacedOrRecorded(display, "#go"), "probe: write and open throw, nested frames are removed, full screen is closed").toMatchObject({
528
581
  write: "throws",
529
582
  open: "throws",
530
583
  frames: 0,
531
584
  fullscreen: "rejected",
532
585
  });
533
- expect(["rejected", "absent"]).toContain((await recorded(display)).clipboard);
586
+ expect(["rejected", "absent"], "probe: the clipboard was written").toContain((await recorded(display)).clipboard);
534
587
  },
535
588
  },
536
589
  {
@@ -544,12 +597,12 @@ export const LIMIT_PROBES = [
544
597
  localStorage.setItem("porthole-limits", "first");
545
598
  r.read = localStorage.getItem("porthole-limits");`),
546
599
  });
547
- expect((await context.result(first)).read).toBe("first");
600
+ expect((await context.result(first)).read, "probe: storage works while the frame is shown").toBe("first");
548
601
  const second = await context.launch({
549
602
  config: inline(),
550
603
  content: attack(`r.read = String(localStorage.getItem("porthole-limits"));`),
551
604
  });
552
- expect((await context.result(second)).read, "another frame's storage").toBe("null");
605
+ expect((await context.result(second)).read, "probe: another frame's storage").toBe("null");
553
606
  },
554
607
  },
555
608
  ];