@sdods/core 0.7.2 → 0.9.0

package/dist/steps/perf.steps.d.ts

@@ -1,136 +1,11 @@
 import './params.js';
 import type { Page, TestInfo } from '@playwright/test';
-import type { EnvConfig, PerformanceMetrics } from '@sdods/contracts';
+import type { EnvConfig } from '@sdods/contracts';
 import type { ApiClient, HttpMethod } from '../api/client.js';
 import type { ApiContext } from '../fixtures/api-context.js';
 import type { ScenarioMeta } from '../fixtures/scenario.js';
-/**
- * Performance budgets.
- *
- * `PerfBudgetsSchema` (pageLoadMs / lcpMs / fcpMs / ttfbMs / apiP95Ms), the `perf.budgets` block in
- * the project and env yaml, the `perfBudgets: true` release gate and `attachmentNames.perf` all
- * existed before this file; nothing read any of them. These steps close that loop.
- *
- * Two rules run through every step here, both learned from hand-written project steps that got
- * them wrong:
- *
- *  1. A BUDGET IS READ FROM CONFIG, NEVER FROM THE FEATURE FILE. A number typed into a `.feature`
- *     is a number that drifts from the environment it runs on — staging and a laptop do not share
- *     a page-load budget. `Then the response time should be under {int} ms` (api.steps.ts) is the
- *     literal-threshold form and stays exactly as it is; the budget-driven forms below are new
- *     patterns, not a widening of it. A local literal is still reachable where a scenario genuinely
- *     needs one — `should be under {int} ms` — so the escape hatch is visible in the step text.
- *  2. AN UNMEASURED VITAL FAILS. LCP does not fire on a page with no contentful paint, and WebKit
- *     does not implement it at all; paint timings and the navigation entry can be missing too.
- *     Recording those as `0` makes every budget assertion pass — a whole perf module
- *     goes green while measuring nothing. So a vital that did not fire is recorded as `null`
- *     together with the reason, and asserting on it FAILS naming that reason. A real navigation
- *     cannot produce a genuine 0 ms vital (they are all offsets from navigation start), so treating
- *     "absent or 0" as "not measured" loses no honest signal.
- *
- * A budget that is not configured is likewise a hard `CONFIG_INVALID` naming the missing key, not
- * a skip: silently skipping is the same vacuous green in a different costume.
- *
- * The two comparison operators are deliberately different and deliberately visible in the step
- * text: `under {int} ms` is strict `<` (matching `the response time should be under {int} ms` in
- * api.steps.ts), `within its configured budget` is `<=` — a budget is a ceiling you may sit on.
- */
-/** The page vitals SDODS records. Each name is also its key in `perf.budgets`. */
-export declare const VITAL_KEYS: readonly ["pageLoadMs", "lcpMs", "fcpMs", "ttfbMs"];
-export type VitalKey = (typeof VITAL_KEYS)[number];
-/** The `perf.budgets` key a sampled API latency distribution is judged against. */
-export declare const API_P95_BUDGET_KEY = "apiP95Ms";
-type BudgetLayer = {
-    budgets?: Record<string, number | undefined>;
-} | undefined;
-/** The slice of a resolved config these steps read. Nothing here writes config. */
-export interface BudgetConfig {
-    project: {
-        perf?: BudgetLayer;
-    };
-    env: {
-        name?: string;
-        perf?: BudgetLayer;
-    };
-}
-/**
- * Effective budgets, env overriding project per key.
- *
- * `resolveConfig` already deep-merges `env.perf` into `config.project.perf`, so on a resolved
- * config the project side is the whole answer. Merging the env side again is idempotent and keeps
- * this correct for a config assembled by hand. Non-numeric values are dropped rather than spread —
- * an explicit `undefined` in the env layer would otherwise erase a real project budget and turn a
- * configured assertion into an unconfigured one.
- */
-export declare function resolvedBudgets(config: BudgetConfig): Record<string, number>;
-/**
- * The configured budget for one key, or a hard error naming it.
- *
- * PROVES the assertion that follows is gated on something real. A missing budget must never
- * degrade to a skip or to `Infinity`: an unconfigured budget is the single failure mode that lets
- * an entire perf suite report success while asserting nothing at all.
- */
-export declare function requireBudget(config: BudgetConfig, key: string): number;
-/** One `When I record the page vitals`. `null` in `vitals` means NOT MEASURED, never "0 ms". */
-export interface VitalsRecording {
-    url: string;
-    vitals: Record<VitalKey, number | null>;
-    /** Why a vital is null, keyed by vital. Surfaced verbatim in the failure message. */
-    unmeasured: Partial<Record<VitalKey, string>>;
-    /** The contract shape written to `sdods/perf/<step>` and ingested into `steps.perf_json`. */
-    metrics: PerformanceMetrics;
-}
-export interface LatencySample {
-    status: number;
-    ms: number;
-}
-export interface LatencySampleSet {
-    method: string;
-    path: string;
-    samples: LatencySample[];
-    p95Ms: number;
-}
-interface PerfStore {
-    recordings: VitalsRecording[];
-    sampleSets: LatencySampleSet[];
-}
-export declare function perfStore(key: object): PerfStore;
-/**
- * Nearest-rank p95 — deterministic for a given set of samples, with no interpolation to argue
- * about. Below 20 samples the nearest rank IS the maximum; the sample count travels in the
- * attachment and in every failure message so a reader can see when "p95" means "slowest of five".
- *
- * Throws rather than returning 0 on an empty sample: a p95 of 0 slides under every budget.
- */
-export declare function p95Of(msValues: readonly number[]): number;
-/** What the page hands back. Every timing is `number | null`; null always means "did not fire". */
-export interface RawVitals {
-    hasNavigationEntry: boolean;
-    navigationStartEpochMs: number | null;
-    pageLoadMs: number | null;
-    ttfbMs: number | null;
-    fcpMs: number | null;
-    lcpMs: number | null;
-    domContentLoadedMs: number | null;
-    totalResources: number;
-    totalResourceSizeKB: number;
-    lcpSupported: boolean;
-    fcpSupported: boolean;
-}
-/**
- * Runs inside the page. Serialised by Playwright, so it closes over nothing but its argument — the
- * type aliases above are erased at compile time and are safe to reference; the constants are not,
- * which is why the settle window is passed in.
- */
-export declare function collectRawVitals(settleMs: number): Promise<RawVitals>;
-/**
- * Turns the page's answer into a recording, capturing WHY a vital is null while the browser's
- * capabilities are still in hand. By the time a `Then` step fails, "lcpMs was not measured" on its
- * own sends the reader hunting for a bug in a page that is merely running in a browser that does
- * not implement LCP (WebKit). Support is read from `PerformanceObserver.supportedEntryTypes`, never
- * assumed from the browser name.
- */
-export declare function toRecording(raw: RawVitals, url: string, browserName?: string): VitalsRecording;
+import { type BudgetConfig } from '../perf/vitals.js';
+export { API_P95_BUDGET_KEY, VITAL_KEYS, collectRawVitals, p95Of, perfStore, requireBudget, resolvedBudgets, toRecording, type BudgetConfig, type LatencySample, type LatencySampleSet, type RawVitals, type VitalKey, type VitalsRecording, } from '../perf/vitals.js';
 interface VitalsFixtures {
     page: Page;
     config: BudgetConfig;
@@ -244,5 +119,4 @@ export declare const assertP95NoWorseThanPrevious: ({ scenario }: {
 export declare const assertEverySampleStatus: ({ scenario }: {
     scenario: ScenarioMeta;
 }, status: number) => Promise<void>;
-export {};
 //# sourceMappingURL=perf.steps.d.ts.map

package/dist/steps/perf.steps.js

@@ -5,6 +5,10 @@ import { Then, When } from '../fixtures/test.js';
 import { attachmentNames, pad2, scenarioFiles } from '@sdods/contracts';
 import { renderJson, renderStrict } from '../api/template.js';
 import { SdodsError } from '../errors.js';
+import { API_P95_BUDGET_KEY, LCP_SETTLE_MS, LOAD_WAIT_MS, collectRawVitals, lastRecording, lastSampleSet, p95Of, perfStore, requireBudget, requireVitalKey, resolvedBudgets, toRecording, } from '../perf/vitals.js';
+// The measurement and budget plumbing lives in `../perf/vitals.ts` so the `@perf` tag hook can
+// share it without importing (and so re-registering) this step file. Re-exported for importers.
+export { API_P95_BUDGET_KEY, VITAL_KEYS, collectRawVitals, p95Of, perfStore, requireBudget, resolvedBudgets, toRecording, } from '../perf/vitals.js';
 /**
  * Performance budgets.
  *
@@ -36,233 +40,6 @@ import { SdodsError } from '../errors.js';
  * text: `under {int} ms` is strict `<` (matching `the response time should be under {int} ms` in
  * api.steps.ts), `within its configured budget` is `<=` — a budget is a ceiling you may sit on.
  */
-/* ── budgets ──────────────────────────────────────────────────────────── */
-/** The page vitals SDODS records. Each name is also its key in `perf.budgets`. */
-export const VITAL_KEYS = ['pageLoadMs', 'lcpMs', 'fcpMs', 'ttfbMs'];
-/** The `perf.budgets` key a sampled API latency distribution is judged against. */
-export const API_P95_BUDGET_KEY = 'apiP95Ms';
-/**
- * Effective budgets, env overriding project per key.
- *
- * `resolveConfig` already deep-merges `env.perf` into `config.project.perf`, so on a resolved
- * config the project side is the whole answer. Merging the env side again is idempotent and keeps
- * this correct for a config assembled by hand. Non-numeric values are dropped rather than spread —
- * an explicit `undefined` in the env layer would otherwise erase a real project budget and turn a
- * configured assertion into an unconfigured one.
- */
-export function resolvedBudgets(config) {
-    const out = {};
-    for (const layer of [config.project.perf?.budgets, config.env.perf?.budgets]) {
-        for (const [key, value] of Object.entries(layer ?? {})) {
-            if (typeof value === 'number' && Number.isFinite(value))
-                out[key] = value;
-        }
-    }
-    return out;
-}
-/**
- * The configured budget for one key, or a hard error naming it.
- *
- * PROVES the assertion that follows is gated on something real. A missing budget must never
- * degrade to a skip or to `Infinity`: an unconfigured budget is the single failure mode that lets
- * an entire perf suite report success while asserting nothing at all.
- */
-export function requireBudget(config, key) {
-    const budget = resolvedBudgets(config)[key];
-    const envName = config.env.name ?? 'unknown';
-    if (typeof budget !== 'number' || !(budget > 0)) {
-        throw new SdodsError('CONFIG_INVALID', `Perf budget "${key}" is not configured for environment "${envName}".`, {
-            hint: `Set perf.budgets.${key} in the project's sdods.project.yaml, or override it in envs/${envName}.yaml. Without it this assertion would pass no matter how slow the application is.`,
-        });
-    }
-    return budget;
-}
-function requireVitalKey(name) {
-    if (VITAL_KEYS.includes(name))
-        return name;
-    throw new SdodsError('CONFIG_INVALID', `"${name}" is not a page vital SDODS records.`, {
-        hint: `Known vitals: ${VITAL_KEYS.join(', ')}. Each is also its key in perf.budgets.`,
-    });
-}
-/**
- * Measurements have to survive from a `When` step to a `Then` step. They do not go in
- * `apiContext.vars`: that store doubles as a `{{…}}` template scope, so an array of samples parked
- * there would leak into every later rendering. Keyed on the per-test `scenario` object, so two
- * scenarios in parallel workers can never read each other's numbers and nothing outlives the
- * scenario that measured it.
- */
-const stores = new WeakMap();
-export function perfStore(key) {
-    let store = stores.get(key);
-    if (!store) {
-        store = { recordings: [], sampleSets: [] };
-        stores.set(key, store);
-    }
-    return store;
-}
-function lastRecording(key) {
-    const recording = perfStore(key).recordings.at(-1);
-    if (!recording) {
-        throw new SdodsError('RUN_FAILED', 'No page vitals have been recorded in this scenario.', {
-            hint: 'Add `When I record the page vitals` after the navigation you want to measure.',
-        });
-    }
-    return recording;
-}
-function lastSampleSet(key) {
-    const set = perfStore(key).sampleSets.at(-1);
-    if (!set) {
-        throw new SdodsError('RUN_FAILED', 'No latency samples have been taken in this scenario.', {
-            hint: 'Add `When I sample the latency of GET "/path" over 20 requests` before asserting a p95.',
-        });
-    }
-    return set;
-}
-/* ── statistics ───────────────────────────────────────────────────────── */
-/**
- * Nearest-rank p95 — deterministic for a given set of samples, with no interpolation to argue
- * about. Below 20 samples the nearest rank IS the maximum; the sample count travels in the
- * attachment and in every failure message so a reader can see when "p95" means "slowest of five".
- *
- * Throws rather than returning 0 on an empty sample: a p95 of 0 slides under every budget.
- */
-export function p95Of(msValues) {
-    if (msValues.length === 0) {
-        throw new SdodsError('RUN_FAILED', 'Cannot compute a p95 over an empty sample.', {
-            hint: 'Sample at least one request before asserting a p95.',
-        });
-    }
-    const sorted = [...msValues].sort((a, b) => a - b);
-    const index = Math.max(0, Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1));
-    return sorted[index];
-}
-/* ── browser-side collection ──────────────────────────────────────────── */
-/**
- * How long the LCP observer is given to settle. LCP arrives as a stream of ever-larger candidates;
- * `buffered: true` replays the ones already emitted and this window catches any still in flight.
- * A fixed constant rather than a computed wait, so two runs of one scenario observe the same
- * window and a baseline stays comparable.
- */
-const LCP_SETTLE_MS = 500;
-/** Bounded wait for the load event before reading `loadEventEnd`. */
-const LOAD_WAIT_MS = 5_000;
-/**
- * Runs inside the page. Serialised by Playwright, so it closes over nothing but its argument — the
- * type aliases above are erased at compile time and are safe to reference; the constants are not,
- * which is why the settle window is passed in.
- */
-export async function collectRawVitals(settleMs) {
-    const perf = performance;
-    const Observer = globalThis
-        .PerformanceObserver;
-    // Every vital is an offset from navigation start, so a genuine measurement is always > 0.
-    const positive = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.round(value) : null;
-    const supported = Observer?.supportedEntryTypes ?? [];
-    const lcpSupported = supported.includes('largest-contentful-paint');
-    const fcpSupported = supported.includes('paint');
-    // TRAP: paint timings can land AFTER the load event. Reading the paint entry eagerly while only
-    // LCP waited for the settle window reported `fcpMs: null` beside a real `lcpMs` on a page that
-    // had painted perfectly well — impossible, since first paint always precedes the largest one —
-    // and a budget assertion would then have failed it as "not measured". So nothing is read until
-    // the window closes, and the window is opened whether or not LCP is supported.
-    let largestPaint = 0;
-    await new Promise((resolve) => {
-        let observer;
-        try {
-            if (Observer && lcpSupported) {
-                observer = new Observer((list) => {
-                    for (const entry of list.getEntries()) {
-                        const start = entry.startTime;
-                        if (typeof start === 'number' && start > largestPaint)
-                            largestPaint = start;
-                    }
-                });
-                observer.observe({ type: 'largest-contentful-paint', buffered: true });
-            }
-        }
-        catch {
-            observer = undefined;
-        }
-        setTimeout(() => {
-            try {
-                observer?.disconnect();
-            }
-            catch {
-                /* already gone */
-            }
-            resolve();
-        }, settleMs);
-    });
-    const nav = perf.getEntriesByType('navigation')[0];
-    const fcpEntry = perf.getEntriesByName('first-contentful-paint')[0];
-    const lcpMs = largestPaint > 0 ? Math.round(largestPaint) : null;
-    let totalResources = 0;
-    let totalBytes = 0;
-    for (const entry of perf.getEntriesByType('resource')) {
-        totalResources++;
-        const size = entry.transferSize;
-        if (typeof size === 'number' && Number.isFinite(size))
-            totalBytes += size;
-    }
-    const startTime = nav && typeof nav.startTime === 'number' ? nav.startTime : 0;
-    return {
-        hasNavigationEntry: Boolean(nav),
-        navigationStartEpochMs: nav && typeof perf.timeOrigin === 'number' ? Math.round(perf.timeOrigin + startTime) : null,
-        pageLoadMs: nav ? positive(nav.loadEventEnd) : null,
-        ttfbMs: nav ? positive(nav.responseStart) : null,
-        fcpMs: fcpEntry ? positive(fcpEntry.startTime) : null,
-        lcpMs,
-        domContentLoadedMs: nav ? positive(nav.domContentLoadedEventEnd) : null,
-        totalResources,
-        totalResourceSizeKB: Math.round(totalBytes / 1024),
-        lcpSupported,
-        fcpSupported,
-    };
-}
-/**
- * Turns the page's answer into a recording, capturing WHY a vital is null while the browser's
- * capabilities are still in hand. By the time a `Then` step fails, "lcpMs was not measured" on its
- * own sends the reader hunting for a bug in a page that is merely running in a browser that does
- * not implement LCP (WebKit). Support is read from `PerformanceObserver.supportedEntryTypes`, never
- * assumed from the browser name.
- */
-export function toRecording(raw, url, browserName) {
-    const vitals = {
-        pageLoadMs: raw.pageLoadMs,
-        lcpMs: raw.lcpMs,
-        fcpMs: raw.fcpMs,
-        ttfbMs: raw.ttfbMs,
-    };
-    const where = browserName ? ` in ${browserName}` : ' in this browser';
-    const unmeasured = {};
-    if (raw.pageLoadMs === null)
-        unmeasured.pageLoadMs = `the load event had not fired ${LOAD_WAIT_MS} ms after the vitals step began`;
-    if (raw.ttfbMs === null)
-        unmeasured.ttfbMs = 'the navigation entry reported no response start';
-    if (raw.fcpMs === null)
-        unmeasured.fcpMs = raw.fcpSupported
-            ? 'the page painted no contentful frame'
-            : `paint timings are not implemented${where}`;
-    if (raw.lcpMs === null)
-        unmeasured.lcpMs = raw.lcpSupported
-            ? 'the page produced no largest-contentful-paint candidate'
-            : `largest-contentful-paint is not implemented${where} — restrict the scenario to a browser that supports it`;
-    // The contract's three non-nullable fields carry 0 for an unmeasured value; the nullable
-    // `budgets.measured` block written alongside is what the assertions read, so a 0 here can never
-    // be mistaken for a measurement.
-    const metrics = {
-        url,
-        timestamp: new Date(raw.navigationStartEpochMs ?? Date.now()).toISOString(),
-        domContentLoaded: raw.domContentLoadedMs ?? 0,
-        pageLoadTime: raw.pageLoadMs ?? 0,
-        timeToFirstByte: raw.ttfbMs ?? 0,
-        totalResources: raw.totalResources,
-        totalResourceSizeKB: raw.totalResourceSizeKB,
-        firstContentfulPaint: raw.fcpMs,
-        largestContentfulPaint: raw.lcpMs,
-    };
-    return { url, vitals, unmeasured, metrics };
-}
 /** The measured value, or a failure naming why it is absent. Never returns 0-for-absent. */
 function measured(recording, metric) {
     const value = recording.vitals[metric];

package/dist/steps/ui.steps.js

@@ -4,6 +4,7 @@ import { Given, Then, When } from '../fixtures/test.js';
 import { render, renderJson, renderStrict } from '../api/template.js';
 import { withActionRole } from '../heal/strategies.js';
 import { SdodsError } from '../errors.js';
+import { parseMaskArgument } from '../shots/baselines.js';
 const scopesOf = (apiContext, env) => [
     apiContext.vars.toObject(),
     env.vars,
@@ -152,6 +153,10 @@ Then('the page title should contain {string}', async ({ page, apiContext, env },
 Then('the page should match the visual baseline {string}', async ({ shots, $bddContext, apiContext, env }, name) => {
     await shots.visual(arg({ apiContext, env }, name), $bddContext.stepIndex);
 });
+/** Masks comma-separated selectors on top of `screenshots.mask` and the baseline's own mask. */
+Then('the page should match the visual baseline {string} masking {string}', async ({ shots, $bddContext, apiContext, env }, name, selectors) => {
+    await shots.visual(arg({ apiContext, env }, name), $bddContext.stepIndex, parseMaskArgument(arg({ apiContext, env }, selectors)));
+});
 /* ── network mocking ──────────────────────────────────────────────────── */
 When('I mock {string} with JSON:', async ({ page, apiContext, env }, urlGlob, json) => {
     const body = renderJson(json, ...scopesOf(apiContext, env));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdods/core",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "SDODS runtime: configuration, project registry, fixtures, step libraries, data providers, screenshot narratives and self-healing locators.",
   "license": "Apache-2.0",
   "author": "SDODS <admin@sdods.com>",
@@ -21,6 +21,7 @@
     "./analyze": "./dist/analyze/index.js",
     "./recorder": "./dist/recorder/index.js",
     "./har": "./dist/har/index.js",
+    "./load": "./dist/load/index.js",
     "./auth": "./dist/auth/index.js",
     "./insights": "./dist/insights/index.js",
     "./reporters/dashboard": "./dist/reporters/dashboard.js",
@@ -42,7 +43,7 @@
     "playwright-bdd": ">=9"
   },
   "dependencies": {
-    "@sdods/contracts": "0.7.2",
+    "@sdods/contracts": "0.9.0",
     "@cucumber/cucumber-expressions": "19.0.0",
     "@cucumber/gherkin": "^42.0.1",
     "@cucumber/messages": "^34.2.1",
@@ -60,7 +61,7 @@
     "tsx": "^4.23.0",
     "yaml": "^2.9.0",
     "zod": "^4.5.4",
-    "@sdods/db": "0.7.2"
+    "@sdods/db": "0.9.0"
   },
   "homepage": "https://sdods.com",
   "bugs": {