saffron-ai 1.3.3 → 1.3.5
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/CHANGELOG.md +318 -0
- package/dist-pkg/cli.js +420 -414
- package/package.json +1 -1
- package/skills/saffron/SKILL.md +4 -3
- package/skills/saffron/references/config.md +1 -1
- package/skills/saffron/references/syntax.md +16 -0
- package/templates/playwright/saffron-helpers.ts +219 -23
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "saffron-ai",
|
|
3
|
-
"version": "1.3.
|
|
3
|
+
"version": "1.3.5",
|
|
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",
|
package/skills/saffron/SKILL.md
CHANGED
|
@@ -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.
|
|
6
|
+
saffron-ai: "1.3.5"
|
|
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.
|
|
13
|
+
This skill describes saffron-ai 1.3.5 (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
|
|
@@ -399,6 +399,7 @@ Use Saffron itself first: `{date...}` tokens (ranges and locales included), capt
|
|
|
399
399
|
outlines, secrets, dates, network waits, page furniture, StepSets.
|
|
400
400
|
- [Configuration & CI](references/config.md): `saffron.config.json`,
|
|
401
401
|
flags, `--strict`, cross-browser and browser matrix, devices, workers
|
|
402
|
-
and agent workers
|
|
402
|
+
and agent workers (`@serial` keeps scenarios that share data apart),
|
|
403
|
+
heal model, secrets setup, the API settings.
|
|
403
404
|
- [API tests](references/api.md): `@api` scenarios, the pinned contract,
|
|
404
405
|
writing and reviewing request steps, API calls from a browser scenario.
|
|
@@ -64,7 +64,7 @@ your-project/
|
|
|
64
64
|
| `device` / `viewport` | A Playwright device profile (`"iPhone 15"`) and/or a `"WIDTHxHEIGHT"` size for every scenario; a desktop recording replays under it or fails at the step that differs |
|
|
65
65
|
| `timezone` | IANA zone (`"Europe/Berlin"`) the browser runs in and `{date...}` tokens count days in (default: the machine's) |
|
|
66
66
|
| `dateLocale` | Locale of month and weekday names in `{date...}` tokens that name none (default `en-US`) |
|
|
67
|
-
| `workers` | Parallel replay workers |
|
|
67
|
+
| `workers` | Parallel replay workers; scenarios tagged `@serial` or `@serial:<name>` still run one at a time per name |
|
|
68
68
|
| `agentWorkers` | Agent sessions (record, heal) that may run at once, each in its own browser (default 1; each is a paid session) |
|
|
69
69
|
| `shardBy` | How `--shard` splits the suite: `"scenario"` (default) or `"file"` (each feature file on one machine) |
|
|
70
70
|
| `provider` | Whose agent records and heals, on its login on this machine: `claude` (default), `codex` (ChatGPT plan), `antigravity` (Google AI Pro/Ultra via the `agy` CLI, experimental), `cursor`. Also `--provider` |
|
|
@@ -322,6 +322,22 @@ Scenario: ...
|
|
|
322
322
|
tags means `or`; once `and`, `not` or a parenthesis appears, join every
|
|
323
323
|
tag with `and` or `or`. The `@` may be left out.
|
|
324
324
|
|
|
325
|
+
Tags that change how a scenario runs:
|
|
326
|
+
|
|
327
|
+
| Tag | Effect |
|
|
328
|
+
|-----|--------|
|
|
329
|
+
| `@api` | An HTTP API test, with no browser ([API tests](api.md)) |
|
|
330
|
+
| `@side-effects` | It changes the app's data; `run_plan` counts how often it runs |
|
|
331
|
+
| `@serial` | Never runs at the same time as another `@serial` scenario |
|
|
332
|
+
| `@serial:<name>` | Never runs at the same time as another scenario with that name (`@serial:rooms`); any case, and commas give several (`@serial:rooms,users`) |
|
|
333
|
+
|
|
334
|
+
`@serial` holds across workers, the record and heal phases, a heal's proof
|
|
335
|
+
replays of an Outline's other rows, and `--shard` (one name's scenarios go to
|
|
336
|
+
one machine). `saffron eject` writes `workers: 1` into the Playwright config it
|
|
337
|
+
creates for such a suite. Tag the scenarios that share data the app keeps
|
|
338
|
+
(one account, one booking slot) instead of running the whole suite with
|
|
339
|
+
`--workers 1`.
|
|
340
|
+
|
|
325
341
|
## A complete file
|
|
326
342
|
|
|
327
343
|
How the pieces fit in one project. The shared sign-in lives in a
|
|
@@ -12,7 +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 { expect, test, type APIResponse, type Browser, type BrowserContext, type Dialog, type Download, type ElementHandle, type Locator, type Page, type Request, type Response } from "@playwright/test";
|
|
15
|
+
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
16
|
|
|
17
17
|
const SETTINGS: {
|
|
18
18
|
/** Locale and time zone {date...} tokens are written in. */
|
|
@@ -151,11 +151,19 @@ async function resolvesLinkLocal(hostname: string): Promise<boolean> {
|
|
|
151
151
|
/** A number or boolean a request body sends where the recording holds text with tokens (a row's "<seats>"). */
|
|
152
152
|
export function typed(text: string, type: "number" | "boolean" | "json"): unknown {
|
|
153
153
|
if (type === "json") {
|
|
154
|
+
let unexact: string | undefined;
|
|
155
|
+
let parsed: unknown;
|
|
154
156
|
try {
|
|
155
|
-
|
|
157
|
+
// A number not held as written (an int64 id) would be sent rounded to another one, as replay refuses it.
|
|
158
|
+
parsed = JSON.parse(text, (_key, value: unknown, context?: { source?: string }) => {
|
|
159
|
+
if (typeof value === "number" && context?.source !== undefined && !heldAsWritten(context.source, value)) unexact ??= context.source;
|
|
160
|
+
return value;
|
|
161
|
+
});
|
|
156
162
|
} catch {
|
|
157
163
|
throw new Error("a body part must be JSON, but its value resolves to text that is not: give the column a whole JSON value");
|
|
158
164
|
}
|
|
165
|
+
if (unexact !== undefined) throw new Error(`a body part holds ${mask(unexact)}, which cannot be sent exactly as a JSON number; send it as a string`);
|
|
166
|
+
return parsed;
|
|
159
167
|
}
|
|
160
168
|
if (type === "boolean") {
|
|
161
169
|
if (text === "true" || text === "false") return text === "true";
|
|
@@ -164,11 +172,12 @@ export function typed(text: string, type: "number" | "boolean" | "json"): unknow
|
|
|
164
172
|
// A decimal number as JSON writes one, as replay reads it: "Infinity" would be sent as null, "0x1F" as 31.
|
|
165
173
|
const number = Number(text);
|
|
166
174
|
if (!/^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(text) || !Number.isFinite(number)) throw new Error(`a body field must be a number, but its value resolves to ${JSON.stringify(mask(text))}`);
|
|
175
|
+
if (!heldAsWritten(text, number)) throw new Error(`a body field holds ${mask(text)}, which cannot be sent exactly as a JSON number; send it as a string`);
|
|
167
176
|
return number;
|
|
168
177
|
}
|
|
169
178
|
|
|
170
179
|
/** A check's expected text must say something: "" is in every text. */
|
|
171
|
-
function said<T extends string | RegExp>(expected: T, what: string): T {
|
|
180
|
+
export function said<T extends string | RegExp>(expected: T, what: string): T {
|
|
172
181
|
if (typeof expected === "string" ? normalize(expected) === "" : expected.source === "" || expected.source === "(?:)") throw new Error(`${what} is blank, so it would hold for anything`);
|
|
173
182
|
return expected;
|
|
174
183
|
}
|
|
@@ -178,10 +187,32 @@ export function projectFile(file: string): string {
|
|
|
178
187
|
return path.resolve(path.dirname(test.info().file), SETTINGS.projectRoot, file);
|
|
179
188
|
}
|
|
180
189
|
|
|
190
|
+
/**
|
|
191
|
+
* A file the page may receive, as replay allows one: inside the project by
|
|
192
|
+
* its real path (a link out of it is out), never a dotfile (.env holds every
|
|
193
|
+
* secret), a single file, never a folder (found in review).
|
|
194
|
+
*/
|
|
195
|
+
export function uploadFile(file: string): string {
|
|
196
|
+
const root = path.resolve(path.dirname(test.info().file), SETTINGS.projectRoot);
|
|
197
|
+
const full = path.resolve(root, file);
|
|
198
|
+
const inside = (base: string, p: string) => { const rel = path.relative(base, p); return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel : undefined; };
|
|
199
|
+
const rel = inside(root, full);
|
|
200
|
+
if (rel === undefined) throw new Error(`${file} is outside the project; uploads come from files inside it`);
|
|
201
|
+
if (rel.split(path.sep).some((seg) => seg.startsWith("."))) throw new Error(`${file} is a hidden file; a Saffron test does not upload dotfiles`);
|
|
202
|
+
if (!fs.existsSync(full)) throw new Error(`${file} does not exist; uploads come from files inside the project`);
|
|
203
|
+
const real = inside(fs.realpathSync(root), fs.realpathSync(full));
|
|
204
|
+
if (real === undefined) throw new Error(`${file} is outside the project; uploads come from files inside it`);
|
|
205
|
+
// A link to .env is .env (found in review): the real path is judged too, and a hard link refused.
|
|
206
|
+
if (real.split(path.sep).some((seg) => seg.startsWith("."))) throw new Error(`${file} is a hidden file; a Saffron test does not upload dotfiles`);
|
|
207
|
+
if (fs.statSync(full).isDirectory()) throw new Error(`${file} is a folder; a Saffron test uploads single files only`);
|
|
208
|
+
if (fs.statSync(full).nlink > 1) throw new Error(`${file} is a hard link (the same file under another name, perhaps a hidden one such as .env); copy the file instead`);
|
|
209
|
+
return full;
|
|
210
|
+
}
|
|
211
|
+
|
|
181
212
|
const LETTER = String.raw`[\p{L}\p{N}\p{M}]`;
|
|
182
213
|
// A script written without spaces (Chinese, Japanese, Thai...): an edge of it is not bounded, as in replay, but for
|
|
183
214
|
// 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;
|
|
215
|
+
const SPACELESS = /(?!\p{N})[\p{sc=Han}\p{sc=Hiragana}\p{sc=Katakana}\p{sc=Thai}\p{sc=Lao}\p{sc=Khmer}\p{sc=Myanmar}]/u;
|
|
185
216
|
const NEGATING = "无法|無法|不能|没有|沒有|未能|ไม่ได้|不|未|非|無|无|没|沒|ไม่";
|
|
186
217
|
|
|
187
218
|
/**
|
|
@@ -190,20 +221,26 @@ const NEGATING = "无法|無法|不能|没有|沒有|未能|ไม่ได้|
|
|
|
190
221
|
* the step wrote, a zero decimal part may follow ("$10" is in "$10.00", not
|
|
191
222
|
* "$10.50"); after a row or data value (`rows` "end"), none.
|
|
192
223
|
*/
|
|
193
|
-
export function bounded(text: string, edges: "start" | "end" | "both", flags = "u", rows: "" | "end" = ""): RegExp {
|
|
224
|
+
export function bounded(text: string, edges: "start" | "end" | "both", flags = "u", rows: "" | "end" = "", grouped = true): RegExp {
|
|
194
225
|
text = said(normalize(text), "the expected text");
|
|
195
226
|
const first = [...text][0];
|
|
196
227
|
// An amount ("$5.00") is never the negative one after a minus ("-$5.00"), as replay reads it.
|
|
197
228
|
const amount = /^\p{Sc}\s?\p{N}/u.test(text);
|
|
198
229
|
const start = edges !== "end" && (amount || (new RegExp(`^${LETTER}`, "u").test(text) && !(SPACELESS.test(first) && new RegExp(`^(?:${NEGATING})`, "u").test(text))));
|
|
199
230
|
const end = edges !== "start" && new RegExp(`${LETTER}$`, "u").test(text) && !SPACELESS.test([...text].at(-1)!);
|
|
200
|
-
|
|
201
|
-
|
|
231
|
+
// Thousands grouped by a space or an apostrophe ("1 250 kr") are one number, and a currency symbol after a letter ("R$") another currency, as replay reads them.
|
|
232
|
+
// Not for "not shown" (grouped false): there a number that might run on into the next ("15 128") counts as shown.
|
|
233
|
+
const group = "[\\x20\\u00a0\\u202f\\u2007\\u2009\\u200a\\u0027\\u2019]";
|
|
234
|
+
// For "not shown", only a decimal point joins two numbers: "2" counts as shown in "1,2,3", as replay reads it.
|
|
235
|
+
const point = grouped ? "[.,\\u066b\\u066c]" : "[.\\u066b]";
|
|
236
|
+
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})`;
|
|
202
239
|
// Quotes and `>` as hex, so Playwright reads no string or chain in the regex; any whitespace as replay's label match allows.
|
|
203
240
|
const body = escapeRegExp(text).replace(/ /g, "\\s+").replace(/["'`>]/g, (c) => `\\x${c.charCodeAt(0).toString(16)}`);
|
|
204
241
|
// After a number's point or comma ("$10."), no more digits, as replay reads it.
|
|
205
|
-
const
|
|
206
|
-
return new RegExp(`${start ? before : ""}${body}${end ? after :
|
|
242
|
+
const pointEnd = /\p{N}[.,\u066b\u066c]$/u.test(text) ? "(?!\\p{N})" : "";
|
|
243
|
+
return new RegExp(`${start ? before : ""}${body}${end ? after : pointEnd}`, flags);
|
|
207
244
|
}
|
|
208
245
|
|
|
209
246
|
const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
@@ -384,6 +421,10 @@ const decode = (url: string) => {
|
|
|
384
421
|
}
|
|
385
422
|
};
|
|
386
423
|
|
|
424
|
+
/** 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
|
+
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)));
|
|
427
|
+
|
|
387
428
|
function statusMatches(observed: number, expected?: string): boolean {
|
|
388
429
|
if (!expected) return observed >= 200 && observed < 300;
|
|
389
430
|
const cls = /^([1-5])xx$/i.exec(expected.trim());
|
|
@@ -587,7 +628,11 @@ export class Run {
|
|
|
587
628
|
|
|
588
629
|
/** A recorded URL under the base URL, as Saffron joins them (a base path is kept). */
|
|
589
630
|
url(recorded: string): string {
|
|
590
|
-
|
|
631
|
+
const url = this.join(recorded, this.baseURL, `relative navigation "${recorded}" needs a baseURL in playwright.config.ts`);
|
|
632
|
+
// A web page only, as replay opens: never data:, file: or javascript: (found in review).
|
|
633
|
+
const scheme = (() => { try { return new URL(url).protocol; } catch { return ""; } })();
|
|
634
|
+
if (!/^localhost(:\d+)?(\/|$)/i.test(url) && url !== "about:blank" && !/^https?:$/.test(scheme)) throw new Error(`${mask(url)} is not a web page; a Saffron test only opens http(s) URLs`);
|
|
635
|
+
return url;
|
|
591
636
|
}
|
|
592
637
|
|
|
593
638
|
private join(recorded: string, baseURL: string | undefined, orElse: string): string {
|
|
@@ -730,7 +775,35 @@ export class Run {
|
|
|
730
775
|
const chooser = this.page.waitForEvent("filechooser", { timeout: SETTINGS.timeoutMs });
|
|
731
776
|
chooser.catch(() => undefined); // the action's own error comes first
|
|
732
777
|
await action();
|
|
733
|
-
await (await chooser).setFiles(files.map(
|
|
778
|
+
await (await chooser).setFiles(files.map(uploadFile));
|
|
779
|
+
}
|
|
780
|
+
|
|
781
|
+
/**
|
|
782
|
+
* Nothing the recording names is shown, in the page and (`ownFrames`) the app's own frames that are shown, once
|
|
783
|
+
* open requests are answered and the hidden state has held for half a second, as replay checks a "not shown":
|
|
784
|
+
* an error drawn 300 ms after the click is shown (found in the 1.3.5 review).
|
|
785
|
+
*/
|
|
786
|
+
async expectNotShown(build: (root: Page | Frame) => Locator[], ownFrames = true): Promise<void> {
|
|
787
|
+
await this.lane.net.quiet(Math.min(SETTINGS.timeoutMs / 2, 3000));
|
|
788
|
+
const settle = Math.min(500, SETTINGS.timeoutMs / 4);
|
|
789
|
+
let since: number | undefined;
|
|
790
|
+
await expect
|
|
791
|
+
.poll(
|
|
792
|
+
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
|
+
}
|
|
800
|
+
}
|
|
801
|
+
since ??= Date.now();
|
|
802
|
+
return Date.now() - since >= settle;
|
|
803
|
+
},
|
|
804
|
+
{ message: "every match of every recorded locator to be hidden, and to stay hidden", timeout: SETTINGS.timeoutMs + settle },
|
|
805
|
+
)
|
|
806
|
+
.toBe(true);
|
|
734
807
|
}
|
|
735
808
|
|
|
736
809
|
/** The text `target` shows, once open requests are answered and the text has held for half a second. */
|
|
@@ -795,7 +868,7 @@ export class Run {
|
|
|
795
868
|
problem = "problem" in verdict ? verdict.problem : undefined;
|
|
796
869
|
if (!("differ" in verdict) || !verdict.differ) return false;
|
|
797
870
|
// The element must still be one the target names.
|
|
798
|
-
return target.evaluateAll((els, el) => els.includes(el as
|
|
871
|
+
return target.evaluateAll((els, el) => els.includes(el as HTMLElement), element).catch(() => false);
|
|
799
872
|
}, { message: `target text to differ from "${compareTo}" (${right})`, timeout: SETTINGS.timeoutMs })
|
|
800
873
|
.toBe(true)
|
|
801
874
|
.catch((err) => {
|
|
@@ -819,7 +892,7 @@ export class Run {
|
|
|
819
892
|
() =>
|
|
820
893
|
(kind === "check" ? net.sinceAction() : net.sincePreviousStep()).some(
|
|
821
894
|
(e) =>
|
|
822
|
-
(url
|
|
895
|
+
(rawUrlMatch(url, e.url) || url.test(decode(e.url))) &&
|
|
823
896
|
(!match.method || e.method.toUpperCase() === match.method.toUpperCase()) &&
|
|
824
897
|
statusMatches(e.status, match.status) &&
|
|
825
898
|
(!match.json || masked(() => checkResponseJson(e.body, match.json!)) === undefined) &&
|
|
@@ -982,7 +1055,12 @@ export class Run {
|
|
|
982
1055
|
}
|
|
983
1056
|
const value = at(parsed, pointer);
|
|
984
1057
|
if (value === undefined) throw new Error(mask(`${method} ${url}: the response has no ${pointer || "/"} to extract as "${name}"${excerpt(exchange.body)}`));
|
|
985
|
-
|
|
1058
|
+
// A list or object keeps its numbers as the API wrote them, numbers still, as replay keeps them (found in the 1.3.5 review).
|
|
1059
|
+
const raw = (JSON as unknown as { rawJSON(source: string): unknown }).rawJSON;
|
|
1060
|
+
const kept = value !== null && typeof value === "object" && !(value instanceof ExactNumber)
|
|
1061
|
+
? JSON.stringify(at(JSON.parse(exchange.body ?? "", (_key, v: unknown, context?: { source?: string }) => (typeof v === "number" && context?.source !== undefined ? raw(context.source) : v)), pointer))
|
|
1062
|
+
: JSON.stringify(value);
|
|
1063
|
+
this.vars.set(name, typeof value === "string" ? value : kept);
|
|
986
1064
|
}
|
|
987
1065
|
}
|
|
988
1066
|
|
|
@@ -1203,6 +1281,20 @@ export async function expectNotVisible(...targets: Locator[]): Promise<void> {
|
|
|
1203
1281
|
}, `every match of every recorded locator to be hidden (${targets.length} locator(s))`);
|
|
1204
1282
|
}
|
|
1205
1283
|
|
|
1284
|
+
async function shownOwnFrames(page: Page): Promise<Frame[]> {
|
|
1285
|
+
const origin = (url: string) => { try { return new URL(url).origin; } catch { return undefined; } };
|
|
1286
|
+
const own = origin(page.mainFrame().url());
|
|
1287
|
+
const frames: Frame[] = [];
|
|
1288
|
+
for (const frame of page.frames()) {
|
|
1289
|
+
if (frame === page.mainFrame() || !(/^about:(?:srcdoc|blank)$|^$/.test(frame.url()) || origin(frame.url()) === own)) continue;
|
|
1290
|
+
const element = await frame.frameElement().catch(() => undefined);
|
|
1291
|
+
const box = element && (await element.isVisible().catch(() => false)) ? await element.boundingBox().catch(() => null) : null;
|
|
1292
|
+
await element?.dispose().catch(() => {});
|
|
1293
|
+
if (box && box.width > 1 && box.height > 1 && box.x + box.width > 0 && box.y + box.height > 0) frames.push(frame);
|
|
1294
|
+
}
|
|
1295
|
+
return frames;
|
|
1296
|
+
}
|
|
1297
|
+
|
|
1206
1298
|
/** Each value is shown in the container, as a whole line of its text. */
|
|
1207
1299
|
export async function expectEach(container: Locator, values: string[]): Promise<void> {
|
|
1208
1300
|
let missing = values;
|
|
@@ -1221,16 +1313,23 @@ async function shownLines(target: Locator): Promise<string[]> {
|
|
|
1221
1313
|
}
|
|
1222
1314
|
|
|
1223
1315
|
/** 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 {
|
|
1316
|
+
export function urlContains(url: string, expected: string | RegExp): boolean {
|
|
1225
1317
|
const text = typeof expected === "string" ? expected : expected.source;
|
|
1226
1318
|
// 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
1319
|
const asked = /[?=&]/.test(text) ? url : text.includes("/") ? url.replace(/\?[^#]*/, "").replace(/([?&#][^=&#/]*=)[^&#]*(?:\/|%2F)[^&#]*/gi, "$1") : url.replace(/([?&#][^=&#/]*=)[^&#]*(?:\/|%2F)[^&#]*/gi, "$1");
|
|
1228
1320
|
// 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
1321
|
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
1322
|
if (typeof expected !== "string") return [asked, decode(asked), decode(asked.replace(/\+/g, "%20"))].some((u) => expected.test(u));
|
|
1233
|
-
|
|
1323
|
+
// A word starts as it ends: not after a letter (a digit, for a number) and "-", "_", "~" or "+", as replay reads it.
|
|
1324
|
+
// In the query and fragment, "+" and a space separate words ("shoes" is in "?q=red+shoes"); in the path they join them.
|
|
1325
|
+
const bounds = (sep: string, sepEnd: string) => [
|
|
1326
|
+
/^[\p{L}\p{N}]/u.test(text) ? String.raw`(?<![\p{L}\p{N}]|${encoded}|(?:[\p{L}\p{M}]|${encoded})${sep}+${/^\p{N}/u.test(text) ? String.raw`|\p{N}[.,]|\p{N}${sep}+` : ""})` : "",
|
|
1327
|
+
/[\p{L}\p{N}]$/u.test(text) ? String.raw`(?![\p{L}\p{N}]|${encoded}|${sepEnd}+(?:[\p{L}\p{N}]|${encoded})|:\p{L}${/\p{N}$/u.test(text) ? String.raw`|[.,]\p{N}` : ""})` : "",
|
|
1328
|
+
];
|
|
1329
|
+
const word = (sep: string, sepEnd: string) => { const [before, after] = bounds(sep, sepEnd); return new RegExp(`${before}${expected.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}${after}`, "gu"); };
|
|
1330
|
+
const re = word("[-_~+ ]", "[-._~+ ]");
|
|
1331
|
+
const spaced = word("[-_~]", "[-._~]");
|
|
1332
|
+
const inQuery = (u: string, at: number) => { const q = u.search(/[?#]/); return q >= 0 && at > q; };
|
|
1234
1333
|
// A text naming a query starts at the URL's own, as replay reads it.
|
|
1235
1334
|
const mark = expected.indexOf("?");
|
|
1236
1335
|
const hash = expected.indexOf("#");
|
|
@@ -1247,7 +1346,7 @@ function urlContains(url: string, expected: string | RegExp): boolean {
|
|
|
1247
1346
|
};
|
|
1248
1347
|
// Each part decoded on its own: a "?", "&", "=" or "#" a value encodes stays encoded.
|
|
1249
1348
|
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)));
|
|
1349
|
+
return [asked, parts(asked), parts(asked.replace(/\+/g, "%20"))].some((u) => [...u.matchAll(re)].some((m) => atQuery(u, m.index)) || [...u.matchAll(spaced)].some((m) => inQuery(u, m.index) && atQuery(u, m.index)));
|
|
1251
1350
|
}
|
|
1252
1351
|
|
|
1253
1352
|
/** The URL contains `expected` (raw, decoded, or with + read as a space); with "excludes", it does not; with "path", its path is exactly `expected`. */
|
|
@@ -1330,6 +1429,56 @@ export function parseAmount(text: string): number | undefined {
|
|
|
1330
1429
|
const amountUnit = (text: string): string =>
|
|
1331
1430
|
joinGroups(text).replace(/[-\u2212\u2013]?\d(?:[\d.,]*\d)?/, " ").replace(/[()\-\u2212\u2013]/g, " ").replace(/\s+/g, " ").trim().toLowerCase();
|
|
1332
1431
|
|
|
1432
|
+
/**
|
|
1433
|
+
* The currency an amount names, as a kind and its spelling: an ISO code
|
|
1434
|
+
* ("NOK") or a symbol ("€"); undefined for none or a local notation ("kr").
|
|
1435
|
+
* Two of the same kind that differ are two currencies; a symbol against a
|
|
1436
|
+
* code ("$5" and "USD 5") is not judged.
|
|
1437
|
+
*/
|
|
1438
|
+
export function amountCurrency(text: string): { kind: "code" | "symbol"; is: string; loose?: true } | undefined {
|
|
1439
|
+
// A code right beside the number ("NOK 150", "150 NOK", "EUR (150)"), in capitals first: "Top up" and "Pay all" are words,
|
|
1440
|
+
// not TOP or ALL. A word beside it that is no currency ("NET 150 EUR") is passed over, and "150 eur" still counts (found in review).
|
|
1441
|
+
const beside = (flags: string) => [...text.matchAll(new RegExp("(?<![A-Za-z])([A-Za-z]{3})\\s?[-\u2212\u2013(]?\\s?\\d|\\d[\\d.,\\s\u00a0\u202f')]*?(?:[.,:]?-)?\\s?([A-Za-z]{3})(?![A-Za-z])", flags))]
|
|
1442
|
+
.map((m) => m[1] ?? m[2])
|
|
1443
|
+
.find((word) => (flags.includes("i") || word === word.toUpperCase()) && currencies.has(word.toUpperCase()));
|
|
1444
|
+
// A symbol before a lowercase word: "€150 all" is in euros, not in ALL (found in review).
|
|
1445
|
+
const upper = beside("gu");
|
|
1446
|
+
if (upper) return { kind: "code", is: upper };
|
|
1447
|
+
// A dollar its letters name ("US$15", "CA$15", "R$ 15") is that dollar, never any (found in review).
|
|
1448
|
+
const named = /(?<![A-Za-z])([A-Z]{1,3})\$/.exec(text)?.[0];
|
|
1449
|
+
if (named && SYMBOL_CODES[named]) return { kind: "symbol", is: named };
|
|
1450
|
+
const symbol = /\p{Sc}+/u.exec(text)?.[0];
|
|
1451
|
+
if (symbol) return { kind: "symbol", is: symbol };
|
|
1452
|
+
// A local notation ("100 kr", "Rs. 500", "5,00 zł") is one too, by its spelling: "kr" is never "€" (found in review).
|
|
1453
|
+
// Only beside the number: "Din saldo: 150 kr" is in kr, its "Din" ("your") no dinar.
|
|
1454
|
+
const local = [...text.toLowerCase().matchAll(/(?<!\p{L})(\p{L}+)\.?\s?[-\u2212\u2013]?\d|\d[\d.,\s\u00a0\u202f']*?(?:[.,:]?-)?\s?(\p{L}+)(?!\p{L})/gu)].map((m) => m[1] ?? m[2]).find((word) => LOCAL_CURRENCIES.has(word));
|
|
1455
|
+
if (local) return { kind: "symbol", is: local };
|
|
1456
|
+
// A lowercase word ("150 eur", but also "Top 10", "try 10") is judged against codes only, never a symbol.
|
|
1457
|
+
const iso = beside("giu");
|
|
1458
|
+
return iso ? { kind: "code", is: iso.toUpperCase(), loose: true } : undefined;
|
|
1459
|
+
}
|
|
1460
|
+
|
|
1461
|
+
/** The codes a symbol can stand for; a symbol not listed ("kr" is no symbol) is compared by its spelling. */
|
|
1462
|
+
const SYMBOL_CODES: Record<string, string[]> = {
|
|
1463
|
+
"€": ["EUR"], "£": ["GBP", "EGP", "GIP", "FKP", "SHP", "SYP", "LBP", "SDG", "SSP"], "₹": ["INR"], "₩": ["KRW", "KPW"], "₺": ["TRY"], "₽": ["RUB"], "₪": ["ILS"], "₫": ["VND"], "₱": ["PHP"], "₴": ["UAH"], "฿": ["THB"], "₦": ["NGN"], "₲": ["PYG"], "₸": ["KZT"], "₾": ["GEL"], "₼": ["AZN"],
|
|
1464
|
+
"$": ["USD", "CAD", "AUD", "NZD", "SGD", "HKD", "MXN", "ARS", "CLP", "COP", "TWD", "BRL", "UYU", "JMD", "TTD", "BBD", "BSD", "BZD", "BMD", "KYD", "XCD", "FJD", "SBD", "LRD", "NAD", "GYD", "SRD", "BND", "ZWL", "TVD", "KID", "CUP", "DOP", "MOP", "NIO", "TOP", "WST", "CVE"],
|
|
1465
|
+
"US$": ["USD"], "CA$": ["CAD"], "C$": ["CAD", "NIO"], "A$": ["AUD"], "AU$": ["AUD"], "NZ$": ["NZD"], "HK$": ["HKD"], "S$": ["SGD"], "R$": ["BRL"], "NT$": ["TWD"], "RD$": ["DOP"], "MX$": ["MXN"], "MOP$": ["MOP"], "T$": ["TOP"], "WS$": ["WST"],
|
|
1466
|
+
"¥": ["JPY", "CNY"], "¥": ["JPY", "CNY"], "¢": ["USD", "CAD", "GHS"],
|
|
1467
|
+
};
|
|
1468
|
+
|
|
1469
|
+
/** Whether two currencies differ ("NOK" and "EUR", "$" and "€", "$" and "NOK"); "$" and "USD" or "US$" may be one. */
|
|
1470
|
+
export function otherCurrency(a: ReturnType<typeof amountCurrency>, b: ReturnType<typeof amountCurrency>): boolean {
|
|
1471
|
+
if (a === undefined || b === undefined) return false;
|
|
1472
|
+
if (a.kind === "code" && b.kind === "code") return a.is !== b.is;
|
|
1473
|
+
// A lowercase word read as a code is judged against codes only.
|
|
1474
|
+
if (a.loose || b.loose) return false;
|
|
1475
|
+
// A symbol stands for its codes: "$5" may be USD 5 or US$ 5, never EUR 5 or € 5 (found in review).
|
|
1476
|
+
const codes = (c: NonNullable<typeof a>) => (c.kind === "code" ? [c.is] : SYMBOL_CODES[c.is]);
|
|
1477
|
+
const [x, y] = [codes(a), codes(b)];
|
|
1478
|
+
if (x === undefined || y === undefined) return a.kind === b.kind && a.is !== b.is;
|
|
1479
|
+
return !x.some((code) => y.includes(code));
|
|
1480
|
+
}
|
|
1481
|
+
|
|
1333
1482
|
/**
|
|
1334
1483
|
* Whether two displayed values differ, for an expectDiffers check. Two
|
|
1335
1484
|
* amounts compare as numbers ("NOK 1 295" and "NOK 1,295.00" are equal), and
|
|
@@ -1447,6 +1596,11 @@ export function jsonExpected(check: ResponseJsonCheck, text: string | undefined
|
|
|
1447
1596
|
if (typeof value === "number" && Number.isInteger(value) && !Number.isSafeInteger(value)) {
|
|
1448
1597
|
throw new Error(`JSON field ${JSON.stringify(check.path)}: ${text} is too large to compare exactly as a number; check it as a string`);
|
|
1449
1598
|
}
|
|
1599
|
+
// A decimal with more digits than a double holds ("0.10000000000000001") reads as another one (0.1) (found in review).
|
|
1600
|
+
const digits = (n: string) => n.replace(/[eE].*$/, "").replace(/\D/g, "").replace(/^0+|0+$/g, "");
|
|
1601
|
+
if (typeof value === "number" && Number.isFinite(value) && digits(text!.trim()) !== digits(String(value).replace(/^-/, ""))) {
|
|
1602
|
+
throw new Error(`JSON field ${JSON.stringify(check.path)}: ${text} has more digits than a number holds exactly; check it as a string or with fewer digits`);
|
|
1603
|
+
}
|
|
1450
1604
|
if ((check.type === "null" ? value === null : typeof value === check.type) && (typeof value !== "number" || Number.isFinite(value))) return value;
|
|
1451
1605
|
throw new Error(`JSON field ${JSON.stringify(check.path)}: expected value must be a valid ${check.type}`);
|
|
1452
1606
|
}
|
|
@@ -1513,7 +1667,7 @@ const compareDecimal = (a: NonNullable<ReturnType<typeof decimal>>, b: NonNullab
|
|
|
1513
1667
|
};
|
|
1514
1668
|
|
|
1515
1669
|
/** 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 => {
|
|
1670
|
+
export const heldAsWritten = (written: string, value: number): boolean => {
|
|
1517
1671
|
const [a, b] = [decimal(written), decimal(String(value))];
|
|
1518
1672
|
return a !== undefined && b !== undefined && compareDecimal(a, b) === 0;
|
|
1519
1673
|
};
|
|
@@ -1523,6 +1677,32 @@ const parseChecked = (text: string): unknown =>
|
|
|
1523
1677
|
JSON.parse(text, (_key, value: unknown, context?: { source?: string }) =>
|
|
1524
1678
|
typeof value === "number" && context?.source !== undefined && (Math.abs(value) > Number.MAX_SAFE_INTEGER || !heldAsWritten(context.source, value)) ? new ExactNumber(context.source) : value);
|
|
1525
1679
|
|
|
1680
|
+
/**
|
|
1681
|
+
* A JSON body's value at a pointer as a key two values share only when they
|
|
1682
|
+
* are the same JSON: numbers by their exact decimal (0.1 and
|
|
1683
|
+
* 0.10000000000000001 differ, 1 and 1.0 do not), never equal to a string of
|
|
1684
|
+
* the same digits, keys in any order. For a group's `same` check (found in review).
|
|
1685
|
+
*/
|
|
1686
|
+
/** A JSON body's value at a pointer as the API wrote it: 0.10000000000000001 and a 19-digit id are never shown rounded. */
|
|
1687
|
+
export function exactValueText(body: string, read: (json: unknown) => unknown): string | undefined {
|
|
1688
|
+
const mark = "\u0000exact:";
|
|
1689
|
+
const marked = (v: unknown): unknown => (v instanceof ExactNumber ? `${mark}${String(v)}` : Array.isArray(v) ? v.map(marked) : v !== null && typeof v === "object" ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, marked(x)])) : v);
|
|
1690
|
+
const value = read(parseChecked(body));
|
|
1691
|
+
return value === undefined ? undefined : JSON.stringify(marked(value)).replace(/"\\u0000exact:([^"]*)"/g, "$1");
|
|
1692
|
+
}
|
|
1693
|
+
|
|
1694
|
+
export function exactValueKey(body: string, read: (json: unknown) => unknown): string | undefined {
|
|
1695
|
+
const keyed = (v: unknown): unknown => {
|
|
1696
|
+
const number = v instanceof ExactNumber ? decimal(String(v)) : typeof v === "number" ? decimal(String(v)) : undefined;
|
|
1697
|
+
if (number) return { "\u0000number": `${number.sign}:${number.digits}:${number.point}` };
|
|
1698
|
+
if (Array.isArray(v)) return v.map(keyed);
|
|
1699
|
+
if (v !== null && typeof v === "object") return Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([k, x]) => [k, keyed(x)]));
|
|
1700
|
+
return v;
|
|
1701
|
+
};
|
|
1702
|
+
const value = read(parseChecked(body));
|
|
1703
|
+
return value === undefined ? undefined : JSON.stringify(keyed(value));
|
|
1704
|
+
}
|
|
1705
|
+
|
|
1526
1706
|
const kind = (value: unknown) => value === null ? "null" : Array.isArray(value) ? "array" : value instanceof ExactNumber ? "number" : typeof value;
|
|
1527
1707
|
const describe = (value: unknown) => `${kind(value)}${value instanceof ExactNumber ? ` ${value}` : value === null || typeof value !== "object" ? ` ${JSON.stringify(value)}` : ""}`;
|
|
1528
1708
|
|
|
@@ -1580,9 +1760,19 @@ function checkValue(json: unknown, checks: ResponseJsonCheck[], prefix = ""): st
|
|
|
1580
1760
|
// Keys in any order and any spacing: {"b":2,"a":1} is the same as {"a": 1, "b": 2}.
|
|
1581
1761
|
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));
|
|
1582
1762
|
const written = (text: unknown) => { try { return canonical(parseChecked(String(text))); } catch { return String(text); } };
|
|
1583
|
-
|
|
1763
|
+
// A number is the same however the step writes it: 10.5 is "10.50" and 100 is "1e2" (found in the 1.3.5 review).
|
|
1764
|
+
const sameNumber = (v: unknown) => {
|
|
1765
|
+
const [a, b] = [typeof v === "number" || v instanceof ExactNumber ? decimal(String(v)) : undefined, typeof other === "string" ? decimal(other) : undefined];
|
|
1766
|
+
return a !== undefined && b !== undefined && compareDecimal(a, b) === 0;
|
|
1767
|
+
};
|
|
1768
|
+
// Checked as a string, a number, true or null is its text, as equals reads it: "differs" on the same id fails (found in the 1.3.5 review).
|
|
1769
|
+
if (value === other || (check.type === "string" && (value === null || typeof value !== "object" || value instanceof ExactNumber) && String(value) === other) || (check.type === undefined && (value !== null && typeof value === "object" && !(value instanceof ExactNumber) ? canonical(value) === written(other) : String(value) === other || sameNumber(value)))) return `${field}: expected a value other than ${describe(other)}, got the same`;
|
|
1584
1770
|
} else if (check.pattern !== undefined) {
|
|
1585
1771
|
const re = jsonPattern(check);
|
|
1772
|
+
// "A non-empty field" holds on a number too: an id is often one (found in the 1.3.5 review). Any other
|
|
1773
|
+
// pattern reads text only, so "1" never passes on the number 10.
|
|
1774
|
+
const nonEmptyNumber = check.pattern === NON_EMPTY && (typeof value === "number" || value instanceof ExactNumber);
|
|
1775
|
+
if (nonEmptyNumber) continue;
|
|
1586
1776
|
if (typeof value !== "string") return `${field}: expected text matching /${check.pattern}/, got ${got}`;
|
|
1587
1777
|
if (!re.test(value)) return `${field}: expected text matching /${check.pattern}/, got ${JSON.stringify(value)}`;
|
|
1588
1778
|
} else if (check.min !== undefined || check.max !== undefined) {
|
|
@@ -1613,14 +1803,20 @@ function checkValue(json: unknown, checks: ResponseJsonCheck[], prefix = ""): st
|
|
|
1613
1803
|
return undefined;
|
|
1614
1804
|
}
|
|
1615
1805
|
|
|
1806
|
+
/** The pattern "should have a non-empty field" compiles to: text with a character other than a space, or any number. */
|
|
1807
|
+
export const NON_EMPTY = "\\S";
|
|
1808
|
+
|
|
1616
1809
|
/**
|
|
1617
1810
|
* 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
|
|
1811
|
+
* id), or a decimal it cannot hold, kept as the digits the API sent, never rounded into another id, as a
|
|
1619
1812
|
* capture keeps it: a differs check then sees the same id (found in review).
|
|
1620
1813
|
*/
|
|
1814
|
+
|
|
1621
1815
|
export function parseExact(text: string): unknown {
|
|
1816
|
+
// As a check reads it (parseChecked): a decimal JavaScript would round keeps its digits too, so a differs check
|
|
1817
|
+
// never passes on an unchanged balance, nor a later request send another number (found in the 1.3.5 review).
|
|
1622
1818
|
return JSON.parse(text, (_key, value: unknown, context?: { source?: string }) =>
|
|
1623
|
-
typeof value === "number" &&
|
|
1819
|
+
typeof value === "number" && context?.source !== undefined && (Math.abs(value) > Number.MAX_SAFE_INTEGER || !heldAsWritten(context.source, value)) ? context.source : value);
|
|
1624
1820
|
}
|
|
1625
1821
|
|
|
1626
1822
|
/** A missing property is different from a property whose value is null. */
|