cssprobe-cli 0.3.1 → 0.4.1

package/dist/daemon/flowRunner.js

@@ -15,6 +15,8 @@ const analyzer_1 = require("../engine/analyzer");
 const renderer_1 = require("../engine/renderer");
 const evalSerializer_1 = require("../engine/evalSerializer");
 const screenshot_1 = require("../utils/screenshot");
+const frames_1 = require("../browser/frames");
+const expect_1 = require("./expect");
 const FLOW_DEFAULT_TIMEOUT = 300_000;
 const CAPTURED_CONSOLE_METHODS = ['log', 'info', 'warn', 'error'];
 // tsc compiles `import()` to `require()` under module=commonjs, which cannot
@@ -64,20 +66,23 @@ function requirePage(launcher) {
     return page;
 }
 async function flowWaitFor(page, target, opts) {
+    const host = opts?.frame ? (0, frames_1.resolveFrame)(page, opts.frame) : page;
     if (typeof target === 'string') {
         const state = opts?.state ?? 'visible';
         const timeout = opts?.timeout ?? 30_000;
-        const elapsedMs = await (0, interactions_1.waitForCondition)(page, { kind: 'selector', selector: target, state }, timeout);
+        const elapsedMs = await (0, interactions_1.waitForCondition)(host, { kind: 'selector', selector: target, state }, timeout);
         return { waitedFor: 'selector', state, elapsedMs };
     }
     if ('js' in target) {
         const timeout = target.timeout ?? 30_000;
-        const elapsedMs = await (0, interactions_1.waitForCondition)(page, { kind: 'js', expression: target.js }, timeout);
+        const elapsedMs = await (0, interactions_1.waitForCondition)(host, { kind: 'js', expression: target.js }, timeout);
         return { waitedFor: 'js', elapsedMs };
     }
     if (target.networkIdle) {
+        if (opts?.frame)
+            throw new Error('networkIdle waits are page-level; remove opts.frame');
         const timeout = target.timeout ?? 30_000;
-        const elapsedMs = await (0, interactions_1.waitForCondition)(page, { kind: 'networkIdle' }, timeout);
+        const elapsedMs = await (0, interactions_1.waitForCondition)(host, { kind: 'networkIdle' }, timeout);
         return { waitedFor: 'networkidle', elapsedMs };
     }
     throw new Error('waitFor requires a selector string, { js }, or { networkIdle: true }');
@@ -102,6 +107,10 @@ function buildFlowApi(launcher, logs, baseDir) {
                 return (0, renderer_1.renderMarkdown)(snapshot, findings);
             return { snapshot, findings };
         },
+        context: page.context(),
+        frames: () => (0, frames_1.describeFrames)(page),
+        newPage: () => page.context().newPage(),
+        expect: (actual) => (0, expect_1.expect)(actual),
         screenshot: async (opts) => {
             const buffer = await page.screenshot({ fullPage: opts?.fullPage });
             const out = opts?.path ? path_1.default.resolve(baseDir, opts.path) : undefined;
@@ -122,6 +131,10 @@ function renderEnvelope(env) {
     else {
         lines.push(`Flow failed in ${env.elapsedMs}ms: ${env.error}`);
     }
+    if (env.pageErrors?.length) {
+        lines.push('', `Page errors (${env.pageErrors.length}):`);
+        lines.push(...env.pageErrors.map(error => `  - ${error.message}`));
+    }
     if (env.logs.length) {
         lines.push('', 'Logs:');
         lines.push(...env.logs.map(line => `  ${line}`));
@@ -132,6 +145,15 @@ async function runFlow(launcher, absPath, opts = {}) {
     const logs = [];
     const started = Date.now();
     const restore = captureConsole(logs);
+    const pageErrors = [];
+    const page = launcher.getPage();
+    const onPageError = (error) => {
+        pageErrors.push({
+            message: error.message,
+            stack: error.stack?.split('\n').slice(0, 6).join('\n'),
+        });
+    };
+    page?.on('pageerror', onPageError);
     let env;
     try {
         const fn = await loadFlowScript(absPath);
@@ -145,8 +167,11 @@ async function runFlow(launcher, absPath, opts = {}) {
         env = { ok: false, logs, error: e.message, elapsedMs: Date.now() - started };
     }
     finally {
+        page?.off('pageerror', onPageError);
         restore();
     }
+    if (pageErrors.length)
+        env.pageErrors = pageErrors;
     return {
         text: opts.json ? JSON.stringify(env, null, 2) : renderEnvelope(env),
         exitCode: env.ok ? 0 : 1,

package/dist/engine/evalSerializer.js

@@ -32,10 +32,10 @@ function serializeEvalResult(value) {
             return '[Depth limit]';
         seen.add(v);
         if (Array.isArray(v))
-            return v.map(item => walk(item, depth + 1));
+            return Array.from(v, item => (item === undefined ? null : walk(item, depth + 1)));
         const out = {};
         for (const [key, val] of Object.entries(v))
-            out[key] = walk(val, depth + 1);
+            out[key] = val === undefined ? null : walk(val, depth + 1);
         return out;
     };
     return walk(value, 0);

package/dist/help.json

@@ -1,13 +1,15 @@
 {
-  "global": "Usage: cssprobe-cli <command> [args] [options]\n\n\nSession Management:\n  open [url]                  open browser in session mode (non-blocking)\n  close                       close the browser session\n  status                      show current session status\n  resize <width> <height>     resize the browser viewport\n  eval <expression>           evaluate javascript expression on the page (browser context)\n  playwright <call>           execute playwright api call (node.js context)\n  click <selector>            click an element with real mouse events (works with custom react components)\n  hover <selector>            hover an element with real mouse events\n  type <selector> <text>      type text into an element (fill by default; --sequential for real key events)\n  wait-for [selector]         wait for a condition: selector state, js predicate, or network idle\n  run <file>                  run a multi-step flow script (default-exports an async function receiving the api object)\n  state-import [file]         import cookies from netscape format file\n  state-save                  save current browser session state (cookies + localstorage)\n  mcp                         start mcp server (stdio transport) for ai clients\n  mcp-install                 install mcp server config into ai client configs\n  mcp-uninstall               remove mcp server config from ai client configs\n\nCSS Inspection:\n  inspect <selector>          inspect the runtime css of a page element\n  tree <selector>             show dom tree structure\n  layout <selector>           show ascii layout diagram\n  findings <selector>         show only issues/warnings/errors\n  inject-css <css>            inject css into the current page\n\nExport:\n  screenshot                  take a screenshot of the current page\n\nConfiguration:\n  config-show                 show current configuration\n  config-set <key> <value>    set a configuration value\n  config-list                 list all profiles\n  config-use <name>           switch active profile\n  config-new <name>           create a new profile\n  config-path                 show configuration file path\n\nAgent Skills:\n  skill-install               install agent skill for cssprobe-cli\n  skill-uninstall             remove agent skill for cssprobe-cli\n\nGlobal options:\n  --help [command]            print help\n  --json                      output response as JSON\n  --raw                       output only the result value\n  --version                   print version\n  -p, --profile <name>        use named profile (or CSSPROBE_PROFILE env)",
+  "global": "Usage: cssprobe-cli <command> [args] [options]\n\n\nSession Management:\n  open [url]                  open browser in session mode (non-blocking)\n  close                       close the browser session\n  status                      show current session status\n  frames                      list frames in the current page\n  doctor                      diagnose browser installation and playwright revision mismatch\n  scenario <action> <file>    run a json scenario suite (regression cases, artifacts, junit)\n  resize <width> <height>     resize the browser viewport\n  eval <expression>           evaluate javascript expression on the page (browser context)\n  playwright <call>           execute playwright api call (node.js context)\n  click <selector>            click an element with real mouse events (works with custom react components)\n  hover <selector>            hover an element with real mouse events\n  type <selector> <text>      type text into an element (fill by default; --sequential for real key events)\n  wait-for [selector]         wait for a condition: selector state, js predicate, or network idle\n  sample <expression>         sample a js expression over time and return a timeline with summary stats\n  wait-stable <expression>    wait until a js expression stops changing (tolerance + stable window)\n  run <file>                  run a multi-step flow script (default-exports an async function receiving the api object)\n  state-import [file]         import cookies from netscape format file\n  state-save                  save current browser session state (cookies + localstorage)\n  state-check                 validate a saved state file: cookies, expiry, and target domain coverage\n  mcp                         start mcp server (stdio transport) for ai clients\n  mcp-install                 install mcp server config into ai client configs\n  mcp-uninstall               remove mcp server config from ai client configs\n\nCSS Inspection:\n  inspect <selector>          inspect the runtime css of a page element\n  tree <selector>             show dom tree structure\n  layout <selector>           show ascii layout diagram\n  findings <selector>         show only issues/warnings/errors\n  inject-css <css>            inject css into the current page\n\nExport:\n  screenshot                  take a screenshot of the current page\n\nConfiguration:\n  config-show                 show current configuration\n  config-set <key> <value>    set a configuration value\n  config-list                 list all profiles\n  config-use <name>           switch active profile\n  config-new <name>           create a new profile\n  config-path                 show configuration file path\n\nAgent Skills:\n  skill-install               install agent skill for cssprobe-cli\n  skill-uninstall             remove agent skill for cssprobe-cli\n\nGlobal options:\n  --help [command]            print help\n  --json                      output response as JSON\n  --raw                       output only the result value\n  --version                   print version\n  -p, --profile <name>        use named profile (or CSSPROBE_PROFILE env)",
   "commands": {
     "open": {
-      "help": "cssprobe-cli open [url]\n\nOpen browser in session mode (non-blocking)\n\nArguments:\n  [url]                       url, file:// path, or local html file path\nOptions:\n  --browser                   browser engine (default chromium)\n  --headed                    show the browser window\n  --viewport                  viewport size as wxh (e.g. 1280x720)\n  --state                     path to saved state file (cookies + localstorage)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli open [url]\n\nOpen browser in session mode (non-blocking)\n\nArguments:\n  [url]                       url, file:// path, or local html file path\nOptions:\n  --browser                   browser engine (default chromium)\n  --headed                    show the browser window\n  --viewport                  viewport size as wxh (e.g. 1280x720)\n  --state                     path to saved state file (cookies + localstorage)\n  --expect-url                regex the final page url must match\n  --fail-on-login             fail when the page redirects to a login url\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
         "browser": "string",
         "headed": "boolean",
         "viewport": "string",
-        "state": "string"
+        "state": "string",
+        "expect-url": "string",
+        "fail-on-login": "boolean"
       },
       "args": [
         "url"
@@ -25,44 +27,80 @@
       "flags": {},
       "args": []
     },
+    "frames": {
+      "help": "cssprobe-cli frames \n\nList frames in the current page\n\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {},
+      "args": []
+    },
+    "doctor": {
+      "help": "cssprobe-cli doctor \n\nDiagnose browser installation and Playwright revision mismatch\n\nOptions:\n  --engine                    browser engine: chromium, firefox, webkit (default: chromium)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "engine": "string"
+      },
+      "args": []
+    },
+    "scenario": {
+      "help": "cssprobe-cli scenario <action> <file>\n\nRun a JSON scenario suite (regression cases, artifacts, JUnit)\n\nArguments:\n  <action>                    only \"run\" is supported\n  <file>                      scenario suite json path\nOptions:\n  --state                     fallback state file when the suite/case does not set one\n  --artifacts                 artifact directory (default: ~/.cssprobe-cli/scenario-runs/<suite>-<timestamp>)\n  --junit                     write a junit xml report to this path\n  --bail                      stop after the first failing case\n  --headed                    show the browser window\n  --browser                   browser engine (default chromium)\n  --viewport                  viewport size as wxh (default: suite defaults or 1280x720)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "state": "string",
+        "artifacts": "string",
+        "junit": "string",
+        "bail": "boolean",
+        "headed": "boolean",
+        "browser": "string",
+        "viewport": "string"
+      },
+      "args": [
+        "action",
+        "file"
+      ]
+    },
     "inspect": {
-      "help": "cssprobe-cli inspect <selector>\n\nInspect the runtime CSS of a page element\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --json                      output structured json instead of markdown\n  --brief                     compact output: tree sketch + warnings/errors only\n  --layout                    ascii layout diagram showing element positions and sizes\n  --depth                     dom tree depth (default: auto, max 20)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli inspect <selector>\n\nInspect the runtime CSS of a page element\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --json                      output structured json instead of markdown\n  --brief                     compact output: tree sketch + warnings/errors only\n  --layout                    ascii layout diagram showing element positions and sizes\n  --depth                     dom tree depth (default: auto, max 20)\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
         "json": "boolean",
         "brief": "boolean",
         "layout": "boolean",
-        "depth": "string"
+        "depth": "string",
+        "frame": "string"
       },
       "args": [
         "selector"
       ]
     },
     "tree": {
-      "help": "cssprobe-cli tree <selector>\n\nShow DOM tree structure\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --depth                     tree depth (default: auto, max 20)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli tree <selector>\n\nShow DOM tree structure\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --depth                     tree depth (default: auto, max 20)\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
-        "depth": "string"
+        "depth": "string",
+        "frame": "string"
       },
       "args": [
         "selector"
       ]
     },
     "layout": {
-      "help": "cssprobe-cli layout <selector>\n\nShow ASCII layout diagram\n\nArguments:\n  <selector>                  css selector for the root element\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
-      "flags": {},
+      "help": "cssprobe-cli layout <selector>\n\nShow ASCII layout diagram\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "frame": "string"
+      },
       "args": [
         "selector"
       ]
     },
     "findings": {
-      "help": "cssprobe-cli findings <selector>\n\nShow only issues/warnings/errors\n\nArguments:\n  <selector>                  css selector for the root element\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
-      "flags": {},
+      "help": "cssprobe-cli findings <selector>\n\nShow only issues/warnings/errors\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "frame": "string"
+      },
       "args": [
         "selector"
       ]
     },
     "inject-css": {
-      "help": "cssprobe-cli inject-css <css>\n\nInject CSS into the current page\n\nArguments:\n  <css>                       css code to inject\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
-      "flags": {},
+      "help": "cssprobe-cli inject-css <css>\n\nInject CSS into the current page\n\nArguments:\n  <css>                       css code to inject\nOptions:\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "frame": "string"
+      },
       "args": [
         "css"
       ]
@@ -76,14 +114,16 @@
       ]
     },
     "eval": {
-      "help": "cssprobe-cli eval <expression>\n\nEvaluate JavaScript expression on the page (browser context)\n\nArguments:\n  <expression>                javascript expression to evaluate\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
-      "flags": {},
+      "help": "cssprobe-cli eval <expression>\n\nEvaluate JavaScript expression on the page (browser context)\n\nArguments:\n  <expression>                javascript expression, or @file / - (stdin) for long scripts\nOptions:\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "frame": "string"
+      },
       "args": [
         "expression"
       ]
     },
     "playwright": {
-      "help": "cssprobe-cli playwright <call>\n\nExecute Playwright API call (Node.js context)\n\nArguments:\n  <call>                      playwright api call, e.g. \"page.setviewportsize({width: 1280, height: 720})\"\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli playwright <call>\n\nExecute Playwright API call (Node.js context)\n\nArguments:\n  <call>                      playwright api call, or @file / - (stdin); e.g. \"page.setviewportsize({width: 1280, height: 720})\"\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {},
       "args": [
         "call"
@@ -135,17 +175,45 @@
       ]
     },
     "wait-for": {
-      "help": "cssprobe-cli wait-for [selector]\n\nWait for a condition: selector state, JS predicate, or network idle\n\nArguments:\n  [selector]                  css selector to wait for\nOptions:\n  --state                     selector state to wait for (default visible)\n  --js                        js predicate, e.g. \"() => document.queryselector('.x')?.offsetheight > 100\"\n  --network-idle              wait until the page is network-idle\n  --timeout                   timeout in ms (default 30000)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli wait-for [selector]\n\nWait for a condition: selector state, JS predicate, or network idle\n\nArguments:\n  [selector]                  css selector to wait for\nOptions:\n  --state                     selector state to wait for (default visible)\n  --js                        js predicate, e.g. \"() => document.queryselector('.x')?.offsetheight > 100\"\n  --network-idle              wait until the page is network-idle\n  --frame                     wait inside a frame: index, name, or url substring\n  --timeout                   timeout in ms (default 30000)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
         "state": "string",
         "js": "string",
         "network-idle": "boolean",
+        "frame": "string",
         "timeout": "string"
       },
       "args": [
         "selector"
       ]
     },
