craftdriver 1.2.0 → 1.3.0

package/dist/lib/vibiumTrace.js

@@ -0,0 +1,372 @@
+/**
+ * Export Craftdriver's crash-resilient trace directory as the
+ * Playwright-compatible recording layout consumed by Vibium Player.
+ */
+import { createWriteStream, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import yazl from 'yazl';
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+const ACTIONS = {
+    navigateTo: { class: 'Page', method: 'navigate' },
+    goBack: { class: 'Page', method: 'goBack' },
+    goForward: { class: 'Page', method: 'goForward' },
+    reload: { class: 'Page', method: 'reload' },
+    setContent: { class: 'Page', method: 'setContent' },
+    click: { class: 'Element', method: 'click' },
+    fill: { class: 'Element', method: 'fill' },
+    clear: { class: 'Element', method: 'clear' },
+    acceptDialog: { class: 'Dialog', method: 'accept' },
+    dismissDialog: { class: 'Dialog', method: 'dismiss' },
+};
+/** Write a Vibium/Playwright-compatible trace zip from a stopped raw trace. */
+export async function writeVibiumTraceZip(opts) {
+    if (!opts.path)
+        throw new Error('stopTrace({ path }) requires a non-empty zip path.');
+    const raw = readRawTrace(join(opts.sourceDir, 'trace.ndjson'));
+    const started = raw.find((event) => event.type === 'meta' && typeof event.startedAt === 'string');
+    const startWallTime = started?.startedAt ? Date.parse(started.startedAt) : Date.now();
+    const id = randomBytes(6).toString('hex');
+    const contextId = `context@${id}`;
+    const pageId = `page@${id}`;
+    const resources = [];
+    const ordered = [];
+    const exportedActions = [];
+    let sequence = 0;
+    let callCounter = 0;
+    const screenshots = raw.filter((event) => event.type === 'screenshot');
+    const firstScreenshot = screenshots.find((event) => existsSync(join(opts.sourceDir, event.file)));
+    const viewport = firstScreenshot
+        ? readPngSize(readFileSync(join(opts.sourceDir, firstScreenshot.file)))
+        : { width: 1280, height: 720 };
+    const actionTimes = [];
+    const actionEnds = new Map(raw.filter((event) => event.type === 'action-end').map((event) => [event.actionIndex, event]));
+    for (const event of raw) {
+        if (event.type !== 'action')
+            continue;
+        const callId = `call@${++callCounter}`;
+        const actionIndex = event.actionIndex ?? callCounter;
+        const completed = actionEnds.get(actionIndex);
+        const endTime = Math.max(event.t + 1, completed?.t ?? event.t + 1);
+        const mapping = ACTIONS[event.name] ?? { class: 'Browser', method: event.name };
+        const params = actionParams(event);
+        actionTimes.push(event.t);
+        const before = {
+            type: 'before',
+            callId,
+            startTime: event.t,
+            class: mapping.class,
+            method: mapping.method,
+            pageId,
+            params,
+            title: actionTitle(mapping, params),
+        };
+        const after = { type: 'after', callId, endTime };
+        if (completed?.error) {
+            after.error = { name: 'Error', message: completed.error };
+        }
+        exportedActions.push({ callId, before, after });
+        ordered.push({
+            time: event.t,
+            order: 3,
+            sequence: sequence++,
+            value: before,
+        });
+        // Older raw traces have no completion marker. Use WDIO's conservative
+        // 1 ms minimum for those; current traces carry the real end timestamp.
+        ordered.push({
+            time: endTime,
+            order: 1,
+            sequence: sequence++,
+            value: after,
+        });
+    }
+    const usedResourceNames = new Set();
+    const addFrame = (sourcePath, frameTime) => {
+        if (!existsSync(sourcePath))
+            return undefined;
+        const data = readFileSync(sourcePath);
+        const size = readPngSize(data);
+        let wallTime = startWallTime + Math.max(0, Math.floor(frameTime));
+        let resourceName = `${pageId}-${wallTime}.png`;
+        while (usedResourceNames.has(resourceName)) {
+            resourceName = `${pageId}-${++wallTime}.png`;
+        }
+        usedResourceNames.add(resourceName);
+        resources.push({ sourcePath, name: resourceName });
+        ordered.push({
+            time: frameTime,
+            order: 2,
+            sequence: sequence++,
+            value: {
+                type: 'screencast-frame',
+                pageId,
+                sha1: resourceName,
+                width: size.width,
+                height: size.height,
+                timestamp: frameTime,
+            },
+        });
+        return {
+            time: frameTime,
+            name: resourceName,
+            width: size.width,
+            height: size.height,
+            dataUri: `data:image/png;base64,${data.toString('base64')}`,
+            url: pageUrlAt(raw, frameTime),
+        };
+    };
+    const actionFrames = new Map();
+    let finalFrame;
+    for (const event of screenshots) {
+        const frameTime = event.actionIndex
+            ? (actionTimes[event.actionIndex - 1] ?? event.t)
+            : event.t;
+        const frame = addFrame(join(opts.sourceDir, event.file), frameTime);
+        if (!frame)
+            continue;
+        if (event.actionIndex !== undefined)
+            actionFrames.set(event.actionIndex, frame);
+        if (event.reason === 'final')
+            finalFrame = frame;
+    }
+    // Backwards compatibility for traces produced by the first recipe draft.
+    const finalScreenshot = join(opts.sourceDir, 'final.png');
+    if (!finalFrame && existsSync(finalScreenshot)) {
+        const finalTime = Math.max(0, ...raw.map((event) => event.t)) + 1;
+        finalFrame = addFrame(finalScreenshot, finalTime);
+    }
+    // Vibium uses a minimal HTML document containing the screenshot as its
+    // Playwright-compatible frame snapshot. This makes the main viewer panel
+    // useful without pretending Craftdriver captured a restorable page DOM.
+    for (let index = 0; index < exportedActions.length; index++) {
+        const action = exportedActions[index];
+        const beforeFrame = actionFrames.get(index + 1);
+        const afterFrame = actionFrames.get(index + 2) ?? finalFrame;
+        if (beforeFrame) {
+            const name = `before@${action.callId}`;
+            action.before.beforeSnapshot = name;
+            addFrameSnapshot(ordered, action.callId, name, pageId, beforeFrame, sequence++);
+        }
+        if (afterFrame) {
+            const name = `after@${action.callId}`;
+            action.after.afterSnapshot = name;
+            addFrameSnapshot(ordered, action.callId, name, pageId, afterFrame, sequence++);
+        }
+    }
+    for (const event of raw) {
+        const value = bidiEvent(event);
+        if (!value)
+            continue;
+        ordered.push({ time: event.t, order: 2, sequence: sequence++, value });
+    }
+    ordered.sort((a, b) => a.time - b.time || a.order - b.order || a.sequence - b.sequence);
+    const contextOptions = {
+        version: 8,
+        type: 'context-options',
+        origin: 'library',
+        libraryName: 'craftdriver',
+        libraryVersion: pkg.version,
+        browserName: opts.browserName === 'chrome' ? 'chromium' : opts.browserName,
+        platform: process.platform === 'darwin' ? 'darwin' : process.platform === 'win32' ? 'windows' : 'linux',
+        wallTime: startWallTime,
+        monotonicTime: 0,
+        sdkLanguage: 'javascript',
+        title: opts.title ?? 'Craftdriver trace',
+        contextId,
+        options: { viewport },
+    };
+    const traceText = [contextOptions, ...ordered.map((event) => event.value)]
+        .map((event) => JSON.stringify(event))
+        .join('\n');
+    const networkText = buildNetworkTrace(raw, startWallTime, pageId);
+    mkdirSync(dirname(opts.path), { recursive: true });
+    await writeZip(opts.path, traceText, networkText, resources);
+}
+function addFrameSnapshot(ordered, callId, snapshotName, pageId, frame, sequence) {
+    ordered.push({
+        time: frame.time,
+        order: 2.5,
+        sequence,
+        value: {
+            type: 'frame-snapshot',
+            snapshot: {
+                callId,
+                snapshotName,
+                pageId,
+                frameId: pageId,
+                frameUrl: frame.url,
+                doctype: 'html',
+                html: [
+                    'HTML', {},
+                    ['HEAD', {}],
+                    ['BODY', { style: 'margin:0;overflow:hidden' }, [
+                            'IMG', { src: frame.dataUri, style: 'width:100%' },
+                        ]],
+                ],
+                viewport: { width: frame.width, height: frame.height },
+                timestamp: frame.time,
+                wallTime: frame.time,
+                resourceOverrides: [{ url: frame.dataUri, sha1: frame.name }],
+                isMainFrame: true,
+            },
+        },
+    });
+}
+function pageUrlAt(events, time) {
+    let url = 'about:blank';
+    for (const event of events) {
+        if (event.t > time)
+            continue;
+        if (event.type === 'navigation' && event.url)
+            url = event.url;
+    }
+    return url;
+}
+function readRawTrace(path) {
+    return readFileSync(path, 'utf8')
+        .split('\n')
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+function actionParams(event) {
+    if (event.name === 'navigateTo')
+        return { url: event.selector ?? event.args?.[0] };
+    if (event.name === 'fill')
+        return { selector: event.selector, value: event.args?.[0] };
+    if (event.selector)
+        return { selector: event.selector };
+    if (event.name === 'acceptDialog' && event.args?.length)
+        return { text: event.args[0] };
+    if (event.args?.length)
+        return { args: event.args };
+    return {};
+}
+function actionTitle(mapping, params) {
+    const label = params.selector ?? params.url ?? params.text;
+    if (label === undefined)
+        return `${mapping.class}.${mapping.method}()`;
+    return `${mapping.class}.${mapping.method}("${String(label).slice(0, 80)}")`;
+}
+function bidiEvent(event) {
+    if (event.type === 'console') {
+        return {
+            type: 'event',
+            method: 'log.entryAdded',
+            params: { type: 'console', level: event.level, text: event.text },
+            time: event.t,
+            class: 'BrowserContext',
+        };
+    }
+    if (event.type === 'error') {
+        return {
+            type: 'event',
+            method: 'log.entryAdded',
+            params: { type: 'javascript', level: 'error', text: event.text },
+            time: event.t,
+            class: 'BrowserContext',
+        };
+    }
+    if (event.type === 'navigation') {
+        return {
+            type: 'event',
+            method: 'browsingContext.navigationStarted',
+            params: { url: event.url, context: event.context },
+            time: event.t,
+            class: 'BrowserContext',
+        };
+    }
+    return null;
+}
+function buildNetworkTrace(events, startWallTime, pageId) {
+    const requests = events
+        .filter((event) => event.type === 'request')
+        .map((event) => ({ ...event }));
+    const snapshots = [];
+    for (const response of events) {
+        if (response.type !== 'response')
+            continue;
+        const request = requests.find((candidate) => !candidate.used && ((response.requestId !== undefined && candidate.requestId === response.requestId) ||
+            (response.requestId === undefined && candidate.url === response.url)));
+        if (!request)
+            continue;
+        request.used = true;
+        const duration = Math.max(0, response.t - request.t);
+        const contentTypeHeaders = response.mimeType
+            ? [{ name: 'Content-Type', value: response.mimeType }]
+            : [];
+        snapshots.push({
+            type: 'resource-snapshot',
+            snapshot: {
+                startedDateTime: new Date(startWallTime + request.t).toISOString(),
+                time: duration,
+                request: {
+                    method: request.method,
+                    url: request.url,
+                    httpVersion: 'HTTP/1.1',
+                    cookies: [],
+                    headers: [],
+                    queryString: queryString(request.url),
+                    headersSize: -1,
+                    bodySize: -1,
+                },
+                response: {
+                    status: response.status,
+                    statusText: '',
+                    httpVersion: 'HTTP/1.1',
+                    cookies: [],
+                    headers: contentTypeHeaders,
+                    content: { size: 0, mimeType: response.mimeType ?? '' },
+                    redirectURL: '',
+                    headersSize: -1,
+                    bodySize: -1,
+                },
+                cache: response.fromCache ? { _fromCache: true } : {},
+                timings: { send: -1, wait: duration, receive: -1 },
+                _monotonicTime: request.t,
+                _frameref: pageId,
+            },
+        });
+    }
+    return snapshots.map((snapshot) => JSON.stringify(snapshot)).join('\n');
+}
+function queryString(url) {
+    try {
+        return [...new URL(url).searchParams].map(([name, value]) => ({ name, value }));
+    }
+    catch {
+        return [];
+    }
+}
+function readPngSize(data) {
+    const isPng = data.length >= 24 && data.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+    if (!isPng)
+        return { width: 1280, height: 720 };
+    return { width: data.readUInt32BE(16), height: data.readUInt32BE(20) };
+}
+function writeZip(path, traceText, networkText, resources) {
+    return new Promise((resolve, reject) => {
+        const zip = new yazl.ZipFile();
+        zip.addBuffer(Buffer.from(traceText, 'utf8'), 'trace.trace');
+        zip.addBuffer(Buffer.from(networkText, 'utf8'), 'trace.network');
+        for (const resource of resources) {
+            zip.addFile(resource.sourcePath, `resources/${resource.name}`);
+        }
+        const output = createWriteStream(path);
+        zip.outputStream.on('error', reject);
+        output.on('error', reject);
+        output.on('close', resolve);
+        zip.outputStream.pipe(output);
+        zip.end();
+    });
+}
+//# sourceMappingURL=vibiumTrace.js.map

package/dist/lib/vibiumTrace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vibiumTrace.js","sourceRoot":"","sources":["../../src/lib/vibiumTrace.ts"],"names":[],"mappings":"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"}

package/docs/api-reference.md

@@ -82,6 +82,7 @@ Capture console output, JavaScript errors, and trace artifacts.
 | `JavaScriptError` | type | — | [browser-logs](browser-logs.md) |
 | `LogMessage` | type | — | [browser-logs](browser-logs.md) |
 | `TraceStartOptions` | type | — | [tracing](tracing.md) |
+| `TraceStopOptions` | type | — | [tracing](tracing.md) |
 | `TraceScreenshotMode` | type | Screenshot mode for tracing. | [tracing](tracing.md) |
 | `TraceEvent` | type | — | [tracing](tracing.md) |
 
@@ -130,4 +131,4 @@ Handle stable CraftDriver errors or customize browser driver services.
 | `FirefoxService` | class | — | [getting-started](getting-started.md) |
 | `FirefoxServiceOptions` | type | — | [getting-started](getting-started.md) |
 
-Total exports: **60**.
+Total exports: **61**.

package/docs/mcp.md

@@ -53,7 +53,7 @@ goose configure   # add craftdriver as a stdio server
 
 ## Tools
 
-Compact set — 14 tools, one line each. Long help lives in the schema
+Compact set — 15 tools, one line each. Long help lives in the schema
 description; clients render it in the model's context once per session.
 
 | Tool                     | Purpose                                                                |
@@ -70,11 +70,25 @@ description; clients render it in the model's context once per session.
 | `browser_pages`          | List open pages (id, url, title).                                      |
 | `browser_snapshot`       | **Sanitized DOM summary with refs.** Use `ref=eN` as the selector for subsequent calls. |
 | `browser_screenshot`     | Capture PNG to a file (auto-allocated under the per-session artifact dir; never inlined). |
+| `browser_trace`          | Start/stop tracing and export a Vibium Player compatible zip.            |
 | `browser_status`         | Browser up? Which URL is active?                                       |
 | `browser_advanced_eval`  | Evaluate JS in the page. Last resort.                                  |
 
-`browser_trace` (start/stop/explain) and trace resources are slated
-for a future release alongside richer trace introspection.
+Trace a complete agent-driven session with two calls:
+
+```jsonc
+{ "name": "browser_trace", "arguments": {
+  "action": "start", "out_dir": "./traces/agent-raw", "title": "Agent flow"
+} }
+// ...browser_navigate / browser_fill / browser_click calls...
+{ "name": "browser_trace", "arguments": {
+  "action": "stop", "path": "./traces/agent-flow.zip"
+} }
+```
+
+The zip opens at [player.vibium.dev](https://player.vibium.dev/). The raw
+directory remains available if the MCP client disconnects before the stop
+call; in that case there is no finalized zip.
 
 ## Selector syntax
 

package/docs/public/recipes/trace-failing-test.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./debug-failing-tests-with-traces">
+    <link
+      rel="canonical"
+      href="https://dtopuzov.github.io/craftdriver/recipes/debug-failing-tests-with-traces"
+    >
+    <title>Vitest traces moved</title>
+    <script>location.replace('./debug-failing-tests-with-traces')</script>
+  </head>
+  <body>
+    <p>This recipe moved to <a href="./debug-failing-tests-with-traces">Debug With Traces</a>.</p>
+  </body>
+</html>

package/docs/public/recipes/vitest-vibium-trace.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./debug-failing-tests-with-traces">
+    <link
+      rel="canonical"
+      href="https://dtopuzov.github.io/craftdriver/recipes/debug-failing-tests-with-traces"
+    >
+    <title>Vitest trace recipe moved</title>
+    <script>location.replace('./debug-failing-tests-with-traces')</script>
+  </head>
+  <body>
+    <p>This recipe moved to <a href="./debug-failing-tests-with-traces">Debug With Traces</a>.</p>
+  </body>
+</html>

package/docs/recipes/debug-failing-tests-with-traces.md

@@ -0,0 +1,117 @@
+# Use Traces To Debug Failing Tests
+
+A failed assertion tells you what was wrong at the end of a test, but often not
+how the browser got there. A trace preserves the actions, screenshots, console
+and JavaScript events, navigation, and network activity that led to the
+failure.
+
+## A Shared Trace Format
+
+[Jason Huggins' SeleniumConf talk](https://www.youtube.com/watch?v=c-OGZK3F0tk&t=1530s)
+was one of the reasons Craftdriver adopted portable browser traces instead of
+a Craftdriver-only viewer format.
+
+The exported zip follows the Playwright-style
+recording layout also used by tools like
+[Vibium](https://github.com/VibiumDev/vibium/blob/main/docs/explanation/recording-format.md)
+and WDIO, so the same artifact can be opened in viewers such as
+[Vibium Player](https://player.vibium.dev/).
+
+Craftdriver still records a crash-resilient raw NDJSON trace first, then
+packages it into the shared zip format when a test runner asks for an artifact.
+
+## Keep A Trace When A Vitest Test Fails
+
+Start one browser for the suite, but scope tracing to the test hooks.
+`afterEach()` knows whether the test failed, so it can keep only the useful zip:
+
+```ts
+import { afterAll, afterEach, beforeAll, beforeEach, describe, it } from 'vitest';
+import { rmSync } from 'node:fs';
+import path from 'node:path';
+import { Browser } from 'craftdriver';
+
+describe('login', () => {
+  let browser: Browser;
+  const rawTraceDir = path.resolve('test-results/traces/login-raw');
+  const traceZip = path.resolve('test-results/traces/login-failure.zip');
+
+  beforeAll(async () => {
+    browser = await Browser.launch();
+  });
+
+  beforeEach(async () => {
+    await browser.startTrace({
+      outDir: rawTraceDir,
+      title: 'Failing login test',
+    });
+  });
+
+  afterEach(async ({ task }) => {
+    const failed = task.result?.state === 'fail';
+    await browser.stopTrace(failed ? { path: traceZip } : undefined);
+    if (!failed) rmSync(rawTraceDir, { recursive: true, force: true });
+  });
+
+  afterAll(async () => browser.quit());
+
+  it('fills and submits the login form', async () => {
+    await browser.navigateTo(
+      'https://dtopuzov.github.io/craftdriver/examples/login.html',
+    );
+    await browser.fill('#username', 'alice');
+    await browser.fill('#password', 'secret');
+    await browser.click('#submit');
+    await browser.expect('#welcome').toContainText('Welcome back, alice!');
+  });
+});
+```
+
+A passing run removes the raw trace and leaves no artifact. After a normal
+Vitest failure, the evidence is kept here:
+
+```text
+test-results/
+└── traces/
+    ├── login-raw/              # trace.ndjson and evidence screenshots
+    └── login-failure.zip       # open this in Vibium Player
+```
+
+For the best online experience, drop the zip into
+[Vibium Player](https://player.vibium.dev/). To keep the trace entirely local,
+use Playwright Trace Viewer:
+
+```sh
+npx playwright show-trace test-results/traces/login-failure.zip
+```
+
+Craftdriver includes screenshot-backed frame snapshots, so Playwright's main
+browser panel shows the captured page state. It is a visual snapshot rather
+than a restorable DOM, so the DOM/locator inspector is intentionally limited.
+
+If the test process is killed before `afterEach()` runs, a zip cannot be
+finalized, but the append-only `trace.ndjson` and completed screenshots remain
+in `login-raw/`.
+
+## Try A Trace Before Creating A Failure
+
+1. [Download the sample login trace](https://dtopuzov.github.io/craftdriver/traces/vitest-login.zip).
+2. Open [Vibium Player](https://player.vibium.dev/).
+3. Drop `vitest-login.zip` onto the player and step through the login.
+
+`stopTrace()` captures the final page state, so a failed assertion is visible
+as the last player frame. The sample was generated by the runnable Vitest proof
+for this recipe against the same published login page. To exercise the failure
+workflow yourself, change the expected message to `Welcome back, bob!`, run the
+test, and open the resulting `login-failure.zip`.
+
+Trace files can contain screenshots, URLs, console messages, network metadata,
+selectors, and entered values. Use test credentials and review a trace before
+publishing it outside your team.
+
+## Learn More
+
+- [Tracing](../tracing.md)
+- [Use CraftDriver With Vitest Hooks](./vitest-browser-lifecycle.md)
+- [Vibium Player](https://player.vibium.dev/)
+- [Jason Huggins on standardized tracing](https://www.youtube.com/watch?v=c-OGZK3F0tk&t=1530s)

package/docs/recipes.md

@@ -49,4 +49,4 @@ For exact signatures, use the linked feature docs and the
 | ----------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
 | Accessibility regression gate | CI should fail on serious page or component accessibility issues.               | [Run Accessibility Gates](./recipes/accessibility-gate.md)               |
 | Console and JavaScript errors | Tests should fail if the browser reports unexpected client-side errors.         | [Fail On Console And JavaScript Errors](./recipes/console-error-gate.md) |
-| Evidence on failure           | You want a replayable trail of actions, network, logs, errors, and screenshots. | [Capture Failure Evidence With Tracing](./recipes/trace-failing-test.md) |
+| Debug failing tests           | You need the actions, screenshots, logs, and network activity behind a failure. | [Use Traces To Debug Failing Tests](./recipes/debug-failing-tests-with-traces.md) |