saffron-ai 1.3.1 → 1.3.3

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "saffron-ai",
3
- "version": "1.3.1",
3
+ "version": "1.3.3",
4
4
  "description": "End-to-end tests written in plain language: an AI agent records each scenario once, replays run at zero tokens, and broken replays heal into proposals you review",
5
5
  "scripts": {
6
6
  "test": "vitest run",
@@ -3,14 +3,14 @@ name: saffron
3
3
  description: Create, translate, or edit Saffron test scenarios in .saffron or .feature files, browser UI tests and HTTP API tests (@api) alike, including validating their recordings and replay. Use when asked to author or fix these test files in a Saffron project. Do not activate for ordinary application development, generic Cucumber projects, or requests only to run existing tests, inspect reports, review proposals, or configure Saffron.
4
4
  license: Saffron Free Use License v1.0 (see the saffron-ai package LICENSE)
5
5
  metadata:
6
- saffron-ai: "1.3.1"
6
+ saffron-ai: "1.3.3"
7
7
  author: saffron-ai
8
8
  homepage: https://saffron-ai.io
9
9
  ---
10
10
 
11
11
  # Saffron
12
12
 
13
- This skill describes saffron-ai 1.3.1 (see the compatibility page: https://saffron-ai.io/docs/compatibility).
13
+ This skill describes saffron-ai 1.3.3 (see the compatibility page: https://saffron-ai.io/docs/compatibility).
14
14
 
15
15
  Apply this workflow only when asked to create, translate, or edit Saffron
16
16
  scenarios in `.saffron` or `.feature` files. A Saffron mention or an
@@ -95,6 +95,37 @@ Feature: Customers API
95
95
  sends the value and the recording keeps the token.
96
96
  - **Outlines** work as for browser scenarios: write `<column>` in every
97
97
  step whose request or check depends on the row.
98
+ - **Several requests at once, each with its own values** (an idempotency
99
+ test, two registrations racing) are one step with a table: a header
100
+ row, then a row per request, the first column naming it. Saffron sends
101
+ the request once per row, every row before any answers, and keeps each
102
+ response with its row whatever order they arrive in. Values all rows
103
+ share can come from a Background step's table, which sends nothing:
104
+
105
+ ```gherkin
106
+ Background:
107
+ Given no-show registrations use these shared request details:
108
+ | reservation | {data:no-show.chargeable} |
109
+ | API key | {env:NOSHOW_API_KEY} |
110
+ | idempotency key | {unique:registration} |
111
+
112
+ Scenario: Correlate every response to its concurrent request
113
+ When I send these no-show registrations concurrently as "registrations":
114
+ | request | correlation ID |
115
+ | original | {unique:original} |
116
+ | duplicate | {unique:duplicate} |
117
+ Then every response in "registrations" should have status 200 or 202
118
+ And every response should echo its own request's correlation ID
119
+ And every 202 response should have a numeric "Retry-After" header
120
+ And at least one response should have status 200
121
+ And all 200 responses should have the same "/paymentReference"
122
+ ```
123
+
124
+ Each `Then` says its scope: every response, those of one status
125
+ ("every 200 response"), a named one ("the duplicate"), or at least
126
+ some. A filtered check holds when no response has that status, so pair
127
+ "every 200 response ..." with "at least one response should have
128
+ status 200". "The response" after a group names none of them, and fails.
98
129
 
99
130
  ## What gets recorded, and what to check in `saffron diff`
100
131
 
@@ -104,6 +135,8 @@ Feature: Customers API
104
135
  | `expectStatus` | the status of the latest response in that step's session, exact (`404`) or a class (`2xx`) |
105
136
  | `expectJson` | field checks by JSON Pointer, typed (`/months` equals `3` as a number) or present/absent; an entry of a list with `item` (`{"path": "/messages", "item": [{"path": "/name", "equals": "ann"}]}`), wherever it stands |
106
137
  | `expectSchema` | the latest response against the pinned contract: the operation's response schema, or a named component schema |
138
+ | `request` with `group` | sent once per row of its step's table; `<row:column>` is a row's own cell, the first column names it |
139
+ | `expectGroup` | the group's responses: every one, those answering `status`, or the `members` named; each holds `statuses`, `json`, `header` or the contract with its own row's values; `same` a field they all share, non-empty; `atLeast` how many must hold it |
107
140
 
108
141
  Before accepting a proposal, check that:
109
142
 
@@ -116,7 +149,10 @@ Before accepting a proposal, check that:
116
149
  and "should match the contract" became an `expectSchema`;
117
150
  - an error case expects the status the step names;
118
151
  - an entry of a list is an `item` check, not a position (`/0/name`),
119
- unless the step names the position ("the first order").
152
+ unless the step names the position ("the first order");
153
+ - a group's request writes each row's own value as `<row:column>`, and a
154
+ `Then` about every response is an `expectGroup` with no `members` or
155
+ `atLeast` it does not state, never a check of one response.
120
156
 
121
157
  The agent verifies each check against the response before it records it,
122
158
  so a recorded check held at recording time; review whether it is the
@@ -18,10 +18,14 @@ But I should not see an error banner
18
18
  trailing block of assertions is always strict; under the opt-in
19
19
  `adaptable-mid` policy only mid-scenario checkpoints may be adapted.
20
20
 
21
- A check on the page's address reads what the URL contains (`Then the URL
22
- contains "/orders"`). There is no check that a URL does not contain
23
- something, or is exactly something: name a part the URL must contain, or
24
- check what the page shows.
21
+ A check on the page's address is recorded the way the step says it: that
22
+ the URL contains a value (`Then the URL contains "/orders"`, the default),
23
+ that it no longer holds one (`Then the URL no longer holds the login
24
+ token`), or that its path is exactly one (`Then I am on the /account path
25
+ exactly`, its query and fragment aside). Write "no longer" or "exactly"
26
+ only when you mean it: the recorder refuses a check the step's words do
27
+ not name. A containment check reads its value as a whole part of the URL
28
+ and outside the query, unless the value names one (`?`, `=`, `&`).
25
29
 
26
30
  ## Scenario Outlines
27
31
 
@@ -51,21 +51,34 @@ export function env(name: string): string {
51
51
  return value;
52
52
  }
53
53
 
54
- /** Every credential the API handed out in this worker (isCredentialCapture), name to value: masked like an {env:...} value. Which a request may send is the Run's own. */
55
- const CREDENTIALS = new Map<string, string>();
54
+ /** Every credential the API handed out in this worker (isCredentialCapture), name and value, an earlier value a rotation replaced kept too: masked like an {env:...} value. Which a request may send is the Run's own. */
55
+ const CREDENTIALS: [string, string][] = [];
56
56
 
57
- /** Text with every {env:...} value and captured credential written back as its token, longest first, as written and as JSON escapes it. */
57
+ /** A credential the API handed out, kept once however often a poll reads it. */
58
+ const remember = (name: string, value: string): void => {
59
+ if (!CREDENTIALS.some(([n, v]) => n === name && v === value)) CREDENTIALS.push([name, value]);
60
+ };
61
+
62
+ /** Text with every {env:...} value and captured credential written back as its token, longest first, as written, as JSON escapes it and as a URL encodes it (found in review). */
58
63
  function mask(text: string): string {
59
- const values = [...[...SECRETS].map(([name, value]) => [`{env:${name}}`, value]), ...[...CREDENTIALS].map(([name, value]) => [`{captured:${name}}`, value])];
64
+ const values = [...[...SECRETS].map(([name, value]) => [`{env:${name}}`, value]), ...CREDENTIALS.map(([name, value]) => [`{captured:${name}}`, value])];
60
65
  for (const [token, value] of values.sort((a, b) => b[1].length - a[1].length)) {
61
66
  if (value.length < 3) continue;
62
- text = text.replaceAll(value, token);
63
- const escaped = JSON.stringify(value).slice(1, -1);
64
- if (escaped !== value) text = text.replaceAll(escaped, token);
67
+ for (const spelling of new Set([value, JSON.stringify(value).slice(1, -1), encodeURIComponent(value), urlValue(value, true), urlValue(value, false)])) text = text.replaceAll(spelling, token);
65
68
  }
66
69
  return text;
67
70
  }
68
71
 
72
+ /** What `run` returns, any error it throws masked: a check's message quotes the resolved value it compares with (found in review). */
73
+ function masked<T>(run: () => T): T {
74
+ try {
75
+ return run();
76
+ } catch (err) {
77
+ if (err instanceof Error) err.message = mask(err.message);
78
+ throw err;
79
+ }
80
+ }
81
+
69
82
  /** Words a name ends in when what it holds is a credential: a login's token, a session id, a key, a code. */
70
83
  const CREDENTIAL_WORDS = new Set(["token", "secret", "password", "passwd", "pwd", "passphrase", "apikey", "accesskey", "privatekey", "session", "credential", "credentials", "auth", "authorization", "jwt", "bearer", "cookie", "otp", "pin", "csrf", "xsrf", "signature", "nonce", "refresh"]);
71
84
 
@@ -166,22 +179,31 @@ export function projectFile(file: string): string {
166
179
  }
167
180
 
168
181
  const LETTER = String.raw`[\p{L}\p{N}\p{M}]`;
182
+ // A script written without spaces (Chinese, Japanese, Thai...): an edge of it is not bounded, as in replay, but for
183
+ // a negating prefix before it ("成功" is not in "不成功").
184
+ const SPACELESS = /[\p{sc=Han}\p{sc=Hiragana}\p{sc=Katakana}\p{sc=Thai}\p{sc=Lao}\p{sc=Khmer}\p{sc=Myanmar}]/u;
185
+ const NEGATING = "无法|無法|不能|没有|沒有|未能|ไม่ได้|不|未|非|無|无|没|沒|ไม่";
169
186
 
170
187
  /**
171
- * Text that must appear inside a longer text. Where the step wrote a row or
172
- * data value at the start or end ("Order <id>"), that edge is whole: "Order 1"
173
- * never matches "Order 12". Elsewhere it is a plain substring, as in replay.
188
+ * Text that must appear inside a longer text, never inside a longer word or
189
+ * number: "Order 1" never matches "Order 12", nor "5" "12.5". After a number
190
+ * the step wrote, a zero decimal part may follow ("$10" is in "$10.00", not
191
+ * "$10.50"); after a row or data value (`rows` "end"), none.
174
192
  */
175
- export function bounded(text: string, edges: "start" | "end" | "both", flags = "u"): RegExp {
193
+ export function bounded(text: string, edges: "start" | "end" | "both", flags = "u", rows: "" | "end" = ""): RegExp {
176
194
  text = said(normalize(text), "the expected text");
177
- const start = edges !== "end" && new RegExp(`^${LETTER}`, "u").test(text);
178
- const end = edges !== "start" && new RegExp(`${LETTER}$`, "u").test(text);
179
- // Beside a digit, no decimal or thousands part either: "1" is not in "1.5" or "1,000".
180
- const before = /^\p{N}/u.test(text) ? `(?<!${LETTER}|\\p{N}[.,])` : `(?<!${LETTER})`;
181
- const after = /\p{N}$/u.test(text) ? `(?!${LETTER}|[.,]\\p{N})` : `(?!${LETTER})`;
195
+ const first = [...text][0];
196
+ // An amount ("$5.00") is never the negative one after a minus ("-$5.00"), as replay reads it.
197
+ const amount = /^\p{Sc}\s?\p{N}/u.test(text);
198
+ const start = edges !== "end" && (amount || (new RegExp(`^${LETTER}`, "u").test(text) && !(SPACELESS.test(first) && new RegExp(`^(?:${NEGATING})`, "u").test(text))));
199
+ const end = edges !== "start" && new RegExp(`${LETTER}$`, "u").test(text) && !SPACELESS.test([...text].at(-1)!);
200
+ const before = SPACELESS.test(first) ? `(?<!${NEGATING})` : /^\p{N}/u.test(text) ? `(?<!${LETTER}|\\p{N}[.,]|(?:^|[^\\p{L}\\p{N}])[-\\u2212\\u2013])` : amount ? `(?<!(?:^|[^\\p{L}\\p{N}])[-\\u2212\\u2013])` : `(?<!${LETTER})`;
201
+ const after = !/\p{N}$/u.test(text) ? `(?!${LETTER})` : rows === "end" ? `(?!${LETTER}|[.,]\\p{N})` : `(?!${LETTER}|[.,](?!0{1,2}(?!\\p{N}|[.,]\\p{N}))\\p{N})`;
182
202
  // Quotes and `>` as hex, so Playwright reads no string or chain in the regex; any whitespace as replay's label match allows.
183
203
  const body = escapeRegExp(text).replace(/ /g, "\\s+").replace(/["'`>]/g, (c) => `\\x${c.charCodeAt(0).toString(16)}`);
184
- return new RegExp(`${start ? before : ""}${body}${end ? after : ""}`, flags);
204
+ // After a number's point or comma ("$10."), no more digits, as replay reads it.
205
+ const point = edges !== "start" && /\p{N}[.,]$/u.test(text) ? "(?!\\p{N})" : "";
206
+ return new RegExp(`${start ? before : ""}${body}${end ? after : point}`, flags);
185
207
  }