+    "sample": {
+      "help": "cssprobe-cli sample <expression>\n\nSample a JS expression over time and return a timeline with summary stats\n\nArguments:\n  <expression>                js expression sampled on an interval\nOptions:\n  --interval                  sampling interval in ms (default 250)\n  --duration                  total sampling duration in ms (default 5000)\n  --key                       dot path for numeric extraction, e.g. \"top\" or \"box.y\"\n  --tail-from                 tail starts at this elapsed ms (default: last 5000ms)\n  --ignore-errors             record evaluation errors as sample points instead of aborting\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "interval": "string",
+        "duration": "string",
+        "key": "string",
+        "tail-from": "string",
+        "ignore-errors": "boolean",
+        "frame": "string"
+      },
+      "args": [
+        "expression"
+      ]
+    },
+    "wait-stable": {
+      "help": "cssprobe-cli wait-stable <expression>\n\nWait until a JS expression stops changing (tolerance + stable window)\n\nArguments:\n  <expression>                js expression polled until stable\nOptions:\n  --tolerance                 absolute tolerance for numeric values (default 0)\n  --window                    stable window in ms (default 1500)\n  --timeout                   timeout in ms (default 30000)\n  --interval                  polling interval in ms (default 200)\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "tolerance": "string",
+        "window": "string",
+        "timeout": "string",
+        "interval": "string",
+        "frame": "string"
+      },
+      "args": [
+        "expression"
+      ]
+    },
     "run": {
       "help": "cssprobe-cli run <file>\n\nRun a multi-step flow script (default-exports an async function receiving the API object)\n\nArguments:\n  <file>                      flow script path (.js / .mjs / .cjs)\nOptions:\n  --timeout                   whole-script timeout in ms (default 300000, 0 = unlimited)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
@@ -173,6 +241,14 @@
       },
       "args": []
     },
