@sdods/core 0.2.2 → 0.3.1

package/dist/steps/net.steps.js

@@ -0,0 +1,728 @@
+import { expect } from '@playwright/test';
+import './params.js';
+import { Given, Then, When } from '../fixtures/test.js';
+import { coerce, getPath } from '../api/json-path.js';
+import { render } from '../api/template.js';
+import { SdodsError } from '../errors.js';
+const scopesOf = (apiContext, env) => [
+    apiContext.vars.toObject(),
+    env.vars,
+];
+/**
+ * Render, then refuse a surviving `{{var}}`. Used for every argument whose non-resolution would
+ * produce a PASS rather than a failure: negative assertions, URL globs and request paths.
+ */
+function renderStrict(value, what, ...scopes) {
+    const out = render(value, ...scopes);
+    if (out.includes('{{')) {
+        throw new SdodsError('CONFIG_UNRESOLVED_VAR', `${what} did not resolve: "${out}".`, {
+            hint: 'No scenario variable or env var of that name exists yet. Save it first (for example with "I save the response JSON path ... as ..."), or fix the spelling — an unresolved placeholder here would make the assertion pass without testing anything.',
+        });
+    }
+    return out;
+}
+/** Comma-separated Gherkin list → trimmed, rendered, non-empty items. */
+function renderList(raw, what, ...scopes) {
+    const items = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => renderStrict(s, what, ...scopes));
+    if (items.length === 0)
+        throw new SdodsError('RUN_FAILED', `${what} is empty.`, {
+            hint: 'List at least one comma-separated value; an empty list would make this assertion pass over nothing.',
+        });
+    return items;
+}
+/** A response body as searchable text. `null`/absent stays EMPTY, so an empty-body guard bites. */
+function bodyText(body) {
+    if (body === null || body === undefined)
+        return '';
+    return typeof body === 'string' ? body : JSON.stringify(body);
+}
+/** Best-effort evidence for an @api scenario, which takes no screenshots. Never fails a step. */
+async function attachEvidence(testInfo, name, payload) {
+    try {
+        await testInfo?.attach(name, {
+            body: JSON.stringify(payload, null, 2),
+            contentType: 'application/json',
+        });
+    }
+    catch {
+        /* evidence is best-effort; losing it must not turn a green step red */
+    }
+}
+const RAW = new WeakMap();
+const RAW_BODIES = new WeakMap();
+function rawOf(apiContext) {
+    const snap = RAW.get(apiContext);
+    if (!snap)
+        throw new SdodsError('RUN_FAILED', 'No raw request has been sent in this scenario yet.', {
+            hint: 'Send one first with `When I send a GET request to "/path" without following redirects`. The built-in `I send a ... request` steps follow redirects and redact Set-Cookie, so their response is not visible to the raw assertions.',
+        });
+    return snap;
+}
+function savedBodies(apiContext) {
+    let bag = RAW_BODIES.get(apiContext);
+    if (!bag) {
+        bag = new Map();
+        RAW_BODIES.set(apiContext, bag);
+    }
+    return bag;
+}
+/** The auth the ApiClient would have applied, so a raw request is not silently anonymous. */
+function envAuth(auth) {
+    switch (auth.type) {
+        case 'bearer':
+            return { type: 'bearer', token: auth.token };
+        case 'basic':
+            return { type: 'basic', username: auth.username, password: auth.password };
+        case 'header':
+            return { type: 'header', name: auth.name, value: auth.value };
+        default:
+            return undefined;
+    }
+}
+/**
+ * Mirrors `ApiClient.buildHeaders` — env headers, then the scenario's pending headers, then auth.
+ * A raw request that dropped auth would report the anonymous redirect instead of the
+ * authenticated one, which is the same class of defect as a step that does not interpolate.
+ * `accept: application/json` is the default; override it with
+ * `Given I set the request header "accept" to "text/html"` when the gate under test negotiates
+ * on content type.
+ */
+function rawHeaders(apiContext, env, hasBody, isForm) {
+    const headers = { accept: 'application/json' };
+    for (const [k, v] of Object.entries(env.api.headers ?? {}))
+        headers[k.toLowerCase()] = v;
+    for (const [k, v] of apiContext.headers)
+        headers[k.toLowerCase()] = v;
+    if (hasBody && !isForm && !headers['content-type'])
+        headers['content-type'] = 'application/json';
+    const auth = apiContext.auth ?? envAuth(env.api.auth);
+    if (auth) {
+        if (auth.type === 'bearer')
+            headers.authorization = `Bearer ${auth.token}`;
+        else if (auth.type === 'basic')
+            headers.authorization = `Basic ${Buffer.from(`${auth.username}:${auth.password}`).toString('base64')}`;
+        else if (auth.type === 'header')
+            headers[auth.name.toLowerCase()] = auth.value;
+    }
+    return headers;
+}
+/** Mirrors `ApiClient.resolveUrl`, so `Given I set the query parameter …` applies here too. */
+function rawUrl(apiContext, env, pathOrUrl) {
+    const base = env.api.baseUrl.replace(/\/+$/, '');
+    const url = /^https?:\/\//.test(pathOrUrl)
+        ? new URL(pathOrUrl)
+        : new URL(`${base}/${pathOrUrl.replace(/^\/+/, '')}`);
+    for (const [k, v] of apiContext.query)
+        url.searchParams.set(k, v);
+    return url.toString();
+}
+/**
+ * One request with `maxRedirects: 0`. The whole point is to keep the 3xx instead of chasing it,
+ * and to keep `Set-Cookie` unredacted — the two things the recorded ApiSnapshot cannot carry.
+ */
+export async function sendRaw(deps, method, pathOrUrl, opts = {}) {
+    const url = rawUrl(deps.apiContext, deps.env, pathOrUrl);
+    const headers = rawHeaders(deps.apiContext, deps.env, opts.body !== undefined || opts.form !== undefined, opts.form !== undefined);
+    const res = await deps.request.fetch(url, {
+        method,
+        headers,
+        data: opts.form ? undefined : opts.body,
+        form: opts.form,
+        maxRedirects: 0,
+        failOnStatusCode: false,
+        timeout: deps.config.project.timeouts.api,
+    });
+    const raw = {};
+    for (const [k, v] of Object.entries(res.headers()))
+        raw[k.toLowerCase()] = v;
+    const snap = {
+        method,
+        url,
+        requestBody: opts.body,
+        status: res.status(),
+        statusText: res.statusText(),
+        headers: raw,
+        setCookies: res
+            .headersArray()
+            .filter((h) => h.name.toLowerCase() === 'set-cookie')
+            .map((h) => h.value),
+        body: await res.text(),
+    };
+    RAW.set(deps.apiContext, snap);
+    // Keeping Set-Cookie readable by the ASSERTIONS is the point of this family; keeping it
+    // readable in the attached artefact is not. The report copy is redacted to exactly what
+    // ApiClient redacts, and the cookie NAMES carry everything a reader of the report needs.
+    await attachEvidence(deps.testInfo, `sdods/raw-${method.toLowerCase()}-${snap.status}`, {
+        request: { method, url, headers: redactForReport(headers), body: opts.body, form: opts.form },
+        response: {
+            status: snap.status,
+            statusText: snap.statusText,
+            headers: redactForReport(snap.headers),
+            setCookieNames: snap.setCookies.map((c) => c.split('=')[0]),
+            body: snap.body.slice(0, 4000),
+        },
+    });
+    return snap;
+}
+/** The header set ApiClient redacts, applied to the reported copy only. */
+const SECRET_HEADERS = /^(authorization|cookie|set-cookie|x-api-key|proxy-authorization)$/i;
+export function redactForReport(headers) {
+    return Object.fromEntries(Object.entries(headers).map(([k, v]) => [k, SECRET_HEADERS.test(k) ? '***' : v]));
+}
+When('I send a {method} request to {string} without following redirects', async ({ request, apiContext, env, config, $testInfo }, method, path) => {
+    // PROVES the edge itself answered. The built-in step would follow the 3xx and report the
+    // page it landed on, so an auth/locale/maintenance gate is unobservable through it.
+    await sendRaw({ request, apiContext, env, config, testInfo: $testInfo }, method, renderStrict(path, 'the request path', ...scopesOf(apiContext, env)));
+});
+When('I send a {method} request to {string} without following redirects with body:', async ({ request, apiContext, env, config, $testInfo }, method, path, body) => {
+    // Body stays TEXT, never re-serialised JSON: the byte-identical comparison below is only an
+    // oracle for enumeration safety if nothing normalises whitespace or key order on the way in.
+    const scopes = scopesOf(apiContext, env);
+    await sendRaw({ request, apiContext, env, config, testInfo: $testInfo }, method, renderStrict(path, 'the request path', ...scopes), { body: render(body, ...scopes) });
+});
+When('I send a {method} request to {string} without following redirects with form:', async ({ request, apiContext, env, config, $testInfo }, method, path, table) => {
+    // PROVES a form POST's gate. Most real redirect gates — sign-in, consent, locale switch —
+    // are urlencoded form posts, so a JSON-only raw request cannot reach the common case.
+    const scopes = scopesOf(apiContext, env);
+    const form = {};
+    for (const row of table.raw())
+        form[String(row[0] ?? '')] = render(String(row[1] ?? ''), ...scopes);
+    await sendRaw({ request, apiContext, env, config, testInfo: $testInfo }, method, renderStrict(path, 'the request path', ...scopes), { form });
+});
+Then('the raw response status should be {int}', async ({ apiContext }, status) => {
+    // PROVES the gate fired at this hop. A 307 that a following client turns into a 200 is the
+    // single most common invisible-pass in an API suite.
+    const snap = rawOf(apiContext);
+    expect(snap.status, `${snap.method} ${snap.url}`).toBe(status);
+});
+Then('the raw response status should be one of {string}', async ({ apiContext }, list) => {
+    const allowed = list
+        .split(/[,\s]+/)
+        .filter(Boolean)
+        .map(Number);
+    if (allowed.length === 0 || allowed.some(Number.isNaN))
+        throw new SdodsError('RUN_FAILED', `"${list}" is not a list of status codes.`, {
+            hint: 'Write them comma- or space-separated, for example "301, 302, 307".',
+        });
+    const snap = rawOf(apiContext);
+    expect(allowed, `${snap.method} ${snap.url} returned ${snap.status}`).toContain(snap.status);
+});
+Then('the raw response Location should be {string}', async ({ apiContext, env }, expected) => {
+    // Exact, not substring: the surviving return-to/callback parameter IS the assertion, and a
+    // `contains` check would pass on a truncated one that silently drops where the user came from.
+    const snap = rawOf(apiContext);
+    expect(snap.headers.location ?? '(no Location header)', `Location of ${snap.url}`).toBe(render(expected, ...scopesOf(apiContext, env)));
+});
+Then('the raw response Location should contain {string}', async ({ apiContext, env }, expected) => {
+    const snap = rawOf(apiContext);
+    expect(snap.headers.location ?? '(no Location header)', `Location of ${snap.url}`).toContain(render(expected, ...scopesOf(apiContext, env)));
+});
+Then('the raw response header {string} should contain {string}', async ({ apiContext, env }, name, value) => {
+    const scopes = scopesOf(apiContext, env);
+    const wanted = render(name, ...scopes);
+    const snap = rawOf(apiContext);
+    expect(snap.headers[wanted.toLowerCase()] ?? `(no ${wanted} header)`, `${wanted} of ${snap.url}`).toContain(render(value, ...scopes));
+});
+Then('the raw response should have no {string} header', async ({ apiContext, env }, name) => {
+    // The deny direction, and NOT the same as "does not contain": an `Allow` header present but
+    // empty, or a `Set-Cookie` present but rejected, are both absences a contains-check would miss.
+    const wanted = renderStrict(name, 'the header name', ...scopesOf(apiContext, env));
+    const snap = rawOf(apiContext);
+    expect(snap.headers[wanted.toLowerCase()], `unexpected ${wanted} header on ${snap.url}`).toBeUndefined();
+});
+Then('the raw response body should contain {string}', async ({ apiContext, env }, text) => {
+    expect(rawOf(apiContext).body).toContain(render(text, ...scopesOf(apiContext, env)));
+});
+Then('the raw response should set the {string} cookie', async ({ apiContext, env }, name) => {
+    // PROVES the credential was actually issued. Unreachable through the built-in header step,
+    // which sees `set-cookie: ***` because the ApiSnapshot redacts it.
+    const wanted = renderStrict(name, 'the cookie name', ...scopesOf(apiContext, env));
+    const snap = rawOf(apiContext);
+    expect(snap.setCookies.some((c) => c.startsWith(`${wanted}=`)), `Set-Cookie for "${wanted}" (got ${JSON.stringify(snap.setCookies.map((c) => c.split('=')[0]))})`).toBe(true);
+});
+Then('the raw response should not set the {string} cookie', async ({ apiContext, env }, name) => {
+    // PROVES a refusal left no credential behind. A `Max-Age=0` line is a deletion, not a grant,
+    // so it must not count as one — otherwise a correct sign-out would read as a session leak.
+    const wanted = renderStrict(name, 'the cookie name', ...scopesOf(apiContext, env));
+    const snap = rawOf(apiContext);
+    expect(snap.setCookies.filter((c) => c.startsWith(`${wanted}=`) && !isCleared(c)), `no Set-Cookie granting "${wanted}"`).toEqual([]);
+});
+Then('the raw response cookie {string} should carry {string}', async ({ apiContext, env }, name, attribute) => {
+    // HttpOnly / Secure / SameSite=Lax / Path=/ — the session contract every downstream gate
+    // reads. Matched case-insensitively because servers disagree on the casing of attributes.
+    const scopes = scopesOf(apiContext, env);
+    const wanted = renderStrict(name, 'the cookie name', ...scopes);
+    const attr = render(attribute, ...scopes);
+    const cookie = rawOf(apiContext).setCookies.find((c) => c.startsWith(`${wanted}=`));
+    expect(cookie, `Set-Cookie for "${wanted}"`).toBeTruthy();
+    expect(String(cookie).toLowerCase(), `attributes of the "${wanted}" cookie`).toContain(attr.toLowerCase());
+});
+Then('the raw response cookie {string} should be cleared', async ({ apiContext, env }, name) => {
+    // PROVES sign-out server-side: a deletion is a Set-Cookie with an immediate expiry, which is
+    // what "the browser no longer holds the credential" actually means over the wire.
+    const wanted = renderStrict(name, 'the cookie name', ...scopesOf(apiContext, env));
+    const cookie = rawOf(apiContext).setCookies.find((c) => c.startsWith(`${wanted}=`));
+    expect(cookie, `Set-Cookie clearing "${wanted}"`).toBeTruthy();
+    expect(isCleared(String(cookie)), `expiry of the "${wanted}" cookie`).toBe(true);
+});
+function isCleared(cookie) {
+    return /Max-Age=0|Expires=Thu,\s*01[ -]Jan[ -]1970/i.test(cookie);
+}
+When('I save the raw response body as {string}', async ({ apiContext }, name) => {
+    savedBodies(apiContext).set(name, rawOf(apiContext).body);
+});
+Then('the raw response body should be identical to {string}', async ({ apiContext }, name) => {
+    // Byte-identical, not "both say no such account". An enumeration-safe endpoint that varies
+    // its wording, whitespace or field order between the two cases is still an oracle.
+    const saved = savedBodies(apiContext).get(name);
+    if (saved === undefined)
+        throw new SdodsError('RUN_FAILED', `No raw body was saved under "${name}".`, {
+            hint: 'Send the first request and store it with `When I save the raw response body as "<name>"` before comparing the second one against it.',
+        });
+    expect(rawOf(apiContext).body, `raw body vs. the one saved as "${name}"`).toBe(saved);
+});
+/* ── downloads ────────────────────────────────────────────────────────── */
+const DOWNLOADS = new WeakMap();
+const DOWNLOAD_TEXT = new WeakMap();
+function downloadOf(page) {
+    const download = DOWNLOADS.get(page);
+    if (!download)
+        throw new SdodsError('RUN_FAILED', 'No download has been captured in this scenario yet.', {
+            hint: 'Capture one first with `When I click the "Export" button and capture the download`. A download must be captured at the moment the click happens — it cannot be read afterwards.',
+        });
+    return download;
+}
+async function downloadedText(page) {
+    const cached = DOWNLOAD_TEXT.get(page);
+    if (cached !== undefined)
+        return cached;
+    const download = downloadOf(page);
+    const file = await download.path();
+    if (!file) {
+        const failure = await download.failure();
+        throw new SdodsError('RUN_FAILED', `The download never completed${failure ? `: ${failure}` : ''}.`, {
+            hint: 'Playwright discards a download unless the browser context was created with `acceptDownloads: true` (the default), and reports null here when the transfer failed. Check the reason above before blaming the step.',
+        });
+    }
+    const { readFile } = await import('node:fs/promises');
+    const text = await readFile(file, 'utf8');
+    if (text.length === 0)
+        throw new SdodsError('RUN_FAILED', `The downloaded file "${download.suggestedFilename()}" is empty.`, {
+            hint: 'An empty export is a product failure, and every assertion below would pass vacuously over it, so this refuses rather than reporting green.',
+        });
+    DOWNLOAD_TEXT.set(page, text);
+    return text;
+}
+async function captureDownload(page, timeout, click) {
+    const [download] = await Promise.all([page.waitForEvent('download', { timeout }), click()]);
+    DOWNLOADS.set(page, download);
+    DOWNLOAD_TEXT.delete(page);
+}
+When('I click the {string} {role} and capture the download', async ({ page, heal, config, apiContext, env }, name, role) => {
+    // PROVES an export produced a file at all. Without this the whole export feature can only be
+    // asserted as "the click did not throw", which is true of a button wired to nothing.
+    const n = render(name, ...scopesOf(apiContext, env));
+    const loc = await heal.resolve(page.getByRole(role, { name: n }), { role: role, name: n, text: n, description: `${role} "${n}"` }, 'click');
+    await captureDownload(page, config.project.timeouts.navigation, () => loc.click());
+});
+When('I click the element with test id {string} and capture the download', async ({ page, heal, config }, id) => {
+    const loc = await heal.resolve(page.getByTestId(id), { testId: id, description: `test id "${id}"` }, 'click');
+    await captureDownload(page, config.project.timeouts.navigation, () => loc.click());
+});
+Then('the downloaded file name should end with {string}', async ({ page, apiContext, env }, suffix) => {
+    // `endsWith`, not `contains`: a ".json" that appears mid-name (report.json.txt) is the exact
+    // mis-typed export this assertion exists to catch.
+    const wanted = render(suffix, ...scopesOf(apiContext, env));
+    const actual = downloadOf(page).suggestedFilename();
+    expect(actual.endsWith(wanted), `download filename "${actual}" should end with "${wanted}"`).toBe(true);
+});
+Then('the downloaded file name should contain {string}', async ({ page, apiContext, env }, part) => {
+    expect(downloadOf(page).suggestedFilename(), 'download filename').toContain(render(part, ...scopesOf(apiContext, env)));
+});
+Then('the downloaded text first line should be {string}', async ({ page, apiContext, env }, expected) => {
+    // PROVES the header row of a CSV export matches the columns the UI promised. Exact, because a
+    // reordered or renamed column silently breaks every consumer of the file.
+    const text = await downloadedText(page);
+    expect(text.split(/\r?\n/)[0] ?? '', 'first line of the downloaded file').toBe(render(expected, ...scopesOf(apiContext, env)));
+});
+Then('the downloaded text should contain {string}', async ({ page, apiContext, env }, text) => {
+    expect(await downloadedText(page), 'downloaded file').toContain(render(text, ...scopesOf(apiContext, env)));
+});
+Then('the downloaded text should have at least {int} data rows', async ({ page }, min) => {
+    expect(dataRows(await downloadedText(page)), 'data rows in the downloaded file').toBeGreaterThanOrEqual(min);
+});
+Then('the downloaded text should have at most {int} data rows', async ({ page }, max) => {
+    // PROVES an export cap. Safe from vacuity because `downloadedText` refuses an empty file, so
+    // "at most N" can never be satisfied by nothing having been exported.
+    expect(dataRows(await downloadedText(page)), 'data rows in the downloaded file').toBeLessThanOrEqual(max);
+});
+/** Non-blank lines after the header row. */
+function dataRows(text) {
+    const lines = text.split(/\r?\n/).filter((l) => l.trim() !== '');
+    return Math.max(0, lines.length - 1);
+}
+async function downloadedJson(page) {
+    const text = await downloadedText(page);
+    try {
+        return JSON.parse(text);
+    }
+    catch (e) {
+        throw new SdodsError('RUN_FAILED', `The downloaded file is not JSON: ${e.message}`, {
+            hint: `First 200 characters: ${text.slice(0, 200)}`,
+        });
+    }
+}
+Then('the downloaded JSON path {string} should equal {string}', async ({ page, apiContext, env }, path, expected) => {
+    // PROVES the export/import round trip, not just that a file arrived: a scenario that can
+    // export but never read what it exported proves only that a click did not throw.
+    const actual = getPath(await downloadedJson(page), path);
+    expect(actual, `downloaded JSON path ${path}`).toEqual(coerce(render(expected, ...scopesOf(apiContext, env))));
+});
+Then('the downloaded JSON path {string} should have {int} items', async ({ page }, path, count) => {
+    // Arrays and keyed records both count, because exports model collections either way; anything
+    // else fails loudly rather than counting as zero.
+    const value = getPath(await downloadedJson(page), path);
+    if (Array.isArray(value)) {
+        expect(value, `downloaded JSON path ${path} length`).toHaveLength(count);
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        expect(Object.keys(value), `downloaded JSON path ${path} key count`).toHaveLength(count);
+        return;
+    }
+    throw new SdodsError('RUN_FAILED', `Downloaded JSON path ${path} is not a collection.`, {
+        hint: `It is ${value === undefined ? 'absent' : typeof value}. Point the path at an array or an object whose keys are the items.`,
+    });
+});
+const STREAMS = new WeakMap();
+const STREAM_TIMEOUT = new WeakMap();
+/**
+ * Parse an SSE body into frames. Frames are separated by a blank line; `data:` lines within one
+ * frame join with a newline; a frame carrying only a comment (`: keepalive`) is not an event.
+ */
+export function parseEventStream(text) {
+    const events = [];
+    for (const frame of text.split(/\r?\n\r?\n/)) {
+        if (frame.trim() === '')
+            continue;
+        let name;
+        const data = [];
+        for (const line of frame.split(/\r?\n/)) {
+            if (line.startsWith(':'))
+                continue;
+            if (line.startsWith('event:'))
+                name = line.slice(6).trim();
+            else if (line.startsWith('data:'))
+                data.push(line.slice(5).replace(/^ /, ''));
+        }
+        if (name === undefined && data.length === 0)
+            continue;
+        const payload = data.join('\n');
+        let json;
+        try {
+            json = payload.length ? JSON.parse(payload) : undefined;
+        }
+        catch {
+            /* a non-JSON frame is still an event; its type is then the `event:` field alone */
+        }
+        const fromJson = json !== null && typeof json === 'object' && 'type' in json
+            ? String(json.type)
+            : undefined;
+        const sentinel = /^\[[A-Z_]+\]$/.test(payload) ? payload : undefined;
+        events.push({ type: name ?? fromJson ?? sentinel, data: payload, json });
+    }
+    return { events, endedWithDelimiter: /\r?\n\r?\n\s*$/.test(text) };
+}
+function streamOf(apiContext) {
+    const capture = STREAMS.get(apiContext);
+    if (!capture)
+        throw new SdodsError('RUN_FAILED', 'No event stream has been read in this scenario yet.', {
+            hint: 'Read one first with `When I read the event stream from a POST request to "/chat" with body:`. The built-in `I send a ... request` steps buffer and JSON-parse the body, which a text/event-stream response is not.',
+        });
+    return capture;
+}
+async function readStream(deps, method, pathOrUrl, body) {
+    const headers = rawHeaders(deps.apiContext, deps.env, body !== undefined, false);
+    headers.accept = 'text/event-stream';
+    const url = rawUrl(deps.apiContext, deps.env, pathOrUrl);
+    const timeout = STREAM_TIMEOUT.get(deps.apiContext) ?? deps.config.project.timeouts.api;
+    let capture;
+    try {
+        const res = await deps.request.fetch(url, {
+            method,
+            headers,
+            data: body,
+            maxRedirects: 0,
+            failOnStatusCode: false,
+            timeout,
+        });
+        const text = await res.text();
+        capture = {
+            status: res.status(),
+            contentType: res.headers()['content-type'] ?? '',
+            ...parseEventStream(text),
+        };
+    }
+    catch (e) {
+        // A stream that dies mid-flight surfaces here, not as a status — record the reason so the
+        // clean-termination step fails with it rather than with "no stream captured".
+        capture = {
+            status: 0,
+            contentType: '',
+            events: [],
+            endedWithDelimiter: false,
+            error: e.message,
+        };
+    }
+    STREAMS.set(deps.apiContext, capture);
+    await attachEvidence(deps.testInfo, `sdods/stream-${method.toLowerCase()}-${capture.status}`, {
+        url,
+        status: capture.status,
+        contentType: capture.contentType,
+        eventCount: capture.events.length,
+        eventTypes: capture.events.map((e) => e.type),
+        endedWithDelimiter: capture.endedWithDelimiter,
+        error: capture.error,
+    });
+    return capture;
+}
+Given('I allow {int} seconds for the event stream', async ({ apiContext }, seconds) => {
+    // A long turn outlives `timeouts.api`, and that timeout would surface as a red step that looks
+    // exactly like a product bug — the worst kind of false failure.
+    STREAM_TIMEOUT.set(apiContext, seconds * 1000);
+});
+When('I read the event stream from a {method} request to {string}', async ({ request, apiContext, env, config, $testInfo }, method, path) => {
+    await readStream({ request, apiContext, env, config, testInfo: $testInfo }, method, renderStrict(path, 'the request path', ...scopesOf(apiContext, env)));
+});
+When('I read the event stream from a {method} request to {string} with body:', async ({ request, apiContext, env, config, $testInfo }, method, path, body) => {
+    const scopes = scopesOf(apiContext, env);
+    await readStream({ request, apiContext, env, config, testInfo: $testInfo }, method, renderStrict(path, 'the request path', ...scopes), render(body, ...scopes));
+});
+Then('the stream status should be {int}', async ({ apiContext }, status) => {
+    const capture = streamOf(apiContext);
+    expect(capture.status, capture.error ? `stream failed: ${capture.error}` : 'stream status').toBe(status);
+});
+Then('the stream content type should be {string}', async ({ apiContext, env }, expected) => {
+    // PROVES the endpoint actually streamed. An endpoint that quietly fell back to a buffered
+    // JSON response still returns 200, and every event assertion below would then fail
+    // confusingly.
+    expect(streamOf(apiContext).contentType, 'stream content type').toContain(render(expected, ...scopesOf(apiContext, env)));
+});
+Then('the stream should have at least {int} events', async ({ apiContext }, min) => {
+    if (min < 1)
+        throw new SdodsError('RUN_FAILED', 'Assert at least one event, not zero.', {
+            hint: '"at least 0 events" is satisfied by a stream that carried nothing; use `the stream should have terminated cleanly` if you mean the stream finished.',
+        });
+    expect(streamOf(apiContext).events.length, 'events parsed from the stream').toBeGreaterThanOrEqual(min);
+});
+Then('the first stream event type should be {string}', async ({ apiContext, env }, expected) => {
+    const { events } = streamOf(apiContext);
+    expect(events.length, 'the stream carried no events at all').toBeGreaterThan(0);
+    expect(events[0]?.type, 'first stream event type').toBe(render(expected, ...scopesOf(apiContext, env)));
+});
+Then('the last stream event type should be {string}', async ({ apiContext, env }, expected) => {
+    // PROVES the turn finished. A streaming endpoint returns 200 on its first byte, so the status
+    // says nothing about whether the model/producer ever reached its terminal event.
+    const { events } = streamOf(apiContext);
+    expect(events.length, 'the stream carried no events at all').toBeGreaterThan(0);
+    expect(events[events.length - 1]?.type, 'last stream event type — a 200 that never reaches this is a stream that died mid-flight').toBe(render(expected, ...scopesOf(apiContext, env)));
+});
+Then('the stream should have terminated cleanly', async ({ apiContext }) => {
+    // Three clauses, and all three are load-bearing: no transport error, at least one frame parsed
+    // (else a body of just "\n\n" would qualify), and a final frame boundary (a stream cut in the
+    // middle of a frame leaves no terminating blank line).
+    const capture = streamOf(apiContext);
+    expect(capture.error, 'the stream failed at the transport level').toBeUndefined();
+    expect(capture.events.length, 'the stream carried no events at all').toBeGreaterThan(0);
+    expect(capture.endedWithDelimiter, 'the body does not end on a frame boundary, so the stream was cut mid-event').toBe(true);
+});
+const REQUESTS = new WeakMap();
+/**
+ * Playwright `page.route` glob semantics, restricted to the three operators that matter:
+ * `**` matches anything including `/`, `*` matches anything except `/`, `?` matches one
+ * non-`/` character. Anchored, like Playwright's own matcher. Kept deliberately compatible so a
+ * counting step and a `I mock {string} …` step can be given the same string.
+ */
+export function globToRegExp(glob) {
+    let out = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                out += '.*';
+                i++;
+            }
+            else
+                out += '[^/]*';
+        }
+        else if (c === '?')
+            out += '[^/]';
+        else
+            out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${out}$`);
+}
+/**
+ * Refuses a pattern that cannot match a URL. A bare fragment such as "analytics" matches nothing
+ * under glob rules, so "no requests were made" would pass for ever — the exact vacuous green this
+ * whole section exists to prevent.
+ */
+function urlGlob(raw, scopes) {
+    const pattern = renderStrict(raw, 'the URL pattern', ...scopes);
+    if (!/[*?]/.test(pattern) && !/^(https?:\/\/|\/)/.test(pattern))
+        throw new SdodsError('RUN_FAILED', `"${pattern}" cannot match a request URL.`, {
+            hint: 'These steps use Playwright route globs, matched against the whole URL. Write "**analytics**" for a fragment, "**/api/users" for a path, or a full URL.',
+        });
+    return globToRegExp(pattern);
+}
+function logOf(page, why) {
+    const log = REQUESTS.get(page);
+    if (!log)
+        throw new SdodsError('RUN_FAILED', `${why} before any request recording was started.`, {
+            hint: 'Add `Given I record outgoing browser requests` (or `When I start counting requests to "<glob>"`) BEFORE the action under test — a listener installed afterwards cannot see requests that already went out.',
+        });
+    return log;
+}
+/**
+ * Listens on `page.on('request')`, not `page.route`. Route handlers run in reverse registration
+ * order, so a mock registered after a counting route would fulfil the request and the counter
+ * would never fire — the count would read 0 and "the client does not poll" would pass vacuously.
+ * The request event fires whether the request is routed, fulfilled, aborted or served from the
+ * network, which is what "did the client issue it" actually means.
+ */
+function ensureLog(page) {
+    const existing = REQUESTS.get(page);
+    if (existing)
+        return existing;
+    const log = { entries: [], counters: new Map() };
+    REQUESTS.set(page, log);
+    page.on('request', (req) => log.entries.push({ method: req.method(), url: req.url() }));
+    return log;
+}
+Given('I record outgoing browser requests', async ({ page }) => {
+    ensureLog(page);
+});
+When('I start counting requests to {string}', async ({ page, apiContext, env }, glob) => {
+    // The counter is an OFFSET into the log, so "start counting" means "ignore what came before".
+    // Start it before navigating if the initial page load's requests are part of the count.
+    urlGlob(glob, scopesOf(apiContext, env));
+    const log = ensureLog(page);
+    log.counters.set(render(glob, ...scopesOf(apiContext, env)), log.entries.length);
+});
+function counted(page, glob, scopes, why) {
+    const rendered = renderStrict(glob, 'the URL pattern', ...scopes);
+    const log = logOf(page, why);
+    const from = log.counters.get(rendered);
+    if (from === undefined)
+        throw new SdodsError('RUN_FAILED', `No counter was started for "${rendered}".`, {
+            hint: 'Add `When I start counting requests to "<the same glob>"` before the action. The glob strings must match exactly — the counter is keyed on the string you wrote.',
+        });
+    const re = urlGlob(glob, scopes);
+    return log.entries.slice(from).filter((e) => re.test(e.url)).length;
+}
+Then('{int} requests should have been counted for {string}', async ({ page, apiContext, env }, expected, glob) => {
+    // PROVES an exact call budget — one fetch per keystroke-debounce window, one per mount.
+    expect(counted(page, glob, scopesOf(apiContext, env), 'a request count was asserted'), `requests matching ${glob}`).toBe(expected);
+});
+Then('at most {int} requests should have been counted for {string}', async ({ page, apiContext, env }, max, glob) => {
+    // PROVES the client does not poll. Bounded rather than exact, because a legitimate retry
+    // should not turn this red — but zero would, and that is the point of the counter start.
+    expect(counted(page, glob, scopesOf(apiContext, env), 'a request count was asserted'), `requests matching ${glob}`).toBeLessThanOrEqual(max);
+});
+Then('at least {int} requests should have been counted for {string}', async ({ page, apiContext, env }, min, glob) => {
+    expect(counted(page, glob, scopesOf(apiContext, env), 'a request count was asserted'), `requests matching ${glob}`).toBeGreaterThanOrEqual(min);
+});
+Then('no requests should have been counted for {string}', async ({ page, apiContext, env }, glob) => {
+    // PROVES a client-side guard refused before sending. Mocking the route instead would make the
+    // scenario pass whether or not the call went out, which is the assertion inverted.
+    expect(counted(page, glob, scopesOf(apiContext, env), 'a request count was asserted'), `requests matching ${glob}`).toBe(0);
+});
+Then('no request matching {string} should have been made', async ({ page, apiContext, env }, glob) => {
+    // PROVES nothing leaked to a third party. Spans the whole recording, not a counter window, so
+    // it also covers requests issued during the initial page load.
+    const scopes = scopesOf(apiContext, env);
+    const re = urlGlob(glob, scopes);
+    const log = logOf(page, 'an outgoing-request assertion ran');
+    const hits = log.entries.filter((e) => re.test(e.url)).map((e) => `${e.method} ${e.url}`);
+    expect(hits, `unexpected request(s) matching ${glob}`).toEqual([]);
+});
+Then('a request matching {string} should have been made', async ({ page, apiContext, env }, glob) => {
+    const scopes = scopesOf(apiContext, env);
+    const re = urlGlob(glob, scopes);
+    const log = logOf(page, 'an outgoing-request assertion ran');
+    expect(log.entries.filter((e) => re.test(e.url)).length, `no request matched ${glob}; recorded: ${log.entries
+        .slice(-5)
+        .map((e) => e.url)
+        .join(', ') || '(none)'}`).toBeGreaterThan(0);
+});
+/* ── cheap negatives ──────────────────────────────────────────────────── */
+Then('the response should have no {string} header', async ({ apiContext, env }, name) => {
+    // Absence, which is NOT "does not contain": a header present with an empty or unexpected value
+    // satisfies a contains-check written as a negative, and this is the assertion behind
+    // "no cache header was set" and "the debug header never reaches production".
+    const wanted = renderStrict(name, 'the header name', ...scopesOf(apiContext, env));
+    expect(apiContext.last().response.headers[wanted.toLowerCase()], `unexpected ${wanted} header`).toBeUndefined();
+});
+Then('the response JSON path {string} should not exist', async ({ apiContext, env }, path) => {
+    // PROVES a field was withheld — the password hash, the internal id, the other tenant's row.
+    // Strict rendering matters most here: an unresolved path would be absent by construction.
+    const wanted = renderStrict(path, 'the JSON path', ...scopesOf(apiContext, env));
+    expect(getPath(apiContext.last().response.body, wanted), `JSON path ${wanted}`).toBeUndefined();
+});
+Then('the response should not contain any of {string}', async ({ apiContext, env }, list) => {
+    // Comma-separated; an empty list is refused, because "contains none of nothing" is the
+    // vacuous pass this step would otherwise be used to hide behind.
+    const wanted = renderList(list, 'the forbidden-strings list', ...scopesOf(apiContext, env));
+    const haystack = bodyText(apiContext.last().response.body);
+    if (haystack.trim().length === 0)
+        throw new SdodsError('RUN_FAILED', 'The response body is empty.', {
+            hint: 'Searching an empty body for forbidden strings can only ever pass; assert the status, or point this at the response that actually carries content.',
+        });
+    const found = wanted.filter((w) => haystack.includes(w));
+    expect(found, 'forbidden strings present in the response body').toEqual([]);
+});
+/**
+ * Shapes that are credentials wherever they appear. Deliberately narrow: each pattern is long
+ * and structured enough that a match is evidence, not a guess.
+ */
+const CREDENTIAL_PATTERNS = [
+    { name: 'JSON Web Token', re: /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/ },
+    { name: 'PEM private key', re: /-----BEGIN (?:[A-Z]+ )?PRIVATE KEY-----/ },
+    { name: 'AWS access key id', re: /\bAKIA[0-9A-Z]{16}\b/ },
+    { name: 'Google API key', re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+    { name: 'Slack token', re: /\bxox[abprs]-[0-9A-Za-z-]{10,}/ },
+    { name: 'GitHub token', re: /\bgh[pousr]_[0-9A-Za-z]{30,}/ },
+    { name: 'Stripe secret key', re: /\bsk_(?:live|test)_[0-9A-Za-z]{16,}/ },
+    {
+        name: 'secret-named field with a value',
+        re: /"(?:password|passwd|secret|api[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret|private[_-]?key|session[_-]?token)"\s*:\s*"(?!\*+"|\[REDACTED\]")[^"]{8,}"/i,
+    },
+];
+/** Every credential shape found in `text`, named. Exported so the patterns are testable. */
+export function credentialFindings(text) {
+    return CREDENTIAL_PATTERNS.filter((p) => p.re.test(text)).map((p) => p.name);
+}
+function assertNoCredentials(text, where) {
+    if (text.trim().length === 0)
+        throw new SdodsError('RUN_FAILED', `The ${where} is empty.`, {
+            hint: 'A credential scan over an empty body proves nothing about the endpoint, so this refuses rather than reporting green. Assert the status or the absence of a cookie instead.',
+        });
+    expect(credentialFindings(text), `credential-shaped values in the ${where}`).toEqual([]);
+}
+Then('nothing in the response body should look like a credential', async ({ apiContext }) => {
+    // PROVES an over-serialised model did not leak a token into a response nobody reads closely.
+    // Body only: the ApiSnapshot already redacts `authorization`/`set-cookie`, so scanning its
+    // headers would assert over asterisks.
+    assertNoCredentials(bodyText(apiContext.last().response.body), 'response body');
+});
+Then('nothing in the raw response body should look like a credential', async ({ apiContext }) => {
+    // The raw variant, for a response whose headers were deliberately kept unredacted. Still body
+    // only: a `Set-Cookie` on a successful sign-in IS a credential by design, and flagging it would
+    // make this fail on every correct login.
+    assertNoCredentials(rawOf(apiContext).body, 'raw response body');
+});
+//# sourceMappingURL=net.steps.js.map