saffron-ai 1.3.1 → 1.3.2
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 +261 -0
- package/dist-pkg/cli.js +357 -357
- package/package.json +1 -1
- package/skills/saffron/SKILL.md +2 -2
- package/skills/saffron/references/syntax.md +8 -4
- package/templates/playwright/saffron-helpers.ts +202 -64
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "saffron-ai",
|
|
3
|
-
"version": "1.3.
|
|
3
|
+
"version": "1.3.2",
|
|
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.2"
|
|
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.2 (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
|
|
@@ -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
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
|
55
|
-
const CREDENTIALS
|
|
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
|
-
/**
|
|
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]), ...
|
|
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(
|
|
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
|
|
172
|
-
*
|
|
173
|
-
*
|
|
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
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
const
|
|
181
|
-
const
|
|
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
|
-
|
|
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
|
-
|
|
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 =
|
|
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
|
-
|
|
976
|
-
|
|
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
|
|
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
|
|
1059
|
-
return element ? normalize((await read(element))
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
1219
|
+
const element = await (await theMatch(target)).elementHandle({ timeout: 1000 }).catch(() => null);
|
|
1180
1220
|
return element ? lines(element).catch(() => []) : [];
|
|
1181
1221
|
}
|
|
1182
1222
|
|
|
1183
|
-
/**
|
|
1184
|
-
|
|
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
|
|
1194
|
-
return match === "excludes" ? !
|
|
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
|
-
|
|
1413
|
-
|
|
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(
|
|
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
|
-
|
|
1478
|
-
|
|
1479
|
-
|
|
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
|
-
|
|
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 =
|
|
1630
|
+
try { json = parseChecked(body); } catch { return "response body is not valid JSON"; }
|
|
1493
1631
|
return checkValue(json, checks);
|
|
1494
1632
|
}
|
|
1495
1633
|
|