@vmz/test 0.0.3 → 0.1.0

package/dist/browser-evidence.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Browser Host evidence stub (U3 thin): failure screenshot + wall-clock step timing.
+ * Not a full U3 artifact pack (no network.json / accessible-tree / trace viewer).
+ */
+export type StepTiming = {
+    phase: 'action' | 'assertion';
+    kind: string;
+    ms: number;
+    ok: boolean;
+    detail?: string;
+};
+export type BrowserTiming = {
+    schema: 'vmz.test.browser.timing.v0';
+    totalMs: number;
+    steps: StepTiming[];
+};
+export type EvidencePaths = {
+    dir: string;
+    screenshot?: string;
+    timing?: string;
+    dom?: string;
+};
+export declare function createArtifactsDir(outDir: string, testId: string): string;
+export declare function createTempArtifactsDir(testId: string): string;
+export declare function writeFailureEvidence(page: {
+    screenshot?: (opts: {
+        path: string;
+        fullPage?: boolean;
+    }) => Promise<unknown>;
+    content?: () => Promise<string>;
+}, artifactsDir: string, timing: BrowserTiming): Promise<EvidencePaths>;
+export declare function writeTimingOnly(artifactsDir: string, timing: BrowserTiming): string;

package/dist/browser-evidence.js

@@ -0,0 +1,51 @@
+/**
+ * Browser Host evidence stub (U3 thin): failure screenshot + wall-clock step timing.
+ * Not a full U3 artifact pack (no network.json / accessible-tree / trace viewer).
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function createArtifactsDir(outDir, testId) {
+    const safe = String(testId || 'anonymous').replace(/[^\w.-]+/g, '_');
+    const base = path.join(outDir, '_vmz', 'test-artifacts', safe);
+    fs.mkdirSync(base, { recursive: true });
+    return base;
+}
+export function createTempArtifactsDir(testId) {
+    const safe = String(testId || 'anonymous').replace(/[^\w.-]+/g, '_');
+    return fs.mkdtempSync(path.join(os.tmpdir(), `vmz-bh-${safe}-`));
+}
+export async function writeFailureEvidence(page, artifactsDir, timing) {
+    fs.mkdirSync(artifactsDir, { recursive: true });
+    const out = { dir: artifactsDir };
+    const timingPath = path.join(artifactsDir, 'timing.json');
+    fs.writeFileSync(timingPath, JSON.stringify(timing, null, 2), 'utf8');
+    out.timing = timingPath;
+    try {
+        if (typeof page.screenshot === 'function') {
+            const shot = path.join(artifactsDir, 'screenshot.png');
+            await page.screenshot({ path: shot, fullPage: true });
+            out.screenshot = shot;
+        }
+    }
+    catch {
+        /* screenshot optional */
+    }
+    try {
+        if (typeof page.content === 'function') {
+            const domPath = path.join(artifactsDir, 'dom.html');
+            fs.writeFileSync(domPath, await page.content(), 'utf8');
+            out.dom = domPath;
+        }
+    }
+    catch {
+        /* optional */
+    }
+    return out;
+}
+export function writeTimingOnly(artifactsDir, timing) {
+    fs.mkdirSync(artifactsDir, { recursive: true });
+    const timingPath = path.join(artifactsDir, 'timing.json');
+    fs.writeFileSync(timingPath, JSON.stringify(timing, null, 2), 'utf8');
+    return timingPath;
+}