186
208
 
187
209
  const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -789,7 +811,7 @@ export class Run {
789
811
  if (match.json) {
790
812
  const malformed = responseJsonProblem(match.json);
791
813
  if (malformed) throw new Error(`Response json ${malformed}`);
792
- jsonChecksReadable(match.json);
814
+ masked(() => jsonChecksReadable(match.json!));
793
815
  }
794
816
  const net = this.lane.net;
795
817
  await expect
@@ -800,7 +822,7 @@ export class Run {
800
822
  (url.test(e.url) || url.test(decode(e.url))) &&
801
823
  (!match.method || e.method.toUpperCase() === match.method.toUpperCase()) &&
802
824
  statusMatches(e.status, match.status) &&
803
- (!match.json || checkResponseJson(e.body, match.json) === undefined) &&
825
+ (!match.json || masked(() => checkResponseJson(e.body, match.json!)) === undefined) &&
804
826
  (!body || (e.body !== undefined && body.test(e.body))),
805
827
  ),
806
828
  { 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 },
@@ -881,7 +903,28 @@ export class Run {
881
903
  // A poll is a wait for a state, as replay bounds it: every 100 ms at the fastest, 10 minutes at the longest.
882
904
  if (until && until.intervalMs < 100) throw new Error(`${method} ${spec.path} polls every ${until.intervalMs} ms, faster than the 100 ms a poll may`);
883
905
  if (until && (spec.until!.timeoutMs ?? 30_000) > 600_000) throw new Error(`${method} ${spec.path} polls for ${spec.until!.timeoutMs} ms, longer than the 10 minutes a poll may wait`);
884
- if (until) jsonChecksReadable(until.checks);
906
+ if (until) masked(() => jsonChecksReadable(until.checks));
907
+ // Every response hands out its credentials as it comes, one polled past (a token it rotates) too, and an error
908
+ // quotes a body: they are known before anything is shown (found in review).
909
+ const learn = (got: Exchange): void => {
910
+ for (const [name, pointer] of Object.entries(spec.extract ?? {})) {
911
+ const header = /^header:(.+)$/i.exec(pointer);
912
+ let value: unknown;
913
+ try {
914
+ value = header ? headerOf(got.headers, header[1]) : at(JSON.parse(got.body ?? ""), pointer);
915
+ } catch {
916
+ value = undefined;
917
+ }
918
+ // An object holding one is a credential too, and its token is masked on its own.
919
+ const nested = nestedCredentials(value);
920
+ if (value !== undefined && (isCredentialCapture(name, pointer) || nested.length > 0)) {
921
+ const kept = typeof value === "string" ? value : JSON.stringify(value);
922
+ this.credentials.set(name, kept);
923
+ remember(name, kept);
924
+ }
925
+ for (const [path, secret] of nested) remember(`${name}${path}`, secret);
926
+ }
927
+ };
885
928
  const lane = this.lane;
886
929
  const attempt = async (): Promise<Exchange> => {
887
930
  const started = Date.now();
@@ -903,11 +946,17 @@ export class Run {
903
946
  throw new Error(mask(`${method} ${url} got no response: ${reason}`));
904
947
  }
905
948
  const body = await response.text().catch(() => undefined);
906
- return (lane.last = { method, url, status: response.status(), headers: response.headers(), body, durationMs: Date.now() - started });
949
+ const status = response.status();
950
+ const headers = response.headers();
951
+ // Its body copied, the response is let go, as replay does.
952
+ await response.dispose?.().catch(() => undefined);
953
+ const got: Exchange = (lane.last = { method, url, status, headers, body, durationMs: Date.now() - started });
954
+ learn(got);
955
+ return got;
907
956
  };
908
957
  const notYet = (exchange: Exchange): string | undefined => {
909
958
  if (!statusMatches(exchange.status, spec.status)) return `returned ${exchange.status}, expected ${spec.status ?? "2xx"}${excerpt(exchange.body)}`;
910
- const problem = until && until.checks.length > 0 ? checkResponseJson(exchange.body, until.checks) : undefined;
959
+ const problem = until && until.checks.length > 0 ? masked(() => checkResponseJson(exchange.body, until.checks)) : undefined;
911
960
  return problem ? `${problem}${excerpt(exchange.body)}` : undefined;
912
961
  };
913
962
  let exchange = await attempt();
@@ -915,24 +964,6 @@ export class Run {
915
964
  await new Promise<void>((r) => setTimeout(r, until.intervalMs));
916
965
  exchange = await attempt();
917
966
  }
918
- // A response the step fails on still hands out its credentials, and the error quotes its body: they are known first.
919
- for (const [name, pointer] of Object.entries(spec.extract ?? {})) {
920
- const header = /^header:(.+)$/i.exec(pointer);
921
- let value: unknown;
922
- try {
923
- value = header ? headerOf(exchange.headers, header[1]) : at(JSON.parse(exchange.body ?? ""), pointer);
924
- } catch {
925
- value = undefined;
926
- }
927
- // An object holding one is a credential too, and its token is masked on its own.
928
- const nested = nestedCredentials(value);
929
- if (value !== undefined && (isCredentialCapture(name, pointer) || nested.length > 0)) {
930
- const kept = typeof value === "string" ? value : JSON.stringify(value);
931
- this.credentials.set(name, kept);
932
- CREDENTIALS.set(name, kept);
933
- }
934
- for (const [path, secret] of nested) CREDENTIALS.set(`${name}${path}`, secret);
935
- }
936
967
  const problem = notYet(exchange);
937
968
  if (problem !== undefined) throw new Error(mask(until === undefined ? `${method} ${url} ${problem}` : `${method} ${url} still ${problem} after ${spec.until!.timeoutMs ?? 30_000} ms of polling`));
938
969
  for (const [name, pointer] of Object.entries(spec.extract ?? {})) {
@@ -945,7 +976,7 @@ export class Run {
945
976
  }
946
977
  let parsed: unknown;
947
978
  try {
948
- parsed = JSON.parse(exchange.body ?? "");
979
+ parsed = parseExact(exchange.body ?? "");
949
980
  } catch {
950
981
  throw new Error(mask(`${method} ${url} returned no JSON body, so "${name}" (${pointer || "/"}) cannot be extracted${excerpt(exchange.body)}`));
951
982
  }
@@ -972,8 +1003,10 @@ export class Run {
972
1003
  const last = this.latest();
973
1004
  const malformed = responseJsonProblem(checks);
974
1005
  if (malformed) throw new Error(`Response json ${malformed}`);
975
- jsonChecksReadable(checks);
976
- const problem = checkResponseJson(last.body, checks);
1006
+ const problem = masked(() => {
1007
+ jsonChecksReadable(checks);
1008
+ return checkResponseJson(last.body, checks);
1009
+ });
977
1010
  if (problem) throw new Error(mask(`${last.method} ${last.url}: ${problem}`));
978
1011
  }
979
1012
 
@@ -1052,11 +1085,11 @@ export class Run {
1052
1085
 
1053
1086
  // --- checks on elements ---------------------------------------------------
1054
1087
 
1055
- /** The text the target's first match shows, whitespace collapsed; "" when it is not visible. */
1056
- async function shown(target: Locator): Promise<string> {
1088
+ /** The text the match replay reads shows (theMatch), whitespace collapsed; "" when it is not visible. */
1089
+ async function shown(target: Locator, by: "text" | "runs" = "text"): Promise<string> {
1057
1090
  try {
1058
- const element = await target.first().elementHandle({ timeout: 1000 });
1059
- return element ? normalize((await read(element)).text) : "";
1091
+ const element = await (await theMatch(target)).elementHandle({ timeout: 1000 });
1092
+ return element ? normalize((await read(element))[by]) : "";
1060
1093
  } catch {
1061
1094
  return "";
1062
1095
  }
@@ -1073,7 +1106,7 @@ const drawn = async (element: ElementHandle) => normalize((await read(element).c
1073
1106
  const DRAWN_TEXT: string = /*DRAWN_TEXT*/ "" /*END*/;
1074
1107
 
1075
1108
  /** The element's drawn text and its lines; nothing when it draws none. */
1076
- async function read(element: ElementHandle): Promise<{ text: string; pieces: string[] }> {
1109
+ async function read(element: ElementHandle): Promise<{ text: string; pieces: string[]; runs: string }> {
1077
1110
  return element.evaluate((el, src) => (0, eval)(`(${src})`)(el, true), DRAWN_TEXT);
1078
1111
  }
1079
1112
 
@@ -1117,7 +1150,8 @@ const poll = (check: () => Promise<boolean>, message: string) =>
1117
1150
  /** The target shows `text` (a string is a plain substring; see bounded). */
1118
1151
  export async function expectText(target: Locator, text: string | RegExp): Promise<void> {
1119
1152
  const needle = said(typeof text === "string" ? normalize(text) : text, "the expected text");
1120
- await poll(async () => contains(await shown(target), needle), `target text to contain ${text}`);
1153
+ // Read by runs, as replay reads it: a value never spans a block, a cell or a <br>.
1154
+ await poll(async () => contains(await shown(target, "runs"), needle), `target text to contain ${text}`);
1121
1155
  }
1122
1156
 
1123
1157
  /** The target's text matches the recorded pattern, in any case. */
@@ -1137,7 +1171,10 @@ export async function expectAttribute(target: Locator, name: string, source: str
1137
1171
  const re = pattern(source);
1138
1172
  const absentHolds = re.test("") && re.test("false") && !re.test("true");
1139
1173
  await poll(async () => {
1140
- const found = await (await theMatch(target)).getAttribute(name, { timeout: 1000 }).catch(() => undefined);
1174
+ const element = await theMatch(target);
1175
+ // Shown, unless the attribute is what hides it, as replay checks it.
1176
+ if (!["hidden", "aria-hidden", "inert", "class", "style", "open", "data-state"].includes(name.toLowerCase()) && !(await element.isVisible())) return false;
1177
+ const found = await element.getAttribute(name, { timeout: 1000 }).catch(() => undefined);
1141
1178
  if (found === undefined) return false;
1142
1179
  return found === null ? absentHolds : re.test(found);
1143
1180
  }, `attribute ${name} to match /${source}/`);
@@ -1148,7 +1185,10 @@ export async function expectStyle(target: Locator, property: string, expected: s
1148
1185
  said(expected, "the expected style");
1149
1186
  const wanted = typeof expected === "string" ? normalize(expected) : expected;
1150
1187
  await poll(async () => {
1151
- const found = await (await theMatch(target)).evaluate((el, name) => (globalThis as unknown as { getComputedStyle(e: unknown): { getPropertyValue(n: string): string } }).getComputedStyle(el).getPropertyValue(name), property, { timeout: 1000 }).catch(() => undefined);
1188
+ const element = await theMatch(target);
1189
+ // Shown, unless the property is what hides it, as replay checks it.
1190
+ if (!["display", "visibility", "opacity", "content-visibility", "height", "max-height", "width", "max-width", "transform", "clip-path", "clip"].includes(property.toLowerCase()) && !(await element.isVisible())) return false;
1191
+ 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);
1152
1192
  if (found === undefined) return false;
1153
1193
  return typeof wanted === "string" ? normalize(found) === wanted : wanted.test(normalize(found));
1154
1194
  }, `${property} to be ${expected}`);
@@ -1176,12 +1216,41 @@ export async function expectEach(container: Locator, values: string[]): Promise<
1176
1216
  }
1177
1217
 
1178
1218
  async function shownLines(target: Locator): Promise<string[]> {
1179
- const element = await target.first().elementHandle({ timeout: 1000 }).catch(() => null);
1219
+ const element = await (await theMatch(target)).elementHandle({ timeout: 1000 }).catch(() => null);
1180
1220
  return element ? lines(element).catch(() => []) : [];
1181
1221
  }
1182
1222
 
1183
- /** The active page's URL contains `expected`, raw, decoded, or with + read as a space. */
1184
- /** The URL contains `expected`; with "excludes", it does not; with "path", its path is exactly `expected`. */
1223
+ /** As replay's urlContains: a path outside the query unless the text names one, and never inside a longer word or number. */
1224
+ function urlContains(url: string, expected: string | RegExp): boolean {
1225
+ const text = typeof expected === "string" ? expected : expected.source;
1226
+ // Cut on the URL as sent: decoded, a "%23" in a query value reads as a fragment; a query value that is a path is no part of the page's own.
1227
+ const asked = /[?=&]/.test(text) ? url : text.includes("/") ? url.replace(/\?[^#]*/, "").replace(/([?&#][^=&#/]*=)[^&#]*(?:\/|%2F)[^&#]*/gi, "$1") : url.replace(/([?&#][^=&#/]*=)[^&#]*(?:\/|%2F)[^&#]*/gi, "$1");
1228
+ // A letter or digit written percent-encoded is part of the word beside it, an encoded "?", "&", "=" or "#" is not; beside a number, no decimal part.
1229
+ const encoded = "%(?!3[Ff]|26|3[Dd]|23)[0-9A-Fa-f]{2}";
1230
+ const before = /^[\p{L}\p{N}]/u.test(text) ? String.raw`(?<![\p{L}\p{N}]|${encoded}${/^\p{N}/u.test(text) ? String.raw`|\p{N}[.,]` : ""})` : "";
1231
+ const after = /[\p{L}\p{N}]$/u.test(text) ? String.raw`(?![\p{L}\p{N}]|${encoded}${/\p{N}$/u.test(text) ? String.raw`|[.,]\p{N}` : ""})` : "";
1232
+ if (typeof expected !== "string") return [asked, decode(asked), decode(asked.replace(/\+/g, "%20"))].some((u) => expected.test(u));
1233
+ const re = new RegExp(`${before}${expected.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}${after}`, "gu");
1234
+ // A text naming a query starts at the URL's own, as replay reads it.
1235
+ const mark = expected.indexOf("?");
1236
+ const hash = expected.indexOf("#");
1237
+ const atQuery = (u: string, at: number) => {
1238
+ const section = u.lastIndexOf("#", at) + 1;
1239
+ const query = u.indexOf("?", section);
1240
+ if (mark >= 0) return query === at + mark;
1241
+ // Its "#" is the URL's own fragment: "#tab=settings" and "/app#tab=settings" name the fragment's fields.
1242
+ if (hash >= 0) return u.indexOf("#") === at + hash;
1243
+ if (!/=/.test(expected) || /^[?&]/.test(expected)) return true;
1244
+ // A field follows a query's "?", else a fragment's "#", or an "&" after either.
1245
+ const start = query >= 0 && query < at ? query : section > 0 ? section - 1 : query;
1246
+ return start >= 0 && start < at && (u[at - 1] === "&" || at - 1 === start) && u.slice(start + 1, at).split("&").every((field) => !/[?#]/.test(field));
1247
+ };
1248
+ // Each part decoded on its own: a "?", "&", "=" or "#" a value encodes stays encoded.
1249
+ const parts = (u: string) => u.replace(/[^?&=#]+/g, (part) => decode(part).replace(/[?&=#]/g, encodeURIComponent));
1250
+ return [asked, parts(asked), parts(asked.replace(/\+/g, "%20"))].some((u) => [...u.matchAll(re)].some((m) => atQuery(u, m.index)));
1251
+ }
1252
+
1253
+ /** The URL contains `expected` (raw, decoded, or with + read as a space); with "excludes", it does not; with "path", its path is exactly `expected`. */
1185
1254
  export async function expectUrl(page: Page, expected: string | RegExp, match?: "excludes" | "path"): Promise<void> {
1186
1255
  said(expected, "the expected URL");
1187
1256
  await poll(async () => {
@@ -1190,8 +1259,8 @@ export async function expectUrl(page: Page, expected: string | RegExp, match?: "
1190
1259
  const path = new URL(url).pathname;
1191
1260
  return [path, decode(path)].some((p) => (typeof expected === "string" ? p === expected : expected.test(p)));
1192
1261
  }
1193
- const holds = [url, decode(url), decode(url.replace(/\+/g, "%20"))].some((u) => contains(u, expected));
1194
- return match === "excludes" ? !holds : holds;
1262
+ const spellings = [url, decode(url), decode(url.replace(/\+/g, "%20"))];
1263
+ return match === "excludes" ? !spellings.some((u) => contains(u, expected)) : urlContains(url, expected);
1195
1264
  }, match === "excludes" ? `URL not containing ${expected} on the active page` : match === "path" ? `URL path ${expected} on the active page` : `URL containing ${expected} on the active page`);
1196
1265
  }
1197
1266
 
@@ -1409,8 +1478,53 @@ function jsonPattern(check: ResponseJsonCheck): RegExp {
1409
1478
  }
1410
1479
  }
1411
1480
 
1412
- const kind = (value: unknown) => value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
1413
- const describe = (value: unknown) => `${kind(value)}${value === null || typeof value !== "object" ? ` ${JSON.stringify(value)}` : ""}`;
1481
+ /**
1482
+ * A number JavaScript cannot hold as written, as a check reads it (an int64
1483
+ * id, 9007199254740991.1, 1e400): a number, written exactly as the API sent
1484
+ * it, so a pattern or a string check never takes it for text and a bound
1485
+ * compares it exactly (found in review). Its digits are no field a JSON
1486
+ * Pointer reaches.
1487
+ */
1488
+ class ExactNumber {
1489
+ readonly #written: string;
1490
+ constructor(written: string) { this.#written = written; }
1491
+ toString(): string { return this.#written; }
1492
+ // As a capture keeps it (parseExact): its digits, so a differs check sees the same object as the same (found in review).
1493
+ toJSON(): string { return this.#written; }
1494
+ }
1495
+
1496
+ /** A decimal as written (`-12.50`, `9.007199254740993e15`), exactly: its sign, its digits and where its point falls before them (0.125 x 10^2). */
1497
+ const decimal = (text: string): { sign: number; digits: string; point: number } | undefined => {
1498
+ const m = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(text.trim());
1499
+ if (!m) return undefined;
1500
+ const all = `${m[2]}${m[3] ?? ""}`;
1501
+ const leading = all.length - all.replace(/^0+/, "").length;
1502
+ const digits = all.slice(leading).replace(/0+$/, "");
1503
+ return { sign: digits === "" ? 0 : m[1] === "-" ? -1 : 1, digits, point: m[2].length - leading + Number(m[4] ?? 0) };
1504
+ };
1505
+
1506
+ /** -1, 0 or 1 as one decimal is below, at or above another, by sign, magnitude and digits: no exponent is ever expanded. */
1507
+ const compareDecimal = (a: NonNullable<ReturnType<typeof decimal>>, b: NonNullable<ReturnType<typeof decimal>>): number => {
1508
+ if (a.sign !== b.sign) return a.sign < b.sign ? -1 : 1;
1509
+ const width = Math.max(a.digits.length, b.digits.length);
1510
+ const [x, y] = [a.digits.padEnd(width, "0"), b.digits.padEnd(width, "0")];
1511
+ const magnitude = a.sign === 0 ? 0 : a.point !== b.point ? (a.point < b.point ? -1 : 1) : x < y ? -1 : x > y ? 1 : 0;
1512
+ return a.sign * magnitude;
1513
+ };
1514
+
1515
+ /** Whether a number parsed is the number written: 9007199254740991.1 is read as 9007199254740991, and 1e400 as Infinity. */
1516
+ const heldAsWritten = (written: string, value: number): boolean => {
1517
+ const [a, b] = [decimal(written), decimal(String(value))];
1518
+ return a !== undefined && b !== undefined && compareDecimal(a, b) === 0;
1519
+ };
1520
+
1521
+ /** JSON as a check reads it: a number JavaScript cannot hold as written, or any integer beyond its safe range (an id an equals check reads by its digits), as an ExactNumber. */
1522
+ const parseChecked = (text: string): unknown =>
1523
+ JSON.parse(text, (_key, value: unknown, context?: { source?: string }) =>
1524
+ typeof value === "number" && context?.source !== undefined && (Math.abs(value) > Number.MAX_SAFE_INTEGER || !heldAsWritten(context.source, value)) ? new ExactNumber(context.source) : value);
1525
+
1526
+ const kind = (value: unknown) => value === null ? "null" : Array.isArray(value) ? "array" : value instanceof ExactNumber ? "number" : typeof value;
1527
+ const describe = (value: unknown) => `${kind(value)}${value instanceof ExactNumber ? ` ${value}` : value === null || typeof value !== "object" ? ` ${JSON.stringify(value)}` : ""}`;
1414
1528
 
1415
1529
  /** The value at a JSON Pointer: own properties and array indexes only, undefined when missing. */
1416
1530
  function at(json: unknown, path: string): unknown {
@@ -1465,7 +1579,7 @@ function checkValue(json: unknown, checks: ResponseJsonCheck[], prefix = ""): st
1465
1579
  // A list, an object or null is compared as its JSON text: [{"sku":"a"}] is the same as itself written out.
1466
1580
  // Keys in any order and any spacing: {"b":2,"a":1} is the same as {"a": 1, "b": 2}.
1467
1581
  const canonical = (v: unknown) => JSON.stringify(v, (_key, x: unknown) => (x && typeof x === "object" && !Array.isArray(x) ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) : x));
1468
- const written = (text: unknown) => { try { return canonical(JSON.parse(String(text))); } catch { return String(text); } };
1582
+ const written = (text: unknown) => { try { return canonical(parseChecked(String(text))); } catch { return String(text); } };
1469
1583
  if (value === other || (check.type === undefined && (value !== null && typeof value === "object" ? canonical(value) === written(other) : String(value) === other))) return `${field}: expected a value other than ${describe(other)}, got the same`;
1470
1584
  } else if (check.pattern !== undefined) {
1471
1585
  const re = jsonPattern(check);
@@ -1474,22 +1588,46 @@ function checkValue(json: unknown, checks: ResponseJsonCheck[], prefix = ""): st
1474
1588
  } else if (check.min !== undefined || check.max !== undefined) {
1475
1589
  const min = check.min === undefined ? undefined : jsonNumber(check, "min");
1476
1590
  const max = check.max === undefined ? undefined : jsonNumber(check, "max");
1477
- const bounds = [min !== undefined ? `at least ${min}` : "", max !== undefined ? `at most ${max}` : ""].filter(Boolean).join(" and ");
1478
- if (typeof value !== "number") return `${field}: expected a number ${bounds}, got ${got}`;
1479
- if ((min !== undefined && value < min) || (max !== undefined && value > max)) return `${field}: expected a number ${bounds}, got ${value}`;
1591
+ // Each bound as written when it reads exactly: "9007199254740993" is no 9007199254740992.
1592
+ const shown = (written: string, read: number) => (decimal(written) ? written.trim() : read);
1593
+ const bounds = [min !== undefined ? `at least ${shown(check.min!, min)}` : "", max !== undefined ? `at most ${shown(check.max!, max)}` : ""].filter(Boolean).join(" and ");
1594
+ const number = value instanceof ExactNumber ? Number(String(value)) : value;
1595
+ if (typeof number !== "number") return `${field}: expected a number ${bounds}, got ${got}`;
1596
+ // Compared exactly, the value as the API wrote it and the bound as the check does, never rounded onto each
1597
+ // other beyond JavaScript's precision (found in review); a bound in another notation (0x10) as a number.
1598
+ const exact = decimal(String(value));
1599
+ const beyond = (written: string, read: number, side: number) => {
1600
+ const bound = decimal(written);
1601
+ return exact && bound ? compareDecimal(exact, bound) === side : side < 0 ? number < read : number > read;
1602
+ };
1603
+ const under = min !== undefined && beyond(check.min!, min, -1);
1604
+ const over = max !== undefined && beyond(check.max!, max, 1);
1605
+ if (under || over) return `${field}: expected a number ${bounds}, got ${value}`;
1480
1606
  } else {
1481
1607
  const expected = jsonExpected(check);
1482
- if (value !== expected) return `${field}: expected ${describe(expected)}, got ${got}`;
1608
+ // Too large to compare as a number, it is checked as a string of its digits (jsonExpected says so).
1609
+ const same = value instanceof ExactNumber ? (check.type === undefined || check.type === "string") && String(value) === expected : value === expected;
1610
+ if (!same) return `${field}: expected ${describe(expected)}, got ${got}`;
1483
1611
  }
1484
1612
  }
1485
1613
  return undefined;
1486
1614
  }
1487
1615
 
1616
+ /**
1617
+ * JSON with an integer beyond JavaScript's precision (a snowflake or int64
1618
+ * id) kept as the digits the API sent, never rounded into another id, as a
1619
+ * capture keeps it: a differs check then sees the same id (found in review).
1620
+ */
1621
+ export function parseExact(text: string): unknown {
1622
+ return JSON.parse(text, (_key, value: unknown, context?: { source?: string }) =>
1623
+ typeof value === "number" && Number.isInteger(value) && !Number.isSafeInteger(value) && context?.source !== undefined ? context.source : value);
1624
+ }
1625
+
1488
1626
  /** A missing property is different from a property whose value is null. */
1489
1627
  export function checkResponseJson(body: string | undefined, checks: ResponseJsonCheck[]): string | undefined {
1490
1628
  if (body === undefined) return "response body is pending, unreadable or not a supported text content type";
1491
1629
  let json: unknown;
1492
- try { json = JSON.parse(body); } catch { return "response body is not valid JSON"; }
1630
+ try { json = parseChecked(body); } catch { return "response body is not valid JSON"; }
1493
1631
  return checkValue(json, checks);
1494
1632
  }
1495
1633