saffron-ai 1.1.0 → 1.2.1
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 +356 -0
- package/README.md +23 -10
- package/dist-pkg/cli.js +533 -379
- package/package.json +29 -19
- package/skills/saffron/SKILL.md +42 -4
- package/skills/saffron/references/api.md +151 -0
- package/skills/saffron/references/config.md +12 -6
- package/skills/saffron/references/syntax.md +4 -0
- package/templates/playwright/saffron-helpers.ts +626 -7
|
@@ -5,11 +5,14 @@
|
|
|
5
5
|
// replay: text checks bounded at a value's edges, {date...} and {unique...}
|
|
6
6
|
// tokens, {env:...} values read at run time, network checks counted from the
|
|
7
7
|
// latest browser action, captured values that wait for the page to settle,
|
|
8
|
-
// browser sessions and tabs, downloads and file choosers
|
|
8
|
+
// browser sessions and tabs, downloads and file choosers, and API requests
|
|
9
|
+
// sent through a session's own request client with the checks on their
|
|
10
|
+
// responses.
|
|
9
11
|
import { createHash, randomBytes } from "node:crypto";
|
|
12
|
+
import dns from "node:dns";
|
|
10
13
|
import fs from "node:fs";
|
|
11
14
|
import path from "node:path";
|
|
12
|
-
import { expect, test, 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 Locator, type Page, type Request, type Response } from "@playwright/test";
|
|
13
16
|
|
|
14
17
|
const SETTINGS: {
|
|
15
18
|
/** Locale and time zone {date...} tokens are written in. */
|
|
@@ -22,17 +25,82 @@ const SETTINGS: {
|
|
|
22
25
|
storageState?: string;
|
|
23
26
|
/** How long a check waits, in milliseconds. */
|
|
24
27
|
timeoutMs: number;
|
|
25
|
-
|
|
28
|
+
/** The APIs under test (api in saffron.config.json): the default one's base URL and the named ones'. */
|
|
29
|
+
api: { baseURL?: string; services: Record<string, string> };
|
|
30
|
+
} = /*SETTINGS*/ { locale: "en-US", projectRoot: "..", sessions: {}, timeoutMs: 10000, api: { services: {} } } /*END*/;
|
|
26
31
|
|
|
27
32
|
// --- values ---------------------------------------------------------------
|
|
28
33
|
|
|
34
|
+
/** The {env:...} values read so far, so an error message shows the token and never the value. */
|
|
35
|
+
const SECRETS = new Map<string, string>();
|
|
36
|
+
|
|
29
37
|
/** An {env:NAME} value, read when the test runs. A spec never holds one. Empty counts as unset: a blank check would hold for anything. */
|
|
38
|
+
/** A duration a recording wrote as text: milliseconds ("2000") or a number with a unit ("2 s", "500 ms", "1 m"). */
|
|
39
|
+
export function duration(text: string): number {
|
|
40
|
+
const m = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|sec|secs|second|seconds|min|mins|minute|minutes|millisecond|milliseconds)?\s*$/i.exec(text);
|
|
41
|
+
if (!m) throw new Error(`${JSON.stringify(text)} is not a duration: write milliseconds ("2000") or a number with a unit ("2 s", "500 ms", "1 m")`);
|
|
42
|
+
const unit = (m[2] ?? "ms").toLowerCase();
|
|
43
|
+
const factor = unit.startsWith("ms") || unit.startsWith("milli") ? 1 : unit.startsWith("m") ? 60_000 : 1000;
|
|
44
|
+
return Math.round(Number(m[1]) * factor);
|
|
45
|
+
}
|
|
46
|
+
|
|
30
47
|
export function env(name: string): string {
|
|
31
48
|
const value = process.env[name];
|
|
32
49
|
if (value === undefined || value === "") throw new Error(`environment variable ${name} is not set`);
|
|
50
|
+
SECRETS.set(name, value);
|
|
33
51
|
return value;
|
|
34
52
|
}
|
|
35
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>();
|
|
56
|
+
|
|
57
|
+
/** Text with every {env:...} value and captured credential written back as its token, longest first, as written and as JSON escapes it. */
|
|
58
|
+
function mask(text: string): string {
|
|
59
|
+
const values = [...[...SECRETS].map(([name, value]) => [`{env:${name}}`, value]), ...[...CREDENTIALS].map(([name, value]) => [`{captured:${name}}`, value])];
|
|
60
|
+
for (const [token, value] of values.sort((a, b) => b[1].length - a[1].length)) {
|
|
61
|
+
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);
|
|
65
|
+
}
|
|
66
|
+
return text;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** Words a capture's name or its field carries when the value is a credential, as the runner reads them. */
|
|
70
|
+
const CREDENTIAL_WORDS = new Set(["token", "secret", "password", "passwd", "pwd", "apikey", "accesskey", "privatekey", "session", "credential", "credentials", "auth", "authorization", "jwt", "bearer", "cookie", "otp", "pin", "csrf", "xsrf", "signature", "nonce", "refresh"]);
|
|
71
|
+
|
|
72
|
+
function isCredentialCapture(name: string, pointer: string): boolean {
|
|
73
|
+
const words = `${name} ${pointer.split("/").at(-1) ?? ""}`.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
|
|
74
|
+
return words.some((w, i) => CREDENTIAL_WORDS.has(w) || (w === "key" && ["api", "access", "private", "secret"].includes(words[i - 1] ?? "")));
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** Whether a host name resolves to a link-local address, looked up for every request. */
|
|
78
|
+
async function resolvesLinkLocal(hostname: string): Promise<boolean> {
|
|
79
|
+
const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
|
|
80
|
+
if (host === "localhost" || /^[\d.]+$/.test(host) || host.includes(":")) return false;
|
|
81
|
+
const found = await dns.promises.lookup(host, { all: true }).catch(() => []);
|
|
82
|
+
return found.some((f) => isLinkLocal(f.address));
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** A number or boolean a request body sends where the recording holds text with tokens (a row's "<seats>"). */
|
|
86
|
+
export function typed(text: string, type: "number" | "boolean" | "json"): unknown {
|
|
87
|
+
if (type === "json") {
|
|
88
|
+
try {
|
|
89
|
+
return JSON.parse(text);
|
|
90
|
+
} catch {
|
|
91
|
+
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");
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
if (type === "boolean") {
|
|
95
|
+
if (text === "true" || text === "false") return text === "true";
|
|
96
|
+
throw new Error(`a body field must be true or false, but its value resolves to ${JSON.stringify(mask(text))}`);
|
|
97
|
+
}
|
|
98
|
+
// A decimal number as JSON writes one, as replay reads it: "Infinity" would be sent as null, "0x1F" as 31.
|
|
99
|
+
const number = Number(text);
|
|
100
|
+
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))}`);
|
|
101
|
+
return number;
|
|
102
|
+
}
|
|
103
|
+
|
|
36
104
|
/** A check's expected text must say something: "" is in every text. */
|
|
37
105
|
function said<T extends string | RegExp>(expected: T, what: string): T {
|
|
38
106
|
if (typeof expected === "string" ? normalize(expected) === "" : expected.source === "" || expected.source === "(?:)") throw new Error(`${what} is blank, so it would hold for anything`);
|
|
@@ -247,8 +315,120 @@ interface Lane {
|
|
|
247
315
|
active: Page;
|
|
248
316
|
opened: Page[];
|
|
249
317
|
net: ResponseLog;
|
|
318
|
+
/** The latest response the session's request client got (see Run.send). */
|
|
319
|
+
last?: Exchange;
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
/** One API request and its response. */
|
|
323
|
+
interface Exchange {
|
|
324
|
+
method: string;
|
|
325
|
+
url: string;
|
|
326
|
+
status: number;
|
|
327
|
+
headers: Record<string, string>;
|
|
328
|
+
body?: string;
|
|
329
|
+
durationMs: number;
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
/** A request as the spec writes it: every text resolved, a typed leaf already a number or a boolean. */
|
|
333
|
+
export interface RequestSpec {
|
|
334
|
+
method: string;
|
|
335
|
+
/** Relative to the API's base URL; a full URL goes to another host. */
|
|
336
|
+
path: string;
|
|
337
|
+
/** The API it goes to, by its name in api.services; absent, the default API. */
|
|
338
|
+
service?: string;
|
|
339
|
+
headers?: Record<string, string>;
|
|
340
|
+
body?: unknown;
|
|
341
|
+
form?: Record<string, string>;
|
|
342
|
+
multipart?: Record<string, string | { $file: string }>;
|
|
343
|
+
/** Sent again until the response has the expected status and satisfies these checks. */
|
|
344
|
+
until?: { json?: ResponseJsonCheck[]; intervalMs?: number; timeoutMs?: number };
|
|
345
|
+
idempotent?: boolean;
|
|
346
|
+
timeoutMs?: number;
|
|
347
|
+
/** The expected status ("201" or "2xx"; default any 2xx). */
|
|
348
|
+
status?: string;
|
|
349
|
+
/** Response fields to keep for {captured:name}: name to JSON Pointer, or header:Name. */
|
|
350
|
+
extract?: Record<string, string>;
|
|
351
|
+
/** The request carries an {env:...} value: it is sent to its API's base URL and nowhere else. */
|
|
352
|
+
secret?: boolean;
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
|
|
356
|
+
|
|
357
|
+
/**
|
|
358
|
+
* Whether a URL's host is a link-local address: 169.254.0.0/16, fe80::/10,
|
|
359
|
+
* or either mapped into IPv6; or AWS's IPv6 metadata address, fd00:ec2::254,
|
|
360
|
+
* which serves the same credentials. Read as written.
|
|
361
|
+
*/
|
|
362
|
+
function isLinkLocal(hostname: string): boolean {
|
|
363
|
+
const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
|
|
364
|
+
if (/^169\.254\.\d{1,3}\.\d{1,3}$/.test(host)) return true;
|
|
365
|
+
if (/^fe[89ab][0-9a-f]?:/.test(host) || host === "fd00:ec2::254") return true;
|
|
366
|
+
const mapped = /^::ffff:(?:(\d{1,3}(?:\.\d{1,3}){3})|([0-9a-f]{1,4}):[0-9a-f]{1,4})$/.exec(host);
|
|
367
|
+
if (mapped) return mapped[1] ? /^169\.254\./.test(mapped[1]) : parseInt(mapped[2], 16) === 0xa9fe;
|
|
368
|
+
return false;
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
/** A file's media type from its extension, for a multipart part; octet-stream when unknown. */
|
|
372
|
+
function mimeTypeOf(file: string): string {
|
|
373
|
+
const types: Record<string, string> = { ".json": "application/json", ".pdf": "application/pdf", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml", ".txt": "text/plain", ".csv": "text/csv", ".xml": "application/xml", ".html": "text/html", ".zip": "application/zip" };
|
|
374
|
+
return types[path.extname(file).toLowerCase()] ?? "application/octet-stream";
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
/** A schema the contract gives, whole, in the JSON Schema dialect of its contract (OpenAPI 3.1: 2020-12; 3.0: draft-07). */
|
|
378
|
+
export interface ExportedSchema {
|
|
379
|
+
dialect: "2020-12" | "draft-07";
|
|
380
|
+
schema: unknown;
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
/** A schema check as the spec holds it: one named schema, or an operation's by response key ("201", "4XX", "default"). */
|
|
384
|
+
export interface SchemaCheck {
|
|
385
|
+
what: string;
|
|
386
|
+
schema?: ExportedSchema;
|
|
387
|
+
responses?: Record<string, ExportedSchema | "no-body" | "no-schema">;
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
type Validator = ((value: unknown) => boolean) & { errors?: { instancePath: string; message?: string; params?: Record<string, unknown> }[] | null };
|
|
391
|
+
|
|
392
|
+
const compiled = new Map<string, Validator>();
|
|
393
|
+
|
|
394
|
+
/**
|
|
395
|
+
* A schema compiled with ajv and ajv-formats, as replay compiles the pinned
|
|
396
|
+
* contract: formats checked, no strict mode, all errors. Loaded only by a
|
|
397
|
+
* schema check, so a suite with none needs neither installed.
|
|
398
|
+
*/
|
|
399
|
+
async function compiledSchema(target: ExportedSchema): Promise<Validator> {
|
|
400
|
+
const key = JSON.stringify(target);
|
|
401
|
+
const known = compiled.get(key);
|
|
402
|
+
if (known) return known;
|
|
403
|
+
// By name, so a project without ajv type-checks and runs every other check.
|
|
404
|
+
const load = (name: string) => import(name);
|
|
405
|
+
let Engine: new (options: object) => { compile(schema: unknown): Validator };
|
|
406
|
+
let addFormats: (ajv: unknown) => void;
|
|
407
|
+
try {
|
|
408
|
+
const core = target.dialect === "2020-12" ? await load("ajv/dist/2020.js") : await load("ajv");
|
|
409
|
+
Engine = target.dialect === "2020-12" ? (core.Ajv2020 ?? core.default?.Ajv2020 ?? core.default) : (core.Ajv ?? core.default?.Ajv ?? core.default);
|
|
410
|
+
const formats = await load("ajv-formats");
|
|
411
|
+
addFormats = formats.default?.default ?? formats.default ?? formats;
|
|
412
|
+
} catch {
|
|
413
|
+
throw new Error("the schema check needs ajv and ajv-formats: npm install --save-dev ajv@^8 ajv-formats@^3");
|
|
414
|
+
}
|
|
415
|
+
const ajv = new Engine({ strict: false, allErrors: true, validateFormats: true, allowUnionTypes: true, logger: false });
|
|
416
|
+
addFormats(ajv);
|
|
417
|
+
const validate = ajv.compile(target.schema);
|
|
418
|
+
compiled.set(key, validate);
|
|
419
|
+
return validate;
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
/** The start of a response body, for an error line. */
|
|
423
|
+
function excerpt(body: string | undefined): string {
|
|
424
|
+
if (!body) return "";
|
|
425
|
+
const line = mask(body).replace(/\s+/g, " ").trim();
|
|
426
|
+
return line ? `: ${line.length > 300 ? `${line.slice(0, 300)}...` : line}` : "";
|
|
250
427
|
}
|
|
251
428
|
|
|
429
|
+
/** A response header by name, whatever its case. */
|
|
430
|
+
const headerOf = (headers: Record<string, string>, name: string) => Object.entries(headers).find(([k]) => k.toLowerCase() === name.toLowerCase())?.[1];
|
|
431
|
+
|
|
252
432
|
/**
|
|
253
433
|
* One scenario: its browser sessions (each a context with its own tabs and
|
|
254
434
|
* network log), the values it captured, its {unique...} seed and its clock.
|
|
@@ -257,6 +437,8 @@ export class Run {
|
|
|
257
437
|
private lanes = new Map<string, Lane>();
|
|
258
438
|
private lane!: Lane;
|
|
259
439
|
private vars = new Map<string, string>();
|
|
440
|
+
/** The credentials this scenario's requests captured: sent only to the APIs under test, as replay keeps them per execution. */
|
|
441
|
+
private credentials = new Map<string, string>();
|
|
260
442
|
private seed = `${Date.now().toString(36)}${randomBytes(4).toString("hex")}`;
|
|
261
443
|
/** One clock per scenario: a day picked in one step is the day a later step checks. */
|
|
262
444
|
readonly now = new Date();
|
|
@@ -321,9 +503,13 @@ export class Run {
|
|
|
321
503
|
|
|
322
504
|
/** A recorded URL under the base URL, as Saffron joins them (a base path is kept). */
|
|
323
505
|
url(recorded: string): string {
|
|
506
|
+
return this.join(recorded, this.baseURL, `relative navigation "${recorded}" needs a baseURL in playwright.config.ts`);
|
|
507
|
+
}
|
|
508
|
+
|
|
509
|
+
private join(recorded: string, baseURL: string | undefined, orElse: string): string {
|
|
324
510
|
if (/^[a-z][a-z\d+.-]*:|^\/\//i.test(recorded)) return recorded;
|
|
325
|
-
if (!
|
|
326
|
-
const base = new URL(
|
|
511
|
+
if (!baseURL) throw new Error(orElse);
|
|
512
|
+
const base = new URL(baseURL);
|
|
327
513
|
const prefix = base.pathname.replace(/\/+$/, "");
|
|
328
514
|
const hashAt = recorded.indexOf("#");
|
|
329
515
|
const hash = hashAt >= 0 ? recorded.slice(hashAt) : undefined;
|
|
@@ -521,10 +707,15 @@ export class Run {
|
|
|
521
707
|
}
|
|
522
708
|
|
|
523
709
|
/** A response matching the recorded request has been seen (a wait) or was answered since the latest action (a check). */
|
|
524
|
-
async response(kind: "wait" | "check", match: { url: string; method?: string; status?: string; body?: string }): Promise<void> {
|
|
710
|
+
async response(kind: "wait" | "check", match: { url: string; method?: string; status?: string; body?: string; json?: ResponseJsonCheck[] }): Promise<void> {
|
|
525
711
|
if (match.url === "" || match.method === "" || match.status === "" || match.body === "") throw new Error("a response check with a blank part would match any response");
|
|
526
712
|
const url = pattern(match.url);
|
|
527
713
|
const body = match.body !== undefined ? pattern(match.body) : undefined;
|
|
714
|
+
if (match.json) {
|
|
715
|
+
const malformed = responseJsonProblem(match.json);
|
|
716
|
+
if (malformed) throw new Error(`Response json ${malformed}`);
|
|
717
|
+
jsonChecksReadable(match.json);
|
|
718
|
+
}
|
|
528
719
|
const net = this.lane.net;
|
|
529
720
|
await expect
|
|
530
721
|
.poll(
|
|
@@ -534,13 +725,237 @@ export class Run {
|
|
|
534
725
|
(url.test(e.url) || url.test(decode(e.url))) &&
|
|
535
726
|
(!match.method || e.method.toUpperCase() === match.method.toUpperCase()) &&
|
|
536
727
|
statusMatches(e.status, match.status) &&
|
|
728
|
+
(!match.json || checkResponseJson(e.body, match.json) === undefined) &&
|
|
537
729
|
(!body || (e.body !== undefined && body.test(e.body))),
|
|
538
730
|
),
|
|
539
|
-
{ message: `a ${match.method ?? ""} response from /${match.url}/ with status ${match.status ?? "2xx"}${match.body ? ` and a body matching /${match.body}/` : ""}`, timeout: SETTINGS.timeoutMs },
|
|
731
|
+
{ 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 },
|
|
540
732
|
)
|
|
541
733
|
.toBe(true);
|
|
542
734
|
}
|
|
543
735
|
|
|
736
|
+
/**
|
|
737
|
+
* The base URL of an API: API_URL (the default API) or API_URL_<NAME> (a
|
|
738
|
+
* named one, its name upper-cased, other characters as _) from the
|
|
739
|
+
* environment, else api.baseURL or api.services.<name>.baseURL from
|
|
740
|
+
* saffron.config.json; the default API falls back to the test's baseURL.
|
|
741
|
+
*/
|
|
742
|
+
apiBase(service?: string): string | undefined {
|
|
743
|
+
if (service === undefined) return process.env.API_URL || SETTINGS.api.baseURL || this.baseURL;
|
|
744
|
+
const configured = SETTINGS.api.services[service];
|
|
745
|
+
if (configured === undefined) throw new Error(`no API service named "${service}": api.services in saffron.config.json has ${Object.keys(SETTINGS.api.services).map((n) => `"${n}"`).join(", ") || "none"}`);
|
|
746
|
+
return process.env[`API_URL_${service.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`] || configured;
|
|
747
|
+
}
|
|
748
|
+
|
|
749
|
+
/**
|
|
750
|
+
* Send a request through the active session's request client, so a call
|
|
751
|
+
* after a UI sign-in carries its cookies, and keep its response for the
|
|
752
|
+
* checks that follow. The response must have the expected status; a
|
|
753
|
+
* polled request (`until`) is sent again until it does and its checks
|
|
754
|
+
* hold, and only a GET, HEAD, OPTIONS or idempotent request polls.
|
|
755
|
+
*/
|
|
756
|
+
async send(spec: RequestSpec): Promise<void> {
|
|
757
|
+
const method = spec.method.toUpperCase();
|
|
758
|
+
const where = spec.service === undefined ? "api.baseURL" : `api.services.${spec.service}.baseURL`;
|
|
759
|
+
if (spec.until !== undefined && !(spec.idempotent ?? IDEMPOTENT_METHODS.has(method))) {
|
|
760
|
+
throw new Error(`${method} ${spec.path} polls (until), and a ${method} may not be sent twice: poll with a GET that reads the state, or mark the request idempotent`);
|
|
761
|
+
}
|
|
762
|
+
const base = this.apiBase(spec.service);
|
|
763
|
+
const url = this.join(spec.path, base, `${method} ${mask(spec.path)} is relative, and no API base URL is set: set ${where} in saffron.config.json, API_URL in the environment, or baseURL in playwright.config.ts`);
|
|
764
|
+
if (isLinkLocal(new URL(url).hostname) || (await resolvesLinkLocal(new URL(url).hostname))) throw new Error(`${method} ${mask(url)} goes to a link-local address, where a cloud keeps its metadata and credentials, so it is never sent.`);
|
|
765
|
+
// A credential the API handed out goes to the APIs under test and nowhere else.
|
|
766
|
+
const sent = JSON.stringify([url, spec.headers, spec.body, spec.form, spec.multipart]);
|
|
767
|
+
const credential = [...this.credentials].find(([, value]) => value.length >= 3 && (sent.includes(value) || sent.includes(JSON.stringify(value).slice(1, -1))))?.[0];
|
|
768
|
+
const origins = new Set([undefined, ...Object.keys(SETTINGS.api.services)].flatMap((name) => {
|
|
769
|
+
const api = this.apiBase(name);
|
|
770
|
+
return api ? [new URL(api).origin] : [];
|
|
771
|
+
}));
|
|
772
|
+
if (credential !== undefined) {
|
|
773
|
+
if (!origins.has(new URL(url).origin)) throw new Error(`${method} ${mask(url)} carries {captured:${credential}}, a credential the API handed out, to ${new URL(url).origin}, which is not an API under test: a captured credential is only sent to one.`);
|
|
774
|
+
}
|
|
775
|
+
// A secret goes to the API under test and nowhere else.
|
|
776
|
+
if (spec.secret && new URL(url).origin !== (base ? new URL(base).origin : undefined)) {
|
|
777
|
+
throw new Error(`${method} ${mask(url)} carries an {env:...} value to ${new URL(url).origin}, which is not the API's base URL${base ? ` (${new URL(base).origin})` : ""}: a request with an {env:...} value is only sent there. Set ${where} to the API that should receive it.`);
|
|
778
|
+
}
|
|
779
|
+
let multipart: Record<string, string | { name: string; mimeType: string; buffer: Buffer }> | undefined;
|
|
780
|
+
if (spec.multipart !== undefined) {
|
|
781
|
+
multipart = {};
|
|
782
|
+
for (const [field, part] of Object.entries(spec.multipart)) {
|
|
783
|
+
if (typeof part === "string") {
|
|
784
|
+
multipart[field] = part;
|
|
785
|
+
continue;
|
|
786
|
+
}
|
|
787
|
+
const root = path.resolve(path.dirname(test.info().file), SETTINGS.projectRoot);
|
|
788
|
+
const file = path.resolve(root, part.$file);
|
|
789
|
+
if (file !== root && !file.startsWith(root + path.sep)) throw new Error(`${part.$file} is outside the project: a request sends only the project's own files`);
|
|
790
|
+
if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`${part.$file} is not a file of the project, so the request cannot send it`);
|
|
791
|
+
// A link inside the project that leads out of it is outside too.
|
|
792
|
+
if (!fs.realpathSync(file).startsWith(fs.realpathSync(root) + path.sep)) throw new Error(`${part.$file} is outside the project: a request sends only the project's own files`);
|
|
793
|
+
// A hidden file or folder (.env, .git, .npmrc) holds the project's secrets and settings, as replay reads it.
|
|
794
|
+
const hidden = (rel: string) => rel.split(path.sep).some((piece) => piece.startsWith("."));
|
|
795
|
+
if (hidden(path.relative(root, file)) || hidden(path.relative(fs.realpathSync(root), fs.realpathSync(file)))) throw new Error(`${part.$file} is a hidden file of the project (.env, .git and the like hold its secrets), so a request never sends it`);
|
|
796
|
+
// A hard link is the same file under a second name, which no path tells: it may be .env.
|
|
797
|
+
if (fs.statSync(file).nlink > 1) throw new Error(`${part.$file} is a hard link (the same file under another name, perhaps a hidden one such as .env), so a request never sends it: copy the file instead`);
|
|
798
|
+
// A file of the project goes to the APIs under test and nowhere else.
|
|
799
|
+
if (!origins.has(new URL(url).origin)) throw new Error(`${method} ${mask(url)} sends a file of the project to ${new URL(url).origin}, which is not an API under test: a request sends the project's files only to one.`);
|
|
800
|
+
multipart[field] = { name: path.basename(file), mimeType: mimeTypeOf(file), buffer: fs.readFileSync(file) };
|
|
801
|
+
}
|
|
802
|
+
}
|
|
803
|
+
const until = spec.until === undefined ? undefined : { checks: spec.until.json ?? [], intervalMs: spec.until.intervalMs ?? 1000, deadline: Date.now() + (spec.until.timeoutMs ?? 30_000) };
|
|
804
|
+
// A poll is a wait for a state, as replay bounds it: every 100 ms at the fastest, 10 minutes at the longest.
|
|
805
|
+
if (until && until.intervalMs < 100) throw new Error(`${method} ${spec.path} polls every ${until.intervalMs} ms, faster than the 100 ms a poll may`);
|
|
806
|
+
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`);
|
|
807
|
+
if (until) jsonChecksReadable(until.checks);
|
|
808
|
+
const lane = this.lane;
|
|
809
|
+
const attempt = async (): Promise<Exchange> => {
|
|
810
|
+
const started = Date.now();
|
|
811
|
+
let response: APIResponse;
|
|
812
|
+
try {
|
|
813
|
+
response = await lane.context.request.fetch(url, {
|
|
814
|
+
method,
|
|
815
|
+
headers: spec.headers,
|
|
816
|
+
...(spec.body === undefined ? {} : { data: spec.body as string | object }),
|
|
817
|
+
...(spec.form === undefined ? {} : { form: spec.form }),
|
|
818
|
+
...(multipart === undefined ? {} : { multipart }),
|
|
819
|
+
timeout: spec.timeoutMs ?? SETTINGS.timeoutMs,
|
|
820
|
+
failOnStatusCode: false,
|
|
821
|
+
maxRedirects: 0,
|
|
822
|
+
});
|
|
823
|
+
} catch (err) {
|
|
824
|
+
// Playwright's message ends in a call log listing the request's headers: only its first line is kept.
|
|
825
|
+
const reason = (err instanceof Error ? err.message : String(err)).split("\n")[0].replace(/^apiRequestContext\.fetch:\s*/, "").trim();
|
|
826
|
+
throw new Error(mask(`${method} ${url} got no response: ${reason}`));
|
|
827
|
+
}
|
|
828
|
+
const body = await response.text().catch(() => undefined);
|
|
829
|
+
return (lane.last = { method, url, status: response.status(), headers: response.headers(), body, durationMs: Date.now() - started });
|
|
830
|
+
};
|
|
831
|
+
const notYet = (exchange: Exchange): string | undefined => {
|
|
832
|
+
if (!statusMatches(exchange.status, spec.status)) return `returned ${exchange.status}, expected ${spec.status ?? "2xx"}${excerpt(exchange.body)}`;
|
|
833
|
+
const problem = until && until.checks.length > 0 ? checkResponseJson(exchange.body, until.checks) : undefined;
|
|
834
|
+
return problem ? `${problem}${excerpt(exchange.body)}` : undefined;
|
|
835
|
+
};
|
|
836
|
+
let exchange = await attempt();
|
|
837
|
+
while (until !== undefined && notYet(exchange) !== undefined && Date.now() + until.intervalMs <= until.deadline) {
|
|
838
|
+
await new Promise<void>((r) => setTimeout(r, until.intervalMs));
|
|
839
|
+
exchange = await attempt();
|
|
840
|
+
}
|
|
841
|
+
// A response the step fails on still hands out its credentials, and the error quotes its body: they are known first.
|
|
842
|
+
for (const [name, pointer] of Object.entries(spec.extract ?? {})) {
|
|
843
|
+
if (!isCredentialCapture(name, pointer)) continue;
|
|
844
|
+
const header = /^header:(.+)$/i.exec(pointer);
|
|
845
|
+
let value: unknown;
|
|
846
|
+
try {
|
|
847
|
+
value = header ? headerOf(exchange.headers, header[1]) : at(JSON.parse(exchange.body ?? ""), pointer);
|
|
848
|
+
} catch {
|
|
849
|
+
value = undefined;
|
|
850
|
+
}
|
|
851
|
+
if (value !== undefined) {
|
|
852
|
+
const kept = typeof value === "string" ? value : JSON.stringify(value);
|
|
853
|
+
this.credentials.set(name, kept);
|
|
854
|
+
CREDENTIALS.set(name, kept);
|
|
855
|
+
}
|
|
856
|
+
}
|
|
857
|
+
const problem = notYet(exchange);
|
|
858
|
+
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`));
|
|
859
|
+
for (const [name, pointer] of Object.entries(spec.extract ?? {})) {
|
|
860
|
+
const header = /^header:(.+)$/i.exec(pointer);
|
|
861
|
+
if (header) {
|
|
862
|
+
const value = headerOf(exchange.headers, header[1]);
|
|
863
|
+
if (value === undefined) throw new Error(mask(`${method} ${url}: the response has no ${header[1]} header to extract as "${name}"`));
|
|
864
|
+
this.vars.set(name, value);
|
|
865
|
+
continue;
|
|
866
|
+
}
|
|
867
|
+
let parsed: unknown;
|
|
868
|
+
try {
|
|
869
|
+
parsed = JSON.parse(exchange.body ?? "");
|
|
870
|
+
} catch {
|
|
871
|
+
throw new Error(mask(`${method} ${url} returned no JSON body, so "${name}" (${pointer || "/"}) cannot be extracted${excerpt(exchange.body)}`));
|
|
872
|
+
}
|
|
873
|
+
const value = at(parsed, pointer);
|
|
874
|
+
if (value === undefined) throw new Error(mask(`${method} ${url}: the response has no ${pointer || "/"} to extract as "${name}"${excerpt(exchange.body)}`));
|
|
875
|
+
this.vars.set(name, typeof value === "string" ? value : JSON.stringify(value));
|
|
876
|
+
}
|
|
877
|
+
}
|
|
878
|
+
|
|
879
|
+
private latest(): Exchange {
|
|
880
|
+
if (!this.lane.last) throw new Error("no request was sent yet in this step's session: a response check needs a request before it");
|
|
881
|
+
return this.lane.last;
|
|
882
|
+
}
|
|
883
|
+
|
|
884
|
+
/** The latest response's status is `expected`: a code ("404") or a class ("2xx"). */
|
|
885
|
+
expectStatus(expected: string): void {
|
|
886
|
+
const last = this.latest();
|
|
887
|
+
if (expected.trim() === "") throw new Error("an expected status is blank, so it would hold for anything");
|
|
888
|
+
if (!statusMatches(last.status, expected)) throw new Error(mask(`expected the response status ${expected}, but ${last.method} ${last.url} returned ${last.status}${excerpt(last.body)}`));
|
|
889
|
+
}
|
|
890
|
+
|
|
891
|
+
/** The latest response's JSON fields pass every check, as replay checks them. */
|
|
892
|
+
expectJson(checks: ResponseJsonCheck[]): void {
|
|
893
|
+
const last = this.latest();
|
|
894
|
+
const malformed = responseJsonProblem(checks);
|
|
895
|
+
if (malformed) throw new Error(`Response json ${malformed}`);
|
|
896
|
+
jsonChecksReadable(checks);
|
|
897
|
+
const problem = checkResponseJson(last.body, checks);
|
|
898
|
+
if (problem) throw new Error(mask(`${last.method} ${last.url}: ${problem}`));
|
|
899
|
+
}
|
|
900
|
+
|
|
901
|
+
/** The latest response has the header: equal to `value`, matching `pattern`, or present when neither is given. */
|
|
902
|
+
expectHeader(name: string, expected: { value?: string; pattern?: string } = {}): void {
|
|
903
|
+
const last = this.latest();
|
|
904
|
+
const value = headerOf(last.headers, name);
|
|
905
|
+
const where = `${last.method} ${last.url}`;
|
|
906
|
+
if (value === undefined) throw new Error(mask(`${where}: the response has no ${name} header${Object.keys(last.headers).length > 0 ? ` (it has ${Object.keys(last.headers).join(", ")})` : ""}`));
|
|
907
|
+
if (expected.value !== undefined) {
|
|
908
|
+
if (value !== expected.value) throw new Error(mask(`${where}: expected the ${name} header to be ${JSON.stringify(expected.value)}, got ${JSON.stringify(value)}`));
|
|
909
|
+
} else if (expected.pattern !== undefined) {
|
|
910
|
+
let re: RegExp;
|
|
911
|
+
try {
|
|
912
|
+
re = new RegExp(expected.pattern);
|
|
913
|
+
} catch {
|
|
914
|
+
throw new Error(`expectHeader: /${expected.pattern}/ is not a regular expression`);
|
|
915
|
+
}
|
|
916
|
+
if (!re.test(value)) throw new Error(mask(`${where}: expected the ${name} header to match /${expected.pattern}/, got ${JSON.stringify(value)}`));
|
|
917
|
+
}
|
|
918
|
+
}
|
|
919
|
+
|
|
920
|
+
/**
|
|
921
|
+
* The latest response's body matches the pinned contract, as replay
|
|
922
|
+
* checks it: the one schema the check names, or the schema the operation
|
|
923
|
+
* gives the response's status (its code, its class, or the default), and
|
|
924
|
+
* no body where the contract gives the response none. The schemas were
|
|
925
|
+
* resolved from the contract when the spec was written (SCHEMAS).
|
|
926
|
+
*/
|
|
927
|
+
async expectSchema(check: SchemaCheck): Promise<void> {
|
|
928
|
+
const last = this.latest();
|
|
929
|
+
let target = check.schema;
|
|
930
|
+
if (!target) {
|
|
931
|
+
const n = Math.floor(last.status / 100);
|
|
932
|
+
const key = [String(last.status), `${n}XX`, `${n}xx`, "default"].find((k) => check.responses?.[k] !== undefined);
|
|
933
|
+
const entry = key === undefined ? "no-schema" : check.responses![key];
|
|
934
|
+
if (entry === "no-body") {
|
|
935
|
+
if ((last.body ?? "").trim() === "") return;
|
|
936
|
+
throw new Error(mask(`${check.what} give a ${last.status} response no body, and ${last.method} ${last.url} returned one${excerpt(last.body)}`));
|
|
937
|
+
}
|
|
938
|
+
if (entry === "no-schema") throw new Error(`${check.what} give no JSON schema for a ${last.status} response`);
|
|
939
|
+
target = entry;
|
|
940
|
+
}
|
|
941
|
+
let value: unknown;
|
|
942
|
+
try {
|
|
943
|
+
value = JSON.parse(last.body ?? "");
|
|
944
|
+
} catch {
|
|
945
|
+
throw new Error(mask(`${last.method} ${last.url} returned no JSON body to check against ${check.what}${excerpt(last.body)}`));
|
|
946
|
+
}
|
|
947
|
+
const validate = await compiledSchema(target);
|
|
948
|
+
if (validate(value)) return;
|
|
949
|
+
const errors = (validate.errors ?? []).slice(0, 5).map((e) => `${e.instancePath || "/"} ${e.message ?? "is invalid"}${e.params && "additionalProperty" in e.params ? ` (${String(e.params.additionalProperty)})` : ""}`);
|
|
950
|
+
throw new Error(mask(`the ${last.method} ${last.url} response does not match ${check.what}: ${errors.join("; ")}`));
|
|
951
|
+
}
|
|
952
|
+
|
|
953
|
+
/** The latest response arrived within `maxMs` milliseconds, from sending the request to its body being read. */
|
|
954
|
+
expectDuration(maxMs: number): void {
|
|
955
|
+
const last = this.latest();
|
|
956
|
+
if (last.durationMs > maxMs) throw new Error(mask(`${last.method} ${last.url} took ${last.durationMs} ms, more than the ${maxMs} ms the step allows`));
|
|
957
|
+
}
|
|
958
|
+
|
|
544
959
|
/** The latest download, read as text, contains `value` and matches `source` (case-sensitive, ^ and $ at each line). */
|
|
545
960
|
async expectDownload(value?: string | RegExp, source?: string): Promise<void> {
|
|
546
961
|
if (!this.download) throw new Error("expectDownload: no file was downloaded in this scenario before this check");
|
|
@@ -650,3 +1065,207 @@ export async function expectUrl(page: Page, expected: string | RegExp): Promise<
|
|
|
650
1065
|
return [url, decode(url), decode(url.replace(/\+/g, "%20"))].some((u) => contains(u, expected));
|
|
651
1066
|
}, `URL containing ${expected} on the active page`);
|
|
652
1067
|
}
|
|
1068
|
+
|
|
1069
|
+
// --- JSON field checks ----------------------------------------------------
|
|
1070
|
+
|
|
1071
|
+
/** A JSON field check, as a recording holds one (ResponseJsonCheck in saffron-ai). */
|
|
1072
|
+
export interface ResponseJsonCheck {
|
|
1073
|
+
/** JSON Pointer, for example /order/status or /items/0/sku. Empty selects the root. */
|
|
1074
|
+
path: string;
|
|
1075
|
+
equals?: string;
|
|
1076
|
+
type?: "string" | "number" | "boolean" | "null";
|
|
1077
|
+
exists?: boolean;
|
|
1078
|
+
/** The value at `path` is a list holding at least one item these checks all hold on. */
|
|
1079
|
+
item?: ResponseJsonCheck[];
|
|
1080
|
+
/** The value at `path` is a list with items, and these checks hold on each one. */
|
|
1081
|
+
every?: ResponseJsonCheck[];
|
|
1082
|
+
/** The value at `path` is a list of exactly this many items. */
|
|
1083
|
+
count?: string;
|
|
1084
|
+
/** The value at `path` is not this scalar (read as `type`). */
|
|
1085
|
+
differs?: string;
|
|
1086
|
+
/** The value at `path` is text matching this regular expression. */
|
|
1087
|
+
pattern?: string;
|
|
1088
|
+
/** The value at `path` is a number at least `min` and/or at most `max`. */
|
|
1089
|
+
min?: string;
|
|
1090
|
+
max?: string;
|
|
1091
|
+
}
|
|
1092
|
+
|
|
1093
|
+
// Saffron's own checker, src/util/response-json.ts in saffron-ai, copied
|
|
1094
|
+
// verbatim so an exported check reads a response exactly as replay does
|
|
1095
|
+
// (a test in saffron-ai fails when the two differ).
|
|
1096
|
+
/*RESPONSE_JSON*/
|
|
1097
|
+
/** The texts of a check a step's value may be written in: resolved at replay, and where a row's value is looked for. */
|
|
1098
|
+
export const JSON_CHECK_TEXTS = ["equals", "differs", "count", "min", "max", "pattern"] as const;
|
|
1099
|
+
|
|
1100
|
+
/** Every check, an item or every check's own checks after it, at any depth. */
|
|
1101
|
+
export function flatJsonChecks(checks: ResponseJsonCheck[] | undefined): ResponseJsonCheck[] {
|
|
1102
|
+
return (checks ?? []).flatMap((c) => [c, ...flatJsonChecks(c.item), ...flatJsonChecks(c.every)]);
|
|
1103
|
+
}
|
|
1104
|
+
|
|
1105
|
+
/** The checks rewritten by `map`, an item or every check's own checks too. */
|
|
1106
|
+
export function mapJsonChecks(checks: ResponseJsonCheck[], map: (check: ResponseJsonCheck) => ResponseJsonCheck): ResponseJsonCheck[] {
|
|
1107
|
+
return checks.map((c) => {
|
|
1108
|
+
const mapped = map(c);
|
|
1109
|
+
return { ...mapped, ...(c.item ? { item: mapJsonChecks(c.item, map) } : {}), ...(c.every ? { every: mapJsonChecks(c.every, map) } : {}) };
|
|
1110
|
+
});
|
|
1111
|
+
}
|
|
1112
|
+
|
|
1113
|
+
/** A check with its texts (JSON_CHECK_TEXTS) rewritten by `text`; a pattern by `pattern`, which defaults to `text`. */
|
|
1114
|
+
export function mapJsonCheckTexts(check: ResponseJsonCheck, text: (value: string) => string, pattern: (value: string) => string = text): ResponseJsonCheck {
|
|
1115
|
+
const out = { ...check };
|
|
1116
|
+
for (const field of JSON_CHECK_TEXTS) {
|
|
1117
|
+
const value = check[field];
|
|
1118
|
+
if (value !== undefined) out[field] = field === "pattern" ? pattern(value) : text(value);
|
|
1119
|
+
}
|
|
1120
|
+
return out;
|
|
1121
|
+
}
|
|
1122
|
+
|
|
1123
|
+
/** JSON Pointer keeps field names containing dots, slashes or brackets unambiguous. */
|
|
1124
|
+
export function responseJsonProblem(checks: unknown): string | undefined {
|
|
1125
|
+
if (!Array.isArray(checks) || checks.length === 0) return "must be a non-empty list of JSON field checks";
|
|
1126
|
+
for (const c of checks) {
|
|
1127
|
+
if (!c || typeof c !== "object" || typeof c.path !== "string" || !/^(?:\/(?:[^~]|~[01])*)*$/.test(c.path)) return "each path must be a JSON Pointer, such as /order/status or /items/0/sku";
|
|
1128
|
+
const kinds = ["equals", "exists", "item", "every", "count", "differs", "pattern"].filter((k) => c[k] !== undefined).length + (c.min !== undefined || c.max !== undefined ? 1 : 0);
|
|
1129
|
+
if (kinds !== 1) return "each check needs exactly one of equals, differs, exists, pattern, min and/or max, count, item or every";
|
|
1130
|
+
for (const list of ["item", "every"] as const) {
|
|
1131
|
+
if (c[list] !== undefined) {
|
|
1132
|
+
const inner = responseJsonProblem(c[list]);
|
|
1133
|
+
if (inner) return `${list} ${inner}`;
|
|
1134
|
+
}
|
|
1135
|
+
}
|
|
1136
|
+
for (const field of JSON_CHECK_TEXTS) if (c[field] !== undefined && typeof c[field] !== "string") return `${field} must be a string`;
|
|
1137
|
+
if (c.exists !== undefined && typeof c.exists !== "boolean") return "exists must be true or false";
|
|
1138
|
+
if (c.type !== undefined && (!["string", "number", "boolean", "null"].includes(c.type) || (c.equals === undefined && c.differs === undefined))) return "type must be string, number, boolean or null, on an equals or differs check";
|
|
1139
|
+
}
|
|
1140
|
+
}
|
|
1141
|
+
|
|
1142
|
+
/** The value a check compares with (`equals`, or the text given), read as the check's type. */
|
|
1143
|
+
export function jsonExpected(check: ResponseJsonCheck, text: string | undefined = check.equals): unknown {
|
|
1144
|
+
if (check.type === undefined || check.type === "string") return text;
|
|
1145
|
+
let value: unknown;
|
|
1146
|
+
try { value = JSON.parse(text!); } catch { /* Name the field without echoing a secret or JSON parse excerpt. */ }
|
|
1147
|
+
// Beyond 2^53 two different numbers parse equal: such a check would pass on another value.
|
|
1148
|
+
if (typeof value === "number" && Number.isInteger(value) && !Number.isSafeInteger(value)) {
|
|
1149
|
+
throw new Error(`JSON field ${JSON.stringify(check.path)}: ${text} is too large to compare exactly as a number; check it as a string`);
|
|
1150
|
+
}
|
|
1151
|
+
if ((check.type === "null" ? value === null : typeof value === check.type) && (typeof value !== "number" || Number.isFinite(value))) return value;
|
|
1152
|
+
throw new Error(`JSON field ${JSON.stringify(check.path)}: expected value must be a valid ${check.type}`);
|
|
1153
|
+
}
|
|
1154
|
+
|
|
1155
|
+
/** A check's number (count, min, max) as a number, or why it is none. */
|
|
1156
|
+
function jsonNumber(check: ResponseJsonCheck, field: "count" | "min" | "max"): number {
|
|
1157
|
+
const text = check[field]!.trim();
|
|
1158
|
+
const value = Number(text);
|
|
1159
|
+
if (text === "" || !Number.isFinite(value) || (field === "count" && (!Number.isInteger(value) || value < 0))) throw new Error(`JSON field ${JSON.stringify(check.path)}: ${field} must be a ${field === "count" ? "whole number" : "number"}, got ${JSON.stringify(check[field])}`);
|
|
1160
|
+
return value;
|
|
1161
|
+
}
|
|
1162
|
+
|
|
1163
|
+
/** Every number a resolved check compares with must read as one: refused before the response is looked at. */
|
|
1164
|
+
export function jsonChecksReadable(checks: ResponseJsonCheck[]): void {
|
|
1165
|
+
for (const c of flatJsonChecks(checks)) {
|
|
1166
|
+
if (c.equals !== undefined) jsonExpected(c);
|
|
1167
|
+
if (c.differs !== undefined) jsonExpected(c, c.differs);
|
|
1168
|
+
for (const field of ["count", "min", "max"] as const) if (c[field] !== undefined) jsonNumber(c, field);
|
|
1169
|
+
if (c.pattern !== undefined) jsonPattern(c);
|
|
1170
|
+
}
|
|
1171
|
+
}
|
|
1172
|
+
|
|
1173
|
+
function jsonPattern(check: ResponseJsonCheck): RegExp {
|
|
1174
|
+
try {
|
|
1175
|
+
// A row value bounded in it (resolveTokens) needs unicode mode, as a browser pattern does.
|
|
1176
|
+
return patternRegex(check.pattern!);
|
|
1177
|
+
} catch {
|
|
1178
|
+
throw new Error(`JSON field ${JSON.stringify(check.path)}: pattern ${JSON.stringify(check.pattern)} is not a regular expression`);
|
|
1179
|
+
}
|
|
1180
|
+
}
|
|
1181
|
+
|
|
1182
|
+
const kind = (value: unknown) => value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
|
|
1183
|
+
const describe = (value: unknown) => `${kind(value)}${value === null || typeof value !== "object" ? ` ${JSON.stringify(value)}` : ""}`;
|
|
1184
|
+
|
|
1185
|
+
/** The value at a JSON Pointer: own properties and array indexes only, undefined when missing. */
|
|
1186
|
+
function at(json: unknown, path: string): unknown {
|
|
1187
|
+
let value = json;
|
|
1188
|
+
for (const part of path === "" ? [] : path.slice(1).split("/")) {
|
|
1189
|
+
const key = part.replace(/~1/g, "/").replace(/~0/g, "~");
|
|
1190
|
+
value = value !== null && typeof value === "object" && (!Array.isArray(value) || /^(0|[1-9]\d*)$/.test(key)) && Object.hasOwn(value, key)
|
|
1191
|
+
? (value as Record<string, unknown>)[key] : undefined;
|
|
1192
|
+
}
|
|
1193
|
+
return value;
|
|
1194
|
+
}
|
|
1195
|
+
|
|
1196
|
+
/** What an item check looks for, for a message: `name "ann", text present`. */
|
|
1197
|
+
const wanted = (checks: ResponseJsonCheck[]): string =>
|
|
1198
|
+
checks.map((c) => `${c.path || "the item"} ${
|
|
1199
|
+
c.item ? `holding an item with ${wanted(c.item)}`
|
|
1200
|
+
: c.every ? `every item with ${wanted(c.every)}`
|
|
1201
|
+
: c.exists !== undefined ? (c.exists ? "present" : "absent")
|
|
1202
|
+
: c.count !== undefined ? `of ${c.count} item(s)`
|
|
1203
|
+
: c.differs !== undefined ? `other than ${JSON.stringify(c.differs)}`
|
|
1204
|
+
: c.pattern !== undefined ? `matching /${c.pattern}/`
|
|
1205
|
+
: c.min !== undefined || c.max !== undefined ? [c.min !== undefined ? `at least ${c.min}` : "", c.max !== undefined ? `at most ${c.max}` : ""].filter(Boolean).join(" and ")
|
|
1206
|
+
: JSON.stringify(c.equals)}`).join(", ");
|
|
1207
|
+
|
|
1208
|
+
/** Why the checks do not hold on a parsed value, or undefined. */
|
|
1209
|
+
function checkValue(json: unknown, checks: ResponseJsonCheck[], prefix = ""): string | undefined {
|
|
1210
|
+
for (const check of checks) {
|
|
1211
|
+
const value = at(json, check.path);
|
|
1212
|
+
const field = `JSON field ${JSON.stringify(prefix + check.path)}`;
|
|
1213
|
+
const got = value === undefined ? "missing" : describe(value);
|
|
1214
|
+
if (check.item) {
|
|
1215
|
+
if (!Array.isArray(value)) return `${field}: expected a list, got ${got}`;
|
|
1216
|
+
if (!value.some((entry) => checkValue(entry, check.item!) === undefined)) return `${field}: none of its ${value.length} item(s) has ${wanted(check.item)}`;
|
|
1217
|
+
} else if (check.every) {
|
|
1218
|
+
// An empty list holds nothing: "every order is paid" over no orders is no check.
|
|
1219
|
+
if (!Array.isArray(value)) return `${field}: expected a list, got ${got}`;
|
|
1220
|
+
if (value.length === 0) return `${field}: expected a list with items, every one with ${wanted(check.every)}, got an empty list`;
|
|
1221
|
+
for (const [i, entry] of value.entries()) {
|
|
1222
|
+
const problem = checkValue(entry, check.every, `${prefix}${check.path}/${i}`);
|
|
1223
|
+
if (problem) return problem;
|
|
1224
|
+
}
|
|
1225
|
+
} else if (check.count !== undefined) {
|
|
1226
|
+
const expected = jsonNumber(check, "count");
|
|
1227
|
+
if (!Array.isArray(value)) return `${field}: expected a list, got ${got}`;
|
|
1228
|
+
if (value.length !== expected) return `${field}: expected ${expected} item(s), got ${value.length}`;
|
|
1229
|
+
} else if (check.exists !== undefined) {
|
|
1230
|
+
if ((value !== undefined) !== check.exists) return `${field}: expected ${check.exists ? "present, got missing" : `absent, got ${describe(value)}`}`;
|
|
1231
|
+
} else if (check.differs !== undefined) {
|
|
1232
|
+
const other = jsonExpected(check, check.differs);
|
|
1233
|
+
if (value === undefined) return `${field}: expected a value other than ${describe(other)}, got missing`;
|
|
1234
|
+
// Untyped, the text is compared as written: a number 5 is the same as "5" (a captured id is kept as text).
|
|
1235
|
+
if (value === other || (check.type === undefined && value !== null && typeof value !== "object" && String(value) === other)) return `${field}: expected a value other than ${describe(other)}, got the same`;
|
|
1236
|
+
} else if (check.pattern !== undefined) {
|
|
1237
|
+
const re = jsonPattern(check);
|
|
1238
|
+
if (typeof value !== "string") return `${field}: expected text matching /${check.pattern}/, got ${got}`;
|
|
1239
|
+
if (!re.test(value)) return `${field}: expected text matching /${check.pattern}/, got ${JSON.stringify(value)}`;
|
|
1240
|
+
} else if (check.min !== undefined || check.max !== undefined) {
|
|
1241
|
+
const min = check.min === undefined ? undefined : jsonNumber(check, "min");
|
|
1242
|
+
const max = check.max === undefined ? undefined : jsonNumber(check, "max");
|
|
1243
|
+
const bounds = [min !== undefined ? `at least ${min}` : "", max !== undefined ? `at most ${max}` : ""].filter(Boolean).join(" and ");
|
|
1244
|
+
if (typeof value !== "number") return `${field}: expected a number ${bounds}, got ${got}`;
|
|
1245
|
+
if ((min !== undefined && value < min) || (max !== undefined && value > max)) return `${field}: expected a number ${bounds}, got ${value}`;
|
|
1246
|
+
} else {
|
|
1247
|
+
const expected = jsonExpected(check);
|
|
1248
|
+
if (value !== expected) return `${field}: expected ${describe(expected)}, got ${got}`;
|
|
1249
|
+
}
|
|
1250
|
+
}
|
|
1251
|
+
return undefined;
|
|
1252
|
+
}
|
|
1253
|
+
|
|
1254
|
+
/** A missing property is different from a property whose value is null. */
|
|
1255
|
+
export function checkResponseJson(body: string | undefined, checks: ResponseJsonCheck[]): string | undefined {
|
|
1256
|
+
if (body === undefined) return "response body is pending, unreadable or not a supported text content type";
|
|
1257
|
+
let json: unknown;
|
|
1258
|
+
try { json = JSON.parse(body); } catch { return "response body is not valid JSON"; }
|
|
1259
|
+
return checkValue(json, checks);
|
|
1260
|
+
}
|
|
1261
|
+
|
|
1262
|
+
/** Unicode boundaries need unicode mode; preserve legacy flags on patterns without them. */
|
|
1263
|
+
export function patternRegex(source: string, flags = ""): RegExp {
|
|
1264
|
+
if (/[uv]/.test(flags) || source.includes(String.raw`[\p{L}\p{N}\p{M}]`)) {
|
|
1265
|
+
// Playwright escapes quotes and chain separators; unicode regexes use hex escapes.
|
|
1266
|
+
source = source.replace(/\\.|[\s\S]/g, part => /^\\['"`>\-]$/.test(part) ? `\\x${part.charCodeAt(1).toString(16)}` : part);
|
|
1267
|
+
if (!/[uv]/.test(flags)) flags += "u";
|
|
1268
|
+
}
|
|
1269
|
+
return new RegExp(source, flags);
|
|
1270
|
+
}
|
|
1271
|
+
/*END*/
|