+    "state-check": {
+      "help": "cssprobe-cli state-check \n\nValidate a saved state file: cookies, expiry, and target domain coverage\n\nOptions:\n  --state                     state file path (default: ~/.cssprobe-cli/states/session.json)\n  --url                       target url whose hostname must be covered by the cookies\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "state": "string",
+        "url": "string"
+      },
+      "args": []
+    },
     "config-show": {
       "help": "cssprobe-cli config-show \n\nShow current configuration\n\nOptions:\n  --profile                   profile name",
       "flags": {
@@ -256,7 +332,9 @@
   },
   "booleanOptions": [
     "headed",
+    "fail-on-login",
     "all",
+    "bail",
     "json",
     "brief",
     "layout",
@@ -265,6 +343,7 @@
     "sequential",
     "clear",
     "network-idle",
+    "ignore-errors",
     "local"
   ]
 }

package/dist/scenario/assertions.d.ts

@@ -0,0 +1,13 @@
+import type { AssertStep } from './schema';
+export interface AssertionState {
+    url: string;
+    title: string;
+    frames: number;
+}
+export interface AssertionContext {
+    vars: Record<string, unknown>;
+    state: AssertionState;
+    globals: Record<string, string>;
+}
+export declare function resolvePath(value: unknown, path?: string): unknown;
+export declare function evaluateAssertion(assertion: AssertStep, context: AssertionContext): string | null;