package/dist/browser-protocol.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Browser Host U0 protocol — Locator / Action / Expectation shapes.
+ *
+ * Owns VMZ locator semantics. CDP/puppeteer-core is transport only.
+ * Legacy `selector` strings lower to `{ kind: 'css' }` with a warning (escape hatch).
+ */
+export declare const BROWSER_LOCATOR_KINDS: readonly ["role", "label", "text", "testId", "css"];
+export type BrowserLocator = {
+    kind: 'role';
+    role: string;
+    name?: string;
+    exact?: boolean;
+} | {
+    kind: 'label';
+    text: string;
+    exact?: boolean;
+} | {
+    kind: 'text';
+    text: string;
+    exact?: boolean;
+} | {
+    kind: 'testId';
+    testId: string;
+} | {
+    kind: 'css';
+    selector: string;
+};
+export type BrowserActionOptions = {
+    timeoutMs?: number;
+    force?: boolean;
+};
+export type LocatorResolveResult = {
+    ok: boolean;
+    count: number;
+    actionable: boolean;
+    reason: string;
+    index: number;
+    tag?: string;
+    name?: string;
+};
+/**
+ * Parse locator from a browser action object.
+ * Prefers `locator`; falls back to legacy `selector` → css (warning).
+ */
+export declare function parseActionLocator(action: Record<string, unknown>): {
+    locator: BrowserLocator | null;
+    warnings: string[];
+};
+/** Default click target when neither locator nor selector is set (Direct mount harness). */
+export declare function defaultClickLocator(): BrowserLocator;
+/**
+ * In-page locator resolver (serializable for page.evaluate).
+ * Returns match metadata; host waits until unique + actionable.
+ */
+export declare function resolveLocatorInPage(locator: BrowserLocator, opts?: BrowserActionOptions): LocatorResolveResult;
+export declare function sleep(ms: number): Promise<void>;

package/dist/browser-protocol.js

