saffron-ai 1.3.5 → 1.4.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.
@@ -12,6 +12,7 @@ import { createHash, randomBytes } from "node:crypto";
12
12
  import dns from "node:dns";
13
13
  import fs from "node:fs";
14
14
  import path from "node:path";
15
+ import vm from "node:vm";
15
16
  import { expect, test, type APIResponse, type Browser, type BrowserContext, type Dialog, type Download, type ElementHandle, type Frame, type Locator, type Page, type Request, type Response } from "@playwright/test";
16
17
 
17
18
  const SETTINGS: {
@@ -88,6 +89,19 @@ const HELD_AS = new Set(["code", "value", "pem", "encrypted", "json", "data", "s
88
89
  /** Credential words a name may end in written as one word: only ones no ordinary word ends in. */
89
90
  const JOINED_SUFFIXES = ["token", "secret", "password", "passwd", "passphrase", "apikey", "accesskey", "privatekey", "credential", "credentials", "cookie", "sessionid", "sessid"];
90
91
 
92
+ /** A response's body as text, as replay reads it (src/http/replay.ts responseText): in its Content-Type charset, a leading BOM dropped. */
93
+ export async function responseText(response: { text(): Promise<string>; body?(): Promise<Buffer> }, contentType: string | undefined): Promise<string | undefined> {
94
+ const charset = /;\s*charset\s*=\s*"?([^";\s]+)/i.exec(contentType ?? "")?.[1];
95
+ let decoder: TextDecoder | undefined;
96
+ try {
97
+ if (charset && !/^utf-?8$/i.test(charset)) decoder = new TextDecoder(charset);
98
+ } catch {
99
+ // A charset Node does not know: read as UTF-8.
100
+ }
101
+ const text = decoder && response.body ? await response.body().then((b) => decoder.decode(b), () => undefined) : await response.text().catch(() => undefined);
102
+ return text?.replace(/^\uFEFF/, "");
103
+ }
104
+
91
105
  /**
92
106
  * Whether a name (a capture's, a field's, a header's) names a credential, by its last word, a version or a number
93
107
  * after it aside (`accessToken`, `api_key`, `X-Session-Id`, `X-Hub-Signature-256`, `Set-Cookie`), never one it only
@@ -111,6 +125,13 @@ export function namesSecret(name: string): boolean {
111
125
  * `/data/access_token`, `sessionId`, `header:Set-Cookie`): a value the API under test handed out that must not reach
112
126
  * a transcript, a report or another host. A value's shape says nothing; `id` and `name` are plain.
113
127
  */
128
+ /** A token pair's access token (`{ refresh, access }`), as the runner's tokenPairAccess reads it. */
129
+ export function tokenPairAccess(value: unknown): string | undefined {
130
+ if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
131
+ const { access, refresh } = value as { access?: unknown; refresh?: unknown };
132
+ return typeof access === "string" && refresh !== undefined && /^\S{16,}$/.test(access) ? access : undefined;
133
+ }
134
+
114
135
  export function isCredentialCapture(name: string, pointer: string): boolean {
115
136
  // A pointer's last segment, unescaped (`/data/id~1token` names `id/token`).
116
137
  return namesSecret(name) || namesSecret((pointer.split("/").at(-1) ?? "").replaceAll("~1", "/").replaceAll("~0", "~"));
@@ -234,19 +255,63 @@ export function bounded(text: string, edges: "start" | "end" | "both", flags = "
234
255
  // For "not shown", only a decimal point joins two numbers: "2" counts as shown in "1,2,3", as replay reads it.
235
256
  const point = grouped ? "[.,\\u066b\\u066c]" : "[.\\u066b]";
236
257
  const groupAfter = grouped && /(?:^|[^\p{L}\p{N}\p{M}])\p{N}{1,3}$/u.test(text) ? `|${group}\\p{N}{3}(?!\\p{N})` : "";
237
- const before = SPACELESS.test(first) ? `(?<!${NEGATING})` : /^\p{N}/u.test(text) ? `(?<!${LETTER}|\\p{N}${point}|(?:^|[^\\p{L}\\p{N}])[-\\u2212\\u2013]${grouped && /^\p{N}{3}(?!\p{N})/u.test(text) ? `|(?:^|[^\\p{L}\\p{N}\\p{M}])\\p{N}{1,3}${group}` : ""})` : amount ? `(?<!${grouped ? "\\p{L}|" : ""}(?:^|[^\\p{L}\\p{N}])[-\\u2212\\u2013])` : `(?<!${LETTER})`;
238
- const after = !/\p{N}$/u.test(text) ? `(?!${LETTER})` : rows === "end" ? `(?!${LETTER}|${point}\\p{N}${groupAfter})` : `(?!${LETTER}|${point}(?!0{1,2}(?!\\p{N}|${point}\\p{N}))\\p{N}${groupAfter})`;
258
+ // An invisible format character (a soft hyphen, a zero-width space) between the text and its neighbour is no boundary, as replay reads it:
259
+ // "saved" is not in "Un\u00adsaved", nor "1" in "Order 1\u200b2".
260
+ const cf = "\\p{Cf}*";
261
+ const before = SPACELESS.test(first) ? `(?<!${NEGATING})` : /^\p{N}/u.test(text) ? `(?<!(?:${LETTER}|\\p{N}${point}|(?:^|[^\\p{L}\\p{N}])[-\\u2212\\u2013]${grouped && /^\p{N}{3}(?!\p{N})/u.test(text) ? `|(?:^|[^\\p{L}\\p{N}\\p{M}])\\p{N}{1,3}${group}` : ""})${cf})` : amount ? `(?<!(?:${grouped ? "\\p{L}|" : ""}(?:^|[^\\p{L}\\p{N}])[-\\u2212\\u2013])${cf})` : `(?<!${LETTER}${cf})`;
262
+ const after = !/\p{N}$/u.test(text) ? `(?!${cf}${LETTER})` : rows === "end" ? `(?!${cf}(?:${LETTER}|${point}\\p{N}${groupAfter}))` : `(?!${cf}(?:${LETTER}|${point}(?!0{1,2}(?!\\p{N}|${point}\\p{N}))\\p{N}${groupAfter}))`;
239
263
  // Quotes and `>` as hex, so Playwright reads no string or chain in the regex; any whitespace as replay's label match allows.
240
- const body = escapeRegExp(text).replace(/ /g, "\\s+").replace(/["'`>]/g, (c) => `\\x${c.charCodeAt(0).toString(16)}`);
264
+ const literal = (s: string) => escapeRegExp(s).replace(/ /g, "\\s+").replace(/["'`>]/g, (c) => `\\x${c.charCodeAt(0).toString(16)}`);
265
+ // For "not shown", the text with invisible format characters in it (a bidi isolate, a soft hyphen) is shown, as replay reads it.
266
+ // A straight or typographic quote is any of them there: "Can't save" is shown as "Can\u2019t save", as replay reads it.
267
+ const body = grouped ? literal(text) : [...text].map((c) => anyQuote(c) ?? literal(c)).join("\\p{Cf}*");
241
268
  // After a number's point or comma ("$10."), no more digits, as replay reads it.
242
269
  const pointEnd = /\p{N}[.,\u066b\u066c]$/u.test(text) ? "(?!\\p{N})" : "";
243
270
  return new RegExp(`${start ? before : ""}${body}${end ? after : pointEnd}`, flags);
244
271
  }
245
272
 
246
273
  const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
274
+ /** A quote as a class of its straight and typographic forms, written as escapes so Playwright reads no string in it. */
275
+ const anyQuote = (c: string) => (/['\u2018\u2019]/.test(c) ? "[\\x27\\u2018\\u2019]" : /["\u201c\u201d]/.test(c) ? "[\\x22\\u201c\\u201d]" : undefined);
247
276
  const normalize = (s: string) => s.replace(/\s+/g, " ").trim();
248
277
  const contains = (haystack: string, needle: string | RegExp) => (typeof needle === "string" ? haystack.includes(needle) : needle.test(haystack));
249
278
 
279
+ /** For "not shown": a role's name in any case and with invisible format characters in it, as replay reads it. */
280
+ export function shownName(name: string): RegExp {
281
+ const text = said(normalize(name), "the expected name");
282
+ return new RegExp(`^[\\s\\p{Cf}]*${[...text].map((c) => (c === " " ? "\\s+" : anyQuote(c) ?? escapeRegExp(c))).join("\\p{Cf}*")}[\\s\\p{Cf}]*$`, "iu");
283
+ }
284
+
285
+ /** A recorded pattern that backtracks on what it is checked against: the check fails with this, never freezes the run, as in replay. */
286
+ class Backtracks extends Error {
287
+ constructor() {
288
+ super("the pattern takes too long on the text (it backtracks): write it without a repeat inside a repeat, such as (a+)+");
289
+ }
290
+ }
291
+
292
+ // One context for every match: a new one per call costs more than the match on each response of a poll.
293
+ const regexContext = vm.createContext({});
294
+ const regexAll = new vm.Script("Array.from(t.matchAll(re), (m) => Object.assign(Array.from(m), { index: m.index }))");
295
+ /** Every match of `re` (global) in `text`, or undefined when it takes more than `ms`: run where V8 can stop it, as src/util/capture.ts matchesWithin. */
296
+ export function matchesWithin(re: RegExp, text: string, ms = 200): RegExpMatchArray[] | undefined {
297
+ Object.assign(regexContext, { re, t: text });
298
+ try {
299
+ return regexAll.runInContext(regexContext, { timeout: ms }) as RegExpMatchArray[];
300
+ } catch (err) {
301
+ if ((err as { code?: string }).code === "ERR_SCRIPT_EXECUTION_TIMEOUT") return undefined;
302
+ throw err;
303
+ } finally {
304
+ Object.assign(regexContext, { re: undefined, t: undefined });
305
+ }
306
+ }
307
+ const matchesAt = (re: RegExp, text: string): RegExpMatchArray[] => {
308
+ const found = matchesWithin(new RegExp(re.source, re.flags.replace(/[gy]/g, "") + "g"), text);
309
+ if (found === undefined) throw new Backtracks();
310
+ return found;
311
+ };
312
+ /** Whether a recorded pattern matches, as replay's testsWithin: one that backtracks throws Backtracks. */
313
+ const testsWithin = (re: RegExp, text: string): boolean => matchesAt(re, text).length > 0;
314
+
250
315
  /** A recorded regular expression; unicode mode when it needs one. */
251
316
  export function pattern(source: string, flags = ""): RegExp {
252
317
  if (source.includes(`[\\p{L}\\p{N}\\p{M}]`) && !/[uv]/.test(flags)) flags += "u";
@@ -387,8 +452,9 @@ class ResponseLog {
387
452
  status: response.status(),
388
453
  };
389
454
  this.entries.push(entry);
390
- if (/json|text|xml/i.test(response.headers()["content-type"] ?? "")) {
391
- void response.text().then((body) => (entry.body = body), () => undefined);
455
+ const type = response.headers()["content-type"] ?? "";
456
+ if (/json|text|xml/i.test(type)) {
457
+ void responseText(response, type).then((body) => (entry.body = body), () => undefined);
392
458
  }
393
459
  });
394
460
  }
@@ -423,7 +489,7 @@ const decode = (url: string) => {
423
489
 
424
490
  /** Raw, a match ending on a letter or digit written percent-encoded is part of a longer word ("Jos" in "Jos%C3%A9"), as replay reads it. */
425
491
  const rawUrlMatch = (re: RegExp, url: string) =>
426
- [...url.matchAll(new RegExp(re.source, re.flags.replace("g", "") + "g"))].some((m) => !/^%(?!3[Ff]|26|3[Dd]|23|2[Ff])[0-9A-Fa-f]{2}/.test(url.slice(m.index! + m[0].length)));
492
+ matchesAt(re, url).some((m) => !/^%(?!3[Ff]|26|3[Dd]|23|2[Ff])[0-9A-Fa-f]{2}/.test(url.slice(m.index! + m[0].length)));
427
493
 
428
494
  function statusMatches(observed: number, expected?: string): boolean {
429
495
  if (!expected) return observed >= 200 && observed < 300;
@@ -439,6 +505,8 @@ interface Lane {
439
505
  active: Page;
440
506
  opened: Page[];
441
507
  net: ResponseLog;
508
+ /** The open tabs in order when last looked at: where the active one was, should it close itself. */
509
+ tabs: Page[];
442
510
  /** The latest response the session's request client got (see Run.send). */
443
511
  last?: Exchange;
444
512
  }
@@ -573,28 +641,41 @@ export class Run {
573
641
  /** What capture() read, and from which element, for expectDiffers. */
574
642
  private captures = new Map<string, ElementHandle>();
575
643
 
576
- private constructor(private browser: Browser, private baseURL: string | undefined) {}
644
+ private constructor(private browser: Browser, private baseURL: string | undefined, private followsAnyTab: boolean) {}
577
645
 
578
- static async start({ page, browser, baseURL }: { page: Page; browser: Browser; baseURL?: string }): Promise<Run> {
579
- const run = new Run(browser, baseURL);
646
+ /** `followsAnyTab`: an older recording that uses tabs without tab marks, where replay follows any tab that opens. */
647
+ static async start({ page, browser, baseURL, followsAnyTab = false }: { page: Page; browser: Browser; baseURL?: string; followsAnyTab?: boolean }): Promise<Run> {
648
+ const run = new Run(browser, baseURL, followsAnyTab);
580
649
  run.lane = run.track(page.context(), page);
581
650
  run.lanes.set("", run.lane);
582
651
  return run;
583
652
  }
584
653
 
585
654
  private track(context: BrowserContext, active: Page): Lane {
586
- const lane: Lane = { context, active, opened: [], net: new ResponseLog(context) };
655
+ const lane: Lane = { context, active, opened: [], net: new ResponseLog(context), tabs: context.pages() };
587
656
  context.on("page", (p) => lane.opened.push(p));
588
657
  return lane;
589
658
  }
590
659
 
591
- /** The tab the scenario acts on: a tab an action opened is followed, as replay follows it. */
660
+ /**
661
+ * The tab the scenario acts on. A tab opens without moving it, as in replay: only tabs() follows the tab an action
662
+ * was recorded opening (an older recording without tab marks follows any).
663
+ */
592
664
  get page(): Page {
593
665
  const lane = this.lane;
594
666
  while (lane.opened.length > 0) {
595
667
  const fresh = lane.opened.shift()!;
596
- if (!fresh.isClosed()) lane.active = fresh;
668
+ if (!fresh.isClosed() && this.followsAnyTab) lane.active = fresh;
669
+ }
670
+ // The tab closed itself (a sign-in popup that closes when done): the tab that slid into its place, else the last,
671
+ // as replay falls back (Playwright MCP's rule).
672
+ const open = this.openPages();
673
+ if (lane.active.isClosed() && open.length > 0) {
674
+ const at = lane.tabs.indexOf(lane.active);
675
+ const before = at < 0 ? open.length : lane.tabs.slice(0, at).filter((p) => !p.isClosed()).length;
676
+ lane.active = open[Math.min(before, open.length - 1)];
597
677
  }
678
+ lane.tabs = open;
598
679
  return lane.active;
599
680
  }
600
681
 
@@ -699,12 +780,6 @@ export class Run {
699
780
  */
700
781
  async tabs(opens = false, background = false): Promise<void> {
701
782
  const lane = this.lane;
702
- if (background) {
703
- // Opened behind the page clicked: noted, not followed.
704
- await lane.context.waitForEvent("page", { timeout: 150 }).catch(() => undefined);
705
- lane.opened.length = 0;
706
- return;
707
- }
708
783
  if (lane.opened.length === 0) {
709
784
  await lane.context.waitForEvent("page", { timeout: opens ? SETTINGS.timeoutMs : 150 }).catch(() => undefined);
710
785
  }
@@ -712,14 +787,19 @@ export class Run {
712
787
  while (lane.opened.length > 0) {
713
788
  const fresh = lane.opened.shift()!;
714
789
  await fresh.waitForLoadState("domcontentloaded").catch(() => undefined);
790
+ // Opened behind the page clicked: noted, not followed (waited for like any recorded tab, as replay waits).
715
791
  if (!background) lane.active = fresh;
716
792
  }
717
793
  }
718
794
 
719
- private openPages = () => this.lane.context.pages().filter((p) => !p.isClosed());
795
+ private openPages(): Page[] {
796
+ return this.lane.context.pages().filter((p) => !p.isClosed());
797
+ }
720
798
 
721
799
  /** Act on tab `index` (0-based, in the order they opened). */
722
800
  async switchTab(index: number): Promise<void> {
801
+ // A tab that opened already is taken first, as replay follows one before every action: the switch then holds.
802
+ void this.page;
723
803
  await expect.poll(() => this.openPages().length > index, { message: `tab ${index} to exist`, timeout: SETTINGS.timeoutMs }).toBe(true);
724
804
  const target = this.openPages()[index];
725
805
  await target.bringToFront();
@@ -734,15 +814,22 @@ export class Run {
734
814
  this.lane.active = fresh;
735
815
  }
736
816
 
737
- /** Close tab `index`, or the active one; the newest tab left becomes active. */
817
+ /**
818
+ * Close tab `index`, or the active one, where the recording's browser went: another tab closed leaves the active
819
+ * one, and the active one closed moves to the tab that took its place, else the last.
820
+ */
738
821
  async closeTab(index?: number): Promise<void> {
739
822
  this.act();
740
- const target = index === undefined ? this.lane.active : this.openPages()[index];
823
+ // From the tab replay is on: one that opened already is followed first, as replay does before every action.
824
+ const active = this.page;
825
+ const pages = this.openPages();
826
+ const target = index === undefined ? active : pages[index];
741
827
  if (!target) throw new Error(`tab ${index} does not exist`);
828
+ const at = pages.indexOf(target);
742
829
  await target.close();
743
830
  const remaining = this.openPages();
744
831
  if (remaining.length === 0) throw new Error("closed the last tab; nothing left to drive");
745
- this.lane.active = remaining[remaining.length - 1];
832
+ if (target === active || active.isClosed()) this.lane.active = remaining[Math.min(at, remaining.length - 1)];
746
833
  }
747
834
 
748
835
  /** Run `action`, which must start `count` downloads; the latest is the one expectDownload reads. */
@@ -784,26 +871,58 @@ export class Run {
784
871
  * an error drawn 300 ms after the click is shown (found in the 1.3.5 review).
785
872
  */
786
873
  async expectNotShown(build: (root: Page | Frame) => Locator[], ownFrames = true): Promise<void> {
874
+ await this.settled(async () => {
875
+ for (const root of [this.page, ...(ownFrames ? await shownOwnFrames(this.page) : [])]) {
876
+ for (const target of build(root)) {
877
+ // A shown closed single select shows its selected option, which Playwright calls hidden, as replay reads it.
878
+ const selected = () =>
879
+ target.evaluateAll((els) =>
880
+ els.some((o) => {
881
+ const owner = o instanceof HTMLOptionElement && o.selected ? o.closest("select") : null;
882
+ if (!owner || owner.multiple || owner.size > 1) return false;
883
+ const box = owner.getBoundingClientRect();
884
+ return box.width > 0 && box.height > 0 && getComputedStyle(owner).visibility !== "hidden";
885
+ }),
886
+ );
887
+ if ((await target.filter({ visible: true }).count()) > 0 || (await selected())) return false;
888
+ }
889
+ }
890
+ return true;
891
+ }, "every match of every recorded locator to be hidden, and to stay hidden");
892
+ }
893
+
894
+ /**
895
+ * As replay's pollSettled: open requests answered first, then `check` must hold for half a second, so a passing
896
+ * moment (a list still growing, a navigation on its way, a request answered again) is not the verdict.
897
+ */
898
+ async settled(check: () => Promise<boolean>, message: string): Promise<void> {
787
899
  await this.lane.net.quiet(Math.min(SETTINGS.timeoutMs / 2, 3000));
788
900
  const settle = Math.min(500, SETTINGS.timeoutMs / 4);
789
901
  let since: number | undefined;
902
+ const stop = stopsOnBacktrack(check);
790
903
  await expect
791
904
  .poll(
792
905
  async () => {
793
- for (const root of [this.page, ...(ownFrames ? await shownOwnFrames(this.page) : [])]) {
794
- for (const target of build(root)) {
795
- if ((await target.filter({ visible: true }).count()) > 0) {
796
- since = undefined;
797
- return false;
798
- }
799
- }
906
+ if (!(await stop.check().catch(() => false))) {
907
+ since = undefined;
908
+ return false;
800
909
  }
910
+ if (stop.backtracked()) return true;
801
911
  since ??= Date.now();
802
912
  return Date.now() - since >= settle;
803
913
  },
804
- { message: "every match of every recorded locator to be hidden, and to stay hidden", timeout: SETTINGS.timeoutMs + settle },
914
+ { message, timeout: SETTINGS.timeoutMs + settle },
805
915
  )
806
916
  .toBe(true);
917
+ stop.rethrow(message);
918
+ }
919
+
920
+ /** The target shows exactly `n` elements, held once the page settles, as replay counts them. */
921
+ async expectCount(target: Locator, n: number): Promise<void> {
922
+ let seen = 0;
923
+ await this.settled(async () => (seen = await target.filter({ visible: true }).count()) === n, `the target to show ${n} element(s)`).catch((err) => {
924
+ throw new Error(`${err instanceof Error ? err.message : String(err)}; it shows ${seen}`);
925
+ });
807
926
  }
808
927
 
809
928
  /** The text `target` shows, once open requests are answered and the text has held for half a second. */
@@ -820,7 +939,7 @@ export class Run {
820
939
  const at = Date.now();
821
940
  if (seen?.text !== text) seen = { text, since: at };
822
941
  if (at - seen.since < settle && at < deadline) return false;
823
- const element = await target.first().elementHandle({ timeout: 1000 }).catch(() => null);
942
+ const element = await (await theMatch(target)).elementHandle({ timeout: 1000 }).catch(() => null);
824
943
  if (!element) return false;
825
944
  await this.captures.get(name)?.dispose().catch(() => undefined);
826
945
  this.captures.set(name, element);
@@ -858,9 +977,10 @@ export class Run {
858
977
  let element: ElementHandle | undefined = same ? this.captures.get(compareTo) : undefined;
859
978
  /** The latest look's reason the two cannot be compared: said only if no look passes. */
860
979
  let problem: string | undefined;
861
- await expect
862
- .poll(async () => {
863
- element ??= (await target.first().elementHandle({ timeout: 1000 }).catch(() => null)) ?? undefined;
980
+ // Held once the page settles, as replay checks it: a placeholder drawn during a refresh is not the verdict.
981
+ await this
982
+ .settled(async () => {
983
+ element ??= (await (await theMatch(target)).elementHandle({ timeout: 1000 }).catch(() => null)) ?? undefined;
864
984
  if (!element) return false;
865
985
  const text = await drawn(element);
866
986
  if (text === "") return false;
@@ -869,8 +989,7 @@ export class Run {
869
989
  if (!("differ" in verdict) || !verdict.differ) return false;
870
990
  // The element must still be one the target names.
871
991
  return target.evaluateAll((els, el) => els.includes(el as HTMLElement), element).catch(() => false);
872
- }, { message: `target text to differ from "${compareTo}" (${right})`, timeout: SETTINGS.timeoutMs })
873
- .toBe(true)
992
+ }, `target text to differ from "${compareTo}" (${right})`)
874
993
  .catch((err) => {
875
994
  throw problem ? new Error(`the differs check: ${problem}`) : err;
876
995
  });
@@ -887,20 +1006,25 @@ export class Run {
887
1006
  masked(() => jsonChecksReadable(match.json!));
888
1007
  }
889
1008
  const net = this.lane.net;
890
- await expect
891
- .poll(
892
- () =>
893
- (kind === "check" ? net.sinceAction() : net.sincePreviousStep()).some(
894
- (e) =>
895
- (rawUrlMatch(url, e.url) || url.test(decode(e.url))) &&
896
- (!match.method || e.method.toUpperCase() === match.method.toUpperCase()) &&
897
- statusMatches(e.status, match.status) &&
898
- (!match.json || masked(() => checkResponseJson(e.body, match.json!)) === undefined) &&
899
- (!body || (e.body !== undefined && body.test(e.body))),
900
- ),
901
- { message: `a ${match.method ?? ""} response from /${match.url}/ with status ${match.status ?? "2xx"}${match.body ? ` and a body matching /${match.body}/` : ""}${match.json ? ` whose JSON fields pass ${match.json.length} check(s)` : ""}`, timeout: SETTINGS.timeoutMs },
902
- )
903
- .toBe(true);
1009
+ const matches = (e: Observed) =>
1010
+ (rawUrlMatch(url, e.url) || testsWithin(url, decode(e.url))) &&
1011
+ (!match.method || e.method.toUpperCase() === match.method.toUpperCase()) &&
1012
+ statusMatches(e.status, match.status) &&
1013
+ (!match.json || masked(() => checkResponseJson(e.body, match.json!)) === undefined) &&
1014
+ (!body || (e.body !== undefined && testsWithin(body, e.body)));
1015
+ const seenNow = async () => {
1016
+ const seen = kind === "check" ? net.sinceAction() : net.sincePreviousStep();
1017
+ const first = seen.find(matches);
1018
+ if (!first || kind === "wait") return first !== undefined;
1019
+ // As replay: the same request (URL and method, and the body the check names) answered again after it with a
1020
+ // status the check rejects fails the check; a POST answered 200 and then 500 failed (found in review).
1021
+ const same = (e: Observed) =>
1022
+ e.url === first.url && e.method === first.method && (!match.json || masked(() => checkResponseJson(e.body, match.json!)) === undefined) && (!body || (e.body !== undefined && testsWithin(body, e.body)));
1023
+ return !seen.some((e) => e.seq > first.seq && same(e) && !matches(e));
1024
+ };
1025
+ const message = `a ${match.method ?? ""} response from /${match.url}/ with status ${match.status ?? "2xx"}${match.body ? ` and a body matching /${match.body}/` : ""}${match.json ? ` whose JSON fields pass ${match.json.length} check(s)` : ""}`;
1026
+ // A check, once the page's requests settle, as replay checks it; a wait takes the first that matches.
1027
+ await (kind === "check" ? this.settled(seenNow, message) : poll(seenNow, message));
904
1028
  }
905
1029
 
906
1030
  /**
@@ -1018,9 +1142,9 @@ export class Run {
1018
1142
  const reason = (err instanceof Error ? err.message : String(err)).split("\n")[0].replace(/^apiRequestContext\.fetch:\s*/, "").trim();
1019
1143
  throw new Error(mask(`${method} ${url} got no response: ${reason}`));
1020
1144
  }
1021
- const body = await response.text().catch(() => undefined);
1022
1145
  const status = response.status();
1023
1146
  const headers = response.headers();
1147
+ const body = await responseText(response, headers["content-type"]);
1024
1148
  // Its body copied, the response is let go, as replay does.
1025
1149
  await response.dispose?.().catch(() => undefined);
1026
1150
  const got: Exchange = (lane.last = { method, url, status, headers, body, durationMs: Date.now() - started });
@@ -1184,13 +1308,13 @@ const drawn = async (element: ElementHandle) => normalize((await read(element).c
1184
1308
  const DRAWN_TEXT: string = /*DRAWN_TEXT*/ "" /*END*/;
1185
1309
 
1186
1310
  /** The element's drawn text and its lines; nothing when it draws none. */
1187
- async function read(element: ElementHandle): Promise<{ text: string; pieces: string[]; runs: string }> {
1188
- return element.evaluate((el, src) => (0, eval)(`(${src})`)(el, true), DRAWN_TEXT);
1311
+ async function read(element: ElementHandle, how: true | "each" = true): Promise<{ text: string; pieces: string[]; runs: string }> {
1312
+ return element.evaluate((el, [src, mode]) => (0, eval)(`(${src})`)(el, mode), [DRAWN_TEXT, how] as const);
1189
1313
  }
1190
1314
 
1191
- /** The lines an element shows, as replay's expectEach reads them. */
1315
+ /** The lines an element shows, as replay's expectEach reads them: every option of a closed dropdown too. */
1192
1316
  async function lines(element: ElementHandle): Promise<string[]> {
1193
- return (await read(element)).pieces;
1317
+ return (await read(element, "each")).pieces;
1194
1318
  }
1195
1319
 
1196
1320
  // A copy of the runner's choice of the match a check reads (src/replay/index.ts), kept the same by a test.
@@ -1222,8 +1346,32 @@ async function theMatch(target: Locator): Promise<Locator> {
1222
1346
  return at > 0 ? target.nth(at) : target.first();
1223
1347
  }
1224
1348
 
1225
- const poll = (check: () => Promise<boolean>, message: string) =>
1226
- expect.poll(check, { message, timeout: SETTINGS.timeoutMs }).toBe(true);
1349
+ const poll = async (check: () => Promise<boolean>, message: string): Promise<void> => {
1350
+ const stop = stopsOnBacktrack(check);
1351
+ await expect.poll(stop.check, { message, timeout: SETTINGS.timeoutMs }).toBe(true);
1352
+ stop.rethrow(message);
1353
+ };
1354
+
1355
+ /** A check that ends its poll on a pattern that backtracks; rethrow then fails with why, as replay's pollEvery does. */
1356
+ function stopsOnBacktrack(check: () => Promise<boolean>): { check: () => Promise<boolean>; backtracked: () => boolean; rethrow: (message: string) => void } {
1357
+ let caught: Backtracks | undefined;
1358
+ return {
1359
+ check: async () => {
1360
+ if (caught) return true;
1361
+ try {
1362
+ return await check();
1363
+ } catch (err) {
1364
+ if (!(err instanceof Backtracks)) throw err;
1365
+ caught = err;
1366
+ return true;
1367
+ }
1368
+ },
1369
+ backtracked: () => caught !== undefined,
1370
+ rethrow: (message) => {
1371
+ if (caught) throw new Error(`${message}: ${caught.message}`);
1372
+ },
1373
+ };
1374
+ }
1227
1375
 
1228
1376
  /** The target shows `text` (a string is a plain substring; see bounded). */
1229
1377
  export async function expectText(target: Locator, text: string | RegExp): Promise<void> {
@@ -1232,6 +1380,14 @@ export async function expectText(target: Locator, text: string | RegExp): Promis
1232
1380
  await poll(async () => contains(await shown(target, "runs"), needle), `target text to contain ${text}`);
1233
1381
  }
1234
1382
 
1383
+ /** The match replay reads is shown and holds `value`, both in one look, as replay checks it. */
1384
+ export async function expectValue(target: Locator, value: string): Promise<void> {
1385
+ await poll(async () => {
1386
+ const match = await theMatch(target);
1387
+ return (await match.isVisible()) && (await match.inputValue({ timeout: 1000 })) === value;
1388
+ }, `a shown input with value "${value}"`);
1389
+ }
1390
+
1235
1391
  /** The target's text matches the recorded pattern, in any case. */
1236
1392
  export async function expectMatches(target: Locator, source: string): Promise<void> {
1237
1393
  const re = pattern(source, "i");
@@ -1252,9 +1408,17 @@ export async function expectAttribute(target: Locator, name: string, source: str
1252
1408
  const element = await theMatch(target);
1253
1409
  // Shown, unless the attribute is what hides it, as replay checks it.
1254
1410
  if (!["hidden", "aria-hidden", "inert", "class", "style", "open", "data-state"].includes(name.toLowerCase()) && !(await element.isVisible())) return false;
1255
- const found = await element.getAttribute(name, { timeout: 1000 }).catch(() => undefined);
1411
+ // A form control's state as it is now, as replay reads it: a box the app unticked has no `checked`.
1412
+ const live = /^(?:checked|selected|value)$/i.test(name)
1413
+ ? await element.evaluate((control: any, key: string): string | null | undefined => {
1414
+ if (!(key in control) || (key === "value" && !/^(?:INPUT|TEXTAREA|SELECT|OPTION|BUTTON)$/.test(control.tagName))) return undefined;
1415
+ if (key === "value") return String(control.value);
1416
+ return control[key] ? "" : null;
1417
+ }, name.toLowerCase()).catch(() => undefined)
1418
+ : undefined;
1419
+ const found = live !== undefined ? live : await element.getAttribute(name, { timeout: 1000 }).catch(() => undefined);
1256
1420
  if (found === undefined) return false;
1257
- return found === null ? absentHolds : re.test(found);
1421
+ return found === null ? absentHolds : testsWithin(re, found);
1258
1422
  }, `attribute ${name} to match /${source}/`);
1259
1423
  }
1260
1424
 
@@ -1268,10 +1432,30 @@ export async function expectStyle(target: Locator, property: string, expected: s
1268
1432
  if (!["display", "visibility", "opacity", "content-visibility", "height", "max-height", "width", "max-width", "transform", "clip-path", "clip"].includes(property.toLowerCase()) && !(await element.isVisible())) return false;
1269
1433
  const found = await element.evaluate((el, name) => (globalThis as unknown as { getComputedStyle(e: unknown): { getPropertyValue(n: string): string } }).getComputedStyle(el).getPropertyValue(name), property, { timeout: 1000 }).catch(() => undefined);
1270
1434
  if (found === undefined) return false;
1271
- return typeof wanted === "string" ? normalize(found) === wanted : wanted.test(normalize(found));
1435
+ return typeof wanted === "string" ? normalize(found) === wanted : testsWithin(wanted, normalize(found));
1272
1436
  }, `${property} to be ${expected}`);
1273
1437
  }
1274
1438
 
1439
+ /**
1440
+ * Selects the recorded options as replay does: an option that is one option's label and another's value is taken
1441
+ * as the label (Playwright MCP's form fill picks by label but writes a plain string).
1442
+ */
1443
+ export async function selectOption(target: Locator, options: string[]): Promise<void> {
1444
+ const plain = options.length > 1 ? options : options[0];
1445
+ const norm = (t: string) => t.replace(/[​­]/g, "").trim().replace(/\s+/g, " ");
1446
+ const listed: [string, string][] = await target
1447
+ .evaluate((el: any) => {
1448
+ const select = el.localName === "label" ? el.control : el;
1449
+ return select?.localName === "select" ? [...select.options].map((o: any): [string, string] => [o.value, o.label]) : [];
1450
+ }, undefined, { timeout: SETTINGS.timeoutMs })
1451
+ .catch(() => []);
1452
+ const labels = new Set(listed.map(([, label]) => norm(label)));
1453
+ const values = new Set(listed.map(([v]) => v));
1454
+ const byLabel =
1455
+ options.some((o) => labels.has(norm(o)) && values.has(o)) && options.every((o) => labels.has(norm(o)) || values.has(o));
1456
+ await target.selectOption(byLabel ? options.map((o) => (labels.has(norm(o)) ? { label: o } : { value: o })) : plain);
1457
+ }
1458
+
1275
1459
  /** Every match of every locator the recording names is hidden. */
1276
1460
  export async function expectNotVisible(...targets: Locator[]): Promise<void> {
1277
1461
  // All hidden at the same look, as replay checks them: one gone, then another, while the first came back, is not a pass.
@@ -1350,9 +1534,11 @@ export function urlContains(url: string, expected: string | RegExp): boolean {
1350
1534
  }
1351
1535
 
1352
1536
  /** The URL contains `expected` (raw, decoded, or with + read as a space); with "excludes", it does not; with "path", its path is exactly `expected`. */
1353
- export async function expectUrl(page: Page, expected: string | RegExp, match?: "excludes" | "path"): Promise<void> {
1537
+ export async function expectUrl(page: Page, expected: string | RegExp, match?: "excludes" | "path", run?: Run): Promise<void> {
1354
1538
  said(expected, "the expected URL");
1355
- await poll(async () => {
1539
+ // A URL that does not hold the text only once a navigation the action started has had its moment, as replay checks it.
1540
+ if (match === "excludes" && !run) throw new Error("a URL check with \"excludes\" needs the run, to wait for the page to settle");
1541
+ await (match === "excludes" ? run!.settled.bind(run) : poll)(async () => {
1356
1542
  const url = page.url();
1357
1543
  if (match === "path") {
1358
1544
  const path = new URL(url).pathname;
@@ -1386,6 +1572,8 @@ export function parseAmount(text: string): number | undefined {
1386
1572
  const [found] = runs;
1387
1573
  const before = joined.slice(0, found.index);
1388
1574
  const after = joined.slice(found.index + found[0].length);
1575
+ // Abbreviated ("€1.5M", "$1.2K", "2.5bn", "1,5 Mio. €", "3 million"): not the amount its digits say, and "1.5k" is not "1.5M".
1576
+ if (/^(?:[kKmMbB]|\s?(?:bn|mn|mio|mrd|million|billion|lakh|crore)s?\.?)(?!\p{L})/iu.test(after)) return undefined;
1389
1577
  // A decimal with no whole part ("$.50", "€,99"): the separator before it is
1390
1578
  // the decimal point, and the sign is judged by what comes before that ("-.50", "($.50)").
1391
1579
  const bare = /[.,]$/.test(before) && !/\d[.,]$/.test(before) && /^\d+$/.test(found[0]);
@@ -1420,7 +1608,9 @@ export function parseAmount(text: string): number | undefined {
1420
1608
  // Grouping: one separator, every group after the first three digits long, not the decimal one.
1421
1609
  const groups = whole.split(/[.,]/);
1422
1610
  const grouping = new Set(whole.match(/[.,]/g) ?? []);
1423
- if (grouping.size > 1 || (decimal && grouping.has(digits[last])) || groups[0] === "" || groups.slice(1).some((g) => g.length !== 3)) return undefined;
1611
+ // Or Indian lakh grouping by commas: twos before the last three ("1,23,456").
1612
+ const lakh = grouping.has(",") && groups.length > 2 && groups[0].length <= 2 && groups.at(-1)!.length === 3 && groups.slice(1, -1).every((g) => g.length === 2);
1613
+ if (grouping.size > 1 || (decimal && grouping.has(digits[last])) || groups[0] === "" || (!lakh && groups.slice(1).some((g) => g.length !== 3))) return undefined;
1424
1614
  const amount = Number(`${negative ? "-" : ""}${groups.join("")}${decimal ? `.${tail}` : ""}`);
1425
1615
  return Number.isFinite(amount) ? amount : undefined;
1426
1616
  }
@@ -1499,6 +1689,10 @@ export function valuesDiffer(left: string, right: string): { differ: boolean } |
1499
1689
  // Two currencies, or a price against a label holding that price's currency ("Book now for NOK 1,295"):
1500
1690
  // a change no amount explains. Any other two (references, counts: "ABC-123", "1 night") compare as text.
1501
1691
  if (currency(ua) && currency(ub)) {
1692
+ // "$5" and "5 USD" are one currency written two ways.
1693
+ const [ca, cb] = [amountCurrency(left), amountCurrency(right)];
1694
+ // Cents against dollars ("50¢" and "$0.50") is one amount in two units: refused as before.
1695
+ if (ca && cb && !otherCurrency(ca, cb) && (ca.is === "¢") === (cb.is === "¢")) return { differ: !sameAmount(a, b) };
1502
1696
  return { problem: `"${left}" and "${right}" are amounts in different currencies, so they differ whatever the amount does. Capture both in one currency.` };
1503
1697
  }
1504
1698
  if ((currency(ua) && words(ub).includes(ua)) || (currency(ub) && words(ua).includes(ub))) {
@@ -1704,7 +1898,9 @@ export function exactValueKey(body: string, read: (json: unknown) => unknown): s
1704
1898
  }
1705
1899
 
1706
1900
  const kind = (value: unknown) => value === null ? "null" : Array.isArray(value) ? "array" : value instanceof ExactNumber ? "number" : typeof value;
1707
- const describe = (value: unknown) => `${kind(value)}${value instanceof ExactNumber ? ` ${value}` : value === null || typeof value !== "object" ? ` ${JSON.stringify(value)}` : ""}`;
1901
+ const describeValue = (value: unknown) => `${kind(value)}${value instanceof ExactNumber ? ` ${value}` : value === null || typeof value !== "object" ? ` ${JSON.stringify(value)}` : ""}`;
1902
+
1903
+ const CREDENTIAL_NOT_KEPT = "[credential, not kept]";
1708
1904
 
1709
1905
  /** The value at a JSON Pointer: own properties and array indexes only, undefined when missing. */
1710
1906
  function at(json: unknown, path: string): unknown {
@@ -1734,6 +1930,11 @@ function checkValue(json: unknown, checks: ResponseJsonCheck[], prefix = ""): st
1734
1930
  for (const check of checks) {
1735
1931
  const value = at(json, check.path);
1736
1932
  const field = `JSON field ${JSON.stringify(prefix + check.path)}`;
1933
+ // A field named as a credential, or under one (`session: { id }`), as hideCredentialFields reads it: its value never reaches the message.
1934
+ const secret = value !== undefined && ([prefix + check.path, (prefix + check.path).replace(/\/[^/]*$/, "")].some((p) => p !== "" && isCredentialCapture("", p)) ||
1935
+ // A token pair's access token, as nestedCredentials reads it.
1936
+ (/\/access$/.test(check.path) && tokenPairAccess(at(json, check.path.replace(/\/access$/, ""))) === value));
1937
+ const describe = (v: unknown) => (secret ? CREDENTIAL_NOT_KEPT : describeValue(v));
1737
1938
  const got = value === undefined ? "missing" : describe(value);
1738
1939
  if (check.item) {
1739
1940
  if (!Array.isArray(value)) return `${field}: expected a list, got ${got}`;
@@ -1754,7 +1955,7 @@ function checkValue(json: unknown, checks: ResponseJsonCheck[], prefix = ""): st
1754
1955
  if ((value !== undefined) !== check.exists) return `${field}: expected ${check.exists ? "present, got missing" : `absent, got ${describe(value)}`}`;
1755
1956
  } else if (check.differs !== undefined) {
1756
1957
  const other = jsonExpected(check, check.differs);
1757
- if (value === undefined) return `${field}: expected a value other than ${describe(other)}, got missing`;
1958
+ if (value === undefined) return `${field}: expected a value other than ${describeValue(other)}, got missing`;
1758
1959
  // Untyped, the text is compared as written: a number 5 is the same as "5" (a captured id is kept as text).
1759
1960
  // A list, an object or null is compared as its JSON text: [{"sku":"a"}] is the same as itself written out.
1760
1961
  // Keys in any order and any spacing: {"b":2,"a":1} is the same as {"a": 1, "b": 2}.
@@ -1774,7 +1975,10 @@ function checkValue(json: unknown, checks: ResponseJsonCheck[], prefix = ""): st
1774
1975
  const nonEmptyNumber = check.pattern === NON_EMPTY && (typeof value === "number" || value instanceof ExactNumber);
1775
1976
  if (nonEmptyNumber) continue;
1776
1977
  if (typeof value !== "string") return `${field}: expected text matching /${check.pattern}/, got ${got}`;
1777
- if (!re.test(value)) return `${field}: expected text matching /${check.pattern}/, got ${JSON.stringify(value)}`;
1978
+ // Run where V8 can stop it: a recorded pattern that backtracks (`(a+)+$`) on a long value fails, never freezes the run (found in the 1.4.0 review).
1979
+ const found = matchesWithin(new RegExp(re.source, re.flags.replace(/[gy]/g, "") + "g"), value);
1980
+ if (found === undefined) return `${field}: the pattern /${check.pattern}/ takes too long on the text (it backtracks): write it without a repeat inside a repeat, such as (a+)+`;
1981
+ if (found.length === 0) return `${field}: expected text matching /${check.pattern}/, got ${secret ? CREDENTIAL_NOT_KEPT : JSON.stringify(value)}`;
1778
1982
  } else if (check.min !== undefined || check.max !== undefined) {
1779
1983
  const min = check.min === undefined ? undefined : jsonNumber(check, "min");
1780
1984
  const max = check.max === undefined ? undefined : jsonNumber(check, "max");
@@ -1792,12 +1996,12 @@ function checkValue(json: unknown, checks: ResponseJsonCheck[], prefix = ""): st
1792
1996
  };
1793
1997
  const under = min !== undefined && beyond(check.min!, min, -1);
1794
1998
  const over = max !== undefined && beyond(check.max!, max, 1);
1795
- if (under || over) return `${field}: expected a number ${bounds}, got ${value}`;
1999
+ if (under || over) return `${field}: expected a number ${bounds}, got ${secret ? CREDENTIAL_NOT_KEPT : value}`;
1796
2000
  } else {
1797
2001
  const expected = jsonExpected(check);
1798
2002
  // Too large to compare as a number, it is checked as a string of its digits (jsonExpected says so).
1799
2003
  const same = value instanceof ExactNumber ? (check.type === undefined || check.type === "string") && String(value) === expected : value === expected;
1800
- if (!same) return `${field}: expected ${describe(expected)}, got ${got}`;
2004
+ if (!same) return `${field}: expected ${describeValue(expected)}, got ${got}`;
1801
2005
  }
1802
2006
  }
1803
2007
  return undefined;