package/dist/scenario/assertions.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePath = resolvePath;
+exports.evaluateAssertion = evaluateAssertion;
+function resolvePath(value, path) {
+    if (!path)
+        return value;
+    let current = value;
+    for (const part of path.split('.')) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, index) => deepEqual(item, b[index]));
+    }
+    if (typeof a === 'object' && typeof b === 'object') {
+        const aKeys = Object.keys(a).sort();
+        const bKeys = Object.keys(b).sort();
+        if (aKeys.length !== bKeys.length || aKeys.some((key, index) => key !== bKeys[index]))
+            return false;
+        return aKeys.every(key => deepEqual(a[key], b[key]));
+    }
+    return false;
+}
+function label(assertion) {
+    return assertion.label ?? 'assert';
+}
+function evaluateAssertion(assertion, context) {
+    const errors = [];
+    if (assertion.url) {
+        let regex;
+        try {
+            regex = new RegExp(assertion.url);
+        }
+        catch {
+            return `${label(assertion)}: invalid url pattern ${assertion.url}`;
+        }
+        if (!regex.test(context.state.url)) {
+            errors.push(`url ${JSON.stringify(context.state.url)} does not match ${assertion.url}`);
+        }
+    }
+    for (const [name, expected] of Object.entries(assertion.globals ?? {})) {
+        const actual = context.globals[name] ?? 'undefined';
+        if (actual !== expected) {
+            errors.push(`global ${name}: expected ${expected}, received ${actual}`);
+        }
+    }
+    for (const name of assertion.absent ?? []) {
+        const actual = context.globals[name] ?? 'undefined';
+        if (actual !== 'undefined') {
+            errors.push(`global ${name}: expected absent, received ${actual}`);
+        }
+    }
+    const hasValueCheck = ['eq', 'ne', 'match', 'within', 'min', 'max'].some(key => key in assertion);
+    if (!hasValueCheck) {
+        return errors.length ? `${label(assertion)}: ${errors.join('; ')}` : null;
+    }
+    let value;
+    if (assertion.on) {
+        if (assertion.on === 'state') {
+            value = context.state;
+        }
+        else if (assertion.on in context.vars) {
+            value = context.vars[assertion.on];
+        }
+        else {
+            return `${label(assertion)}: unknown variable "${assertion.on}"`;
+        }
+    }
+    else {
+        value = context.state;
+    }
+    value = resolvePath(value, assertion.path);
+    if ('eq' in assertion && !deepEqual(value, assertion.eq)) {
+        errors.push(`expected ${JSON.stringify(assertion.eq)}, received ${JSON.stringify(value)}`);
+    }
+    if ('ne' in assertion && deepEqual(value, assertion.ne)) {
+        errors.push(`expected value different from ${JSON.stringify(assertion.ne)}`);
+    }
+    if (assertion.match !== undefined) {
+        const actual = typeof value === 'string' ? value : JSON.stringify(value);
+        if (!new RegExp(assertion.match).test(actual)) {
+            errors.push(`expected ${JSON.stringify(actual)} to match ${assertion.match}`);
+        }
+    }
+    if (assertion.within) {
+        if (typeof value !== 'number' || Math.abs(value - assertion.within.expected) > assertion.within.tolerance) {
+            errors.push(`expected ${assertion.within.expected} ±${assertion.within.tolerance}, received ${JSON.stringify(value)}`);
+        }
+    }
+    if (assertion.min !== undefined && (typeof value !== 'number' || value < assertion.min)) {
+        errors.push(`expected >= ${assertion.min}, received ${JSON.stringify(value)}`);
+    }
+    if (assertion.max !== undefined && (typeof value !== 'number' || value > assertion.max)) {
+        errors.push(`expected <= ${assertion.max}, received ${JSON.stringify(value)}`);
+    }
+    return errors.length ? `${label(assertion)}: ${errors.join('; ')}` : null;
+}
+//# sourceMappingURL=assertions.js.map