@@ -0,0 +1,249 @@
+/**
+ * Browser Host U0 protocol — Locator / Action / Expectation shapes.
+ *
+ * Owns VMZ locator semantics. CDP/puppeteer-core is transport only.
+ * Legacy `selector` strings lower to `{ kind: 'css' }` with a warning (escape hatch).
+ */
+export const BROWSER_LOCATOR_KINDS = Object.freeze(['role', 'label', 'text', 'testId', 'css']);
+/**
+ * Parse locator from a browser action object.
+ * Prefers `locator`; falls back to legacy `selector` → css (warning).
+ */
+export function parseActionLocator(action) {
+    const warnings = [];
+    const loc = action && typeof action.locator === 'object' && action.locator
+        ? action.locator
+        : null;
+    if (loc) {
+        const kind = String(loc.kind || '');
+        if (kind === 'role') {
+            const role = String(loc.role || '').trim();
+            if (!role)
+                return { locator: null, warnings: ['locator.role required'] };
+            return {
+                locator: {
+                    kind: 'role',
+                    role,
+                    name: loc.name != null ? String(loc.name) : undefined,
+                    exact: loc.exact === true,
+                },
+                warnings,
+            };
+        }
+        if (kind === 'label') {
+            const text = String(loc.text || '').trim();
+            if (!text)
+                return { locator: null, warnings: ['locator.text required for label'] };
+            return { locator: { kind: 'label', text, exact: loc.exact === true }, warnings };
+        }
+        if (kind === 'text') {
+            const text = String(loc.text || '').trim();
+            if (!text)
+                return { locator: null, warnings: ['locator.text required'] };
+            return { locator: { kind: 'text', text, exact: loc.exact === true }, warnings };
+        }
+        if (kind === 'testId') {
+            const testId = String(loc.testId || loc.value || '').trim();
+            if (!testId)
+                return { locator: null, warnings: ['locator.testId required'] };
+            return { locator: { kind: 'testId', testId }, warnings };
+        }
+        if (kind === 'css') {
+            const selector = String(loc.selector || '').trim();
+            if (!selector)
+                return { locator: null, warnings: ['locator.selector required for css'] };
+            warnings.push('locator.kind=css is an escape hatch; prefer role/label/text/testId');
+            return { locator: { kind: 'css', selector }, warnings };
+        }
+        return { locator: null, warnings: [`unknown locator.kind ${JSON.stringify(kind)}`] };
+    }
+    if (typeof action.selector === 'string' && action.selector.trim()) {
+        warnings.push('action.selector is legacy css escape hatch; prefer action.locator');
+        return { locator: { kind: 'css', selector: action.selector.trim() }, warnings };
+    }
+    return { locator: null, warnings };
+}
+/** Default click target when neither locator nor selector is set (Direct mount harness). */
+export function defaultClickLocator() {
+    return { kind: 'role', role: 'button' };
+}
+/**
+ * In-page locator resolver (serializable for page.evaluate).
+ * Returns match metadata; host waits until unique + actionable.
+ */
+export function resolveLocatorInPage(locator, opts = {}) {
+    const root = document.getElementById('app') || document.body;
+    if (!root)
+        return { ok: false, count: 0, actionable: false, reason: '#app missing', index: -1 };
+    const normalize = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+    const nameOf = (el) => {
+        const labelled = el.getAttribute('aria-label');
+        if (labelled)
+            return normalize(labelled);
+        if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+            const id = el.id;
+            if (id) {
+                const lab = root.querySelector(`label[for="${CSS.escape(id)}"]`);
+                if (lab)
+                    return normalize(lab.textContent || '');
+            }
+        }
+        return normalize(el.innerText || el.textContent || '');
+    };
+    const isVisible = (el) => {
+        if (!(el instanceof Element))
+            return false;
+        const st = window.getComputedStyle(el);
+        if (st.display === 'none' || st.visibility === 'hidden' || Number(st.opacity) === 0)
+            return false;
+        const r = el.getBoundingClientRect();
+        return r.width > 0 && r.height > 0;
+    };
+    const isEnabled = (el) => {
+        if (el instanceof HTMLButtonElement ||
+            el instanceof HTMLInputElement ||
+            el instanceof HTMLSelectElement ||
+            el instanceof HTMLTextAreaElement) {
+            if (el.disabled)
+                return false;
+            if ((el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) && el.readOnly)
+                return false;
+            return true;
+        }
+        return el.getAttribute('aria-disabled') !== 'true';
+    };
+    let found = [];
+    if (locator.kind === 'css') {
+        try {
+            found = [...root.querySelectorAll(String(locator.selector || ''))];
+        }
+        catch (e) {
+            return {
+                ok: false,
+                count: 0,
+                actionable: false,
+                reason: `bad css: ${e instanceof Error ? e.message : e}`,
+                index: -1,
+            };
+        }
+    }
+    else if (locator.kind === 'testId') {
+        const id = String(locator.testId || '');
+        found = [...root.querySelectorAll(`[data-testid="${CSS.escape(id)}"]`)];
+    }
+    else if (locator.kind === 'role') {
+        const role = String(locator.role || '');
+        let pool = [];
+        if (role === 'button') {
+            pool = [...root.querySelectorAll('button, [role="button"], input[type="button"], input[type="submit"]')];
+        }
+        else if (role === 'textbox') {
+            pool = [
+                ...root.querySelectorAll('input:not([type="hidden"]):not([type="checkbox"]):not([type="radio"]):not([type="button"]):not([type="submit"]), textarea, [role="textbox"]'),
+            ];
+        }
+        else if (role === 'link') {
+            pool = [...root.querySelectorAll('a[href], [role="link"]')];
+        }
+        else if (role === 'checkbox') {
+            pool = [...root.querySelectorAll('input[type="checkbox"], [role="checkbox"]')];
+        }
+        else if (role === 'combobox') {
+            pool = [...root.querySelectorAll('select, [role="combobox"]')];
+        }
+        else if (role === 'listbox') {
+            pool = [...root.querySelectorAll('select, [role="listbox"]')];
+        }
+        else if (role === 'option') {
+            pool = [...root.querySelectorAll('option, [role="option"], [data-vmz-option]')];
+        }
+        else {
+            pool = [...root.querySelectorAll(`[role="${CSS.escape(role)}"]`)];
+        }
+        if (locator.name != null && String(locator.name).length) {
+            const want = normalize(locator.name);
+            found = pool.filter((el) => {
+                const n = nameOf(el);
+                const optVal = el.getAttribute('data-vmz-option') || (el instanceof HTMLOptionElement ? el.value : '');
+                return locator.exact
+                    ? n === want || optVal === want
+                    : n.includes(want) || String(optVal).includes(want);
+            });
+        }
+        else {
+            found = pool;
+        }
+    }
+    else if (locator.kind === 'label') {
+        const want = normalize(locator.text);
+        const labels = [...root.querySelectorAll('label')].filter((lab) => {
+            const t = normalize(lab.textContent || '');
+            return locator.exact ? t === want : t.includes(want);
+        });
+        found = labels
+            .map((lab) => {
+            if (lab instanceof HTMLLabelElement && lab.control)
+                return lab.control;
+            const htmlFor = lab.getAttribute('for');
+            if (htmlFor)
+                return root.querySelector(`#${CSS.escape(htmlFor)}`);
+            return lab.querySelector('input, textarea, select');
+        })
+            .filter((el) => Boolean(el));
+    }
+    else if (locator.kind === 'text') {
+        const want = normalize(locator.text);
+        const all = [...root.querySelectorAll('button, a, label, p, span, li, td, th, h1, h2, h3, h4, h5, h6, [role]')];
+        found = all.filter((el) => {
+            const t = normalize(el.innerText || el.textContent || '');
+            if (!t)
+                return false;
+            return locator.exact ? t === want : t.includes(want);
+        });
+    }
+    else {
+        return {
+            ok: false,
+            count: 0,
+            actionable: false,
+            reason: `unknown locator.kind ${locator.kind}`,
+            index: -1,
+        };
+    }
+    const visible = found.filter(isVisible);
+    const actionable = opts.force ? visible : visible.filter(isEnabled);
+    if (actionable.length === 1) {
+        for (const el of root.querySelectorAll('[data-vmz-bh-target]'))
+            el.removeAttribute('data-vmz-bh-target');
+        const target = actionable[0];
+        target.setAttribute('data-vmz-bh-target', '1');
+        return {
+            ok: true,
+            count: 1,
+            actionable: true,
+            reason: '',
+            index: 0,
+            tag: target.tagName.toLowerCase(),
+            name: nameOf(target),
+        };
+    }
+    if (actionable.length === 0) {
+        return {
+            ok: false,
+            count: found.length,
+            actionable: false,
+            reason: found.length === 0 ? 'no matches' : visible.length === 0 ? 'matches not visible' : 'matches not actionable',
+            index: -1,
+        };
+    }
+    return {
+        ok: false,
+        count: actionable.length,
+        actionable: false,
+        reason: `ambiguous: ${actionable.length} actionable matches`,
+        index: -1,
+    };
+}
+export function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/browser-serve.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Browser Host U2 — real VMZ serve-host lifecycle + RouteId → path resolution.
+ */
+export type ServeHostHandle = {
+    port: number;
+    origin: string;
+    kill: () => void;
+};
+/**
+ * Resolve author RouteId / pathPattern to a pathname for page.goto.
+ * Prefers explicit path; then cdn-policy-manifest; then route-realization.
+ */
+export declare function resolveRoutePath(outDir: string, opts: {
+    routeId?: string;
+    path?: string;
+    params?: Record<string, string>;
+}): string;
+export declare function startServeHost(outDir: string): Promise<ServeHostHandle>;
+export declare function isServeHostManifest(manifest: Record<string, unknown>): boolean;