package/dist/scenario/reporters.d.ts

@@ -0,0 +1,13 @@
+import type { CaseResult } from './schema';
+export declare function slugify(value: string): string;
+export interface ScenarioSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    durationMs: number;
+    ok: boolean;
+}
+export declare function summarize(results: CaseResult[]): ScenarioSummary;
+export declare function formatConsole(suiteName: string, results: CaseResult[]): string;
+export declare function escapeXml(value: string): string;
+export declare function toJunit(suiteName: string, results: CaseResult[]): string;

package/dist/scenario/reporters.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.slugify = slugify;
+exports.summarize = summarize;
+exports.formatConsole = formatConsole;
+exports.escapeXml = escapeXml;
+exports.toJunit = toJunit;
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60) || 'case';
+}
+function summarize(results) {
+    const passed = results.filter(result => result.ok).length;
+    const durationMs = results.reduce((total, result) => total + result.durationMs, 0);
+    return {
+        total: results.length,
+        passed,
+        failed: results.length - passed,
+        durationMs,
+        ok: passed === results.length,
+    };
+}
+function formatConsole(suiteName, results) {
+    const summary = summarize(results);
+    const lines = [];
+    for (const result of results) {
+        const marker = result.ok ? 'PASS' : result.skipped ? 'SKIP' : 'FAIL';
+        lines.push(`${marker} ${result.name} (${result.durationMs}ms)`);
+        if (result.error)
+            lines.push(`  ${result.error}`);
+        for (const step of result.steps) {
+            if (!step.ok)
+                lines.push(`  step ${step.index + 1} (${step.action}): ${step.error}`);
+        }
+        if (result.artifactsDir)
+            lines.push(`  artifacts: ${result.artifactsDir}`);
+    }
+    lines.push('');
+    lines.push(`${suiteName}: ${summary.passed}/${summary.total} passed, ${summary.failed} failed in ${summary.durationMs}ms`);
+    return lines.join('\n');
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function toJunit(suiteName, results) {
+    const summary = summarize(results);
+    const cases = results
+        .map(result => {
+        const time = (result.durationMs / 1000).toFixed(3);
+        const failureDetails = [
+            result.error,
+            ...result.steps.filter(step => !step.ok).map(step => `step ${step.index + 1} (${step.action}): ${step.error}`),
+        ]
+            .filter(Boolean)
+            .join('\n');
+        const body = result.ok
+            ? ''
+            : `<failure message="${escapeXml(result.error ?? 'scenario case failed')}">${escapeXml(failureDetails)}</failure>`;
+        return `    <testcase classname="${escapeXml(suiteName)}" name="${escapeXml(result.name)}" time="${time}">${body}</testcase>`;
+    })
+        .join('\n');
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<testsuites tests="${summary.total}" failures="${summary.failed}" time="${(summary.durationMs / 1000).toFixed(3)}">`,
+        `  <testsuite name="${escapeXml(suiteName)}" tests="${summary.total}" failures="${summary.failed}" time="${(summary.durationMs / 1000).toFixed(3)}">`,
+        cases,
+        '  </testsuite>',
+        '</testsuites>',
+    ].join('\n');
+}
+//# sourceMappingURL=reporters.js.map

package/dist/scenario/runner.d.ts

@@ -0,0 +1,10 @@
+import { type ScenarioSummary } from './reporters';
+import type { CaseResult, ScenarioRunOptions, Suite } from './schema';
+export interface ScenarioRunResult {
+    suite: string;
+    ok: boolean;
+    summary: ScenarioSummary;
+    results: CaseResult[];
+    artifactsDir: string;
+}
+export declare function runScenario(suite: Suite, suitePath: string, options?: ScenarioRunOptions): Promise<ScenarioRunResult>;