package/dist/browser-serve.js

@@ -0,0 +1,130 @@
+/**
+ * Browser Host U2 — real VMZ serve-host lifecycle + RouteId → path resolution.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const s = net.createServer();
+        s.listen(0, '127.0.0.1', () => {
+            const addr = s.address();
+            if (!addr || typeof addr === 'string') {
+                s.close();
+                reject(new Error('freePort: no address'));
+                return;
+            }
+            const port = addr.port;
+            s.close((err) => (err ? reject(err) : resolve(port)));
+        });
+        s.on('error', reject);
+    });
+}
+/**
+ * Resolve author RouteId / pathPattern to a pathname for page.goto.
+ * Prefers explicit path; then cdn-policy-manifest; then route-realization.
+ */
+export function resolveRoutePath(outDir, opts) {
+    if (typeof opts.path === 'string' && opts.path.trim()) {
+        return applyParams(opts.path.trim(), opts.params);
+    }
+    const routeId = String(opts.routeId || '').trim();
+    if (!routeId)
+        throw new Error('open/navigate: routeId or path required');
+    const cdnPath = path.join(outDir, '_vmz', 'cdn-policy-manifest.json');
+    if (fs.existsSync(cdnPath)) {
+        try {
+            const doc = JSON.parse(fs.readFileSync(cdnPath, 'utf8'));
+            const entries = Array.isArray(doc.entries) ? doc.entries : [];
+            const hit = entries.find((e) => e.routeId === routeId && (!e.localeId || e.localeId === 'en-us') && e.path) ||
+                entries.find((e) => e.routeId === routeId && e.path);
+            if (hit?.path)
+                return applyParams(String(hit.path), opts.params);
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    const rrPath = path.join(outDir, '_vmz', 'route-realization.json');
+    if (fs.existsSync(rrPath)) {
+        try {
+            const doc = JSON.parse(fs.readFileSync(rrPath, 'utf8'));
+            const routes = Array.isArray(doc.routes) ? doc.routes : [];
+            const hit = routes.find((r) => r.routeId === routeId) ||
+                routes.find((r) => r.routeId === `pages/${routeId}`) ||
+                routes.find((r) => String(r.routeId || '').endsWith(`/${routeId}`));
+            if (hit?.pathPattern)
+                return applyParams(String(hit.pathPattern), opts.params);
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    throw new Error(`open/navigate: cannot resolve RouteId ${JSON.stringify(routeId)} (no path / cdn / realization)`);
+}
+function applyParams(pattern, params) {
+    if (!params)
+        return pattern;
+    let out = pattern;
+    for (const [k, v] of Object.entries(params)) {
+        out = out.replace(new RegExp(`\\[${k}\\]`, 'g'), encodeURIComponent(String(v)));
+        out = out.replace(new RegExp(`:${k}\\b`, 'g'), encodeURIComponent(String(v)));
+    }
+    return out;
+}
+export async function startServeHost(outDir) {
+    const hostJs = path.join(outDir, 'vmz-serve-host.mjs');
+    if (!fs.existsSync(hostJs)) {
+        throw new Error(`serve host: missing ${hostJs} (run vmz build for application dist)`);
+    }
+    const port = await freePort();
+    const child = spawn(process.execPath, [hostJs], {
+        cwd: outDir,
+        env: { ...process.env, VMZ_DIST: outDir, VMZ_HOST: '127.0.0.1', VMZ_PORT: String(port) },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const kill = () => {
+        try {
+            child.kill('SIGTERM');
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    await new Promise((resolve, reject) => {
+        const t = setTimeout(() => {
+            kill();
+            reject(new Error(`serve host start timeout :${port}`));
+        }, 12000);
+        const onData = (buf) => {
+            if (String(buf).includes('vmz serve http://')) {
+                clearTimeout(t);
+                child.stdout?.off('data', onData);
+                resolve();
+            }
+        };
+        child.stdout?.on('data', onData);
+        child.stderr?.on('data', () => {
+            /* absorb */
+        });
+        child.on('exit', (code) => {
+            clearTimeout(t);
+            reject(new Error(`serve host exited early ${code}`));
+        });
+    });
+    return { port, origin: `http://127.0.0.1:${port}`, kill };
+}
+export function isServeHostManifest(manifest) {
+    const host = manifest.host && typeof manifest.host === 'object' ? manifest.host : null;
+    if (host && (host.kind === 'serve' || host.mode === 'serve'))
+        return true;
+    const program = manifest.program && typeof manifest.program === 'object' ? manifest.program : null;
+    if (program && (program.kind === 'application' || program.host === 'serve'))
+        return true;
+    const actions = Array.isArray(manifest.actions) ? manifest.actions : [];
+    return actions.some((raw) => {
+        const a = raw && typeof raw === 'object' ? raw : {};
+        return a.kind === 'open' || a.kind === 'navigate';
+    });
+}

package/dist/browser.d.ts

@@ -1,11 +1,14 @@
 /**
- * Browser Host for `vmz test --mode browser` ( close slice).
+ * Browser Host for `vmz test --mode browser` (U0–U2 thin).
  *
  * Real Chromium/Chrome via CDP. Transport may use puppeteer-core as a CDP
  * client — that is NOT the Playwright/Puppeteer *test model*. Manifest actions
- * and assertions remain the VMZ Browser Host protocol; same Direct schedule as
- * production (`__vmzCreate` in a real document).
+ * and assertions remain the VMZ Browser Host protocol.
  *
+ * U0: Locator / Action / Expectation dispatcher (browser-protocol.ts).
+ * U1: role/label/text/testId; click/fill/press/select; actionability + auto-wait.
+ * U2: real serve-host + RouteId open/navigate; console/request fail gate;
+ *     wall-clock timing + failure screenshot/DOM (not full U3 artifact pack).
  */
 type Diag = {
     severity: string;