craftdriver 1.2.0 → 1.3.0

package/docs/tracing.md

@@ -39,6 +39,50 @@ artefacts/login/
 `try/finally` is the recommended shape, but it's a courtesy — see the
 next section.
 
+## Export for Vibium Player
+
+Pass a zip path when stopping the trace to create a portable recording that
+opens in [Vibium Player](https://player.vibium.dev/) and Playwright Trace
+Viewer:
+
+```ts
+await browser.startTrace({
+  outDir: './artefacts/login-raw',
+  title: 'Login flow',
+});
+
+try {
+  await browser.navigateTo('https://example.com/login');
+  await browser.fill('#user', 'alice');
+  await browser.click('#submit');
+} finally {
+  await browser.stopTrace({ path: './artefacts/login.zip' });
+}
+```
+
+The raw `trace.ndjson` remains the crash-resilient source. The zip is produced
+during `stopTrace()` and contains the Vibium/Playwright layout:
+
+```text
+login.zip
+├── trace.trace       # context-options + before/after actions + browser events
+├── trace.network     # HAR-style resource-snapshot events
+└── resources/        # PNG frames referenced by screencast-frame events
+```
+
+Vibium Player is the recommended online viewer. For local-only inspection:
+
+```sh
+npx playwright show-trace ./artefacts/login.zip
+```
+
+The export includes Craftdriver actions, screenshots, screenshot-backed frame
+snapshots, navigation/console events, and the network metadata that WebDriver
+BiDi exposes to the tracer. Screenshot-backed snapshots make the main panel of
+Playwright Trace Viewer useful while staying honest: they are not a restorable
+DOM. Response bodies and source files remain future work. Browser action spans
+use real start/end times and preserve thrown action errors.
+
 ## What happens when a test throws
 
 Every recorded event hits disk **before** the next line of your test
@@ -70,13 +114,14 @@ since `startTrace`) and a `type`:
 | `type`         | Fields                                                      |
 | -------------- | ----------------------------------------------------------- |
 | `meta`         | `startedAt` / `endedAt`, `opts` on the start line           |
-| `action`       | `name`, `args?`, `selector?`                                |
+| `action`       | `actionIndex`, `name`, `args?`, `selector?`                 |
+| `action-end`   | `actionIndex`, `error?`                                     |
 | `console`      | `level`, `text`                                             |
 | `error`        | `text` (uncaught page errors)                               |
 | `request`      | `url`, `method`, `requestId?`                               |
 | `response`     | `url`, `status`, `mimeType?`, `fromCache?`, `requestId?`    |
 | `navigation`   | `url`, `context?`                                           |
-| `screenshot`   | `file` (relative path), `reason` (`'action'` \| `'error'`), `actionIndex?` |
+| `screenshot`   | `file` (relative path), `reason` (`'action'` \| `'error'` \| `'final'`), `actionIndex?` |
 
 Actions currently logged: `navigateTo`, `goBack`, `goForward`, `reload`,
 `setContent`, `click`, `fill`, `clear`, `acceptDialog`, `dismissDialog`.
@@ -88,6 +133,8 @@ Screenshots are tied to **meaningful moments**, not a timer:
 * Before every logged action — answers *"what did the page look like
   when I clicked?"*
 * On every page error — answers *"what was on screen when it broke?"*
+* Once when `stopTrace()` runs — preserves the state left by the final action
+  or failed assertion.
 
 A 30-second test with 5 clicks produces 5 PNGs, not 300. Turn it off
 when you only want the JSON log:
@@ -149,7 +196,7 @@ Drop this into your test folder (e.g. `tests/auto-trace.ts`):
 
 ```ts
 import { beforeEach, afterEach } from 'vitest';
-import { rmSync, writeFileSync } from 'node:fs';
+import { rmSync } from 'node:fs';
 import { join } from 'node:path';
 import type { Browser, TraceScreenshotMode } from 'craftdriver';
 
@@ -170,19 +217,15 @@ export function autoTrace(getBrowser: () => Browser): void {
 
   afterEach(async ({ task }) => {
     const failed = task.result?.state === 'fail';
-    // Snap the page as it looked at the failed assertion (not just
-    // before the last click).
-    if (failed) {
-      try {
-        const buf = await getBrowser().screenshot();
-        writeFileSync(join(currentDir, 'final.png'), buf);
-      } catch { /* browser may already be dead */ }
-    }
-    try { await getBrowser().stopTrace(); } catch { return; }
+    const keep = MODE === 'always' || failed;
+    const zipPath = `${currentDir}.zip`;
+    try {
+      await getBrowser().stopTrace(keep ? { path: zipPath } : undefined);
+    } catch { return; }
     if (MODE === 'on-failure' && !failed) {
       rmSync(currentDir, { recursive: true, force: true });
     } else if (failed) {
-      console.error(`  📁 trace: ${currentDir}`);
+      console.error(`  📦 Vibium trace: ${zipPath}`);
     }
   });
 }
@@ -211,7 +254,7 @@ describe('Login', () => {
     await browser.navigateTo('http://127.0.0.1:8080/login.html');
     await browser.fill('#user', 'alice');
     await browser.click('#submit');
-    // If this expect throws, ./traces/login/signs-in/trace.ndjson is on disk.
+    // If this expect throws, ./traces/login/signs-in.zip opens in Vibium Player.
   });
 });
 ```
@@ -238,6 +281,42 @@ craftdriver — and the runner-specific glue (pass/fail detection, hook
 order, output paths) belongs on your side. The helper is ~30 lines you
 can read, copy, and adjust to your team's conventions.
 
+### One trace for the whole suite
+
+If the desired boundary is exactly `beforeAll()` → `afterAll()`, record the
+suite continuously and remember failures in `afterEach()`. A passing suite
+does not create a zip; a failing suite does:
+
+```ts
+import { afterAll, afterEach, beforeAll, describe } from 'vitest';
+import { rmSync } from 'node:fs';
+import { Browser } from 'craftdriver';
+
+describe('checkout', () => {
+  let browser: Browser;
+  let failed = false;
+  const rawDir = './traces/checkout-raw';
+  const zipPath = './traces/checkout-failure.zip';
+
+  beforeAll(async () => {
+    browser = await Browser.launch();
+    await browser.startTrace({ outDir: rawDir, title: 'Checkout suite' });
+  });
+
+  afterEach(({ task }) => {
+    failed ||= task.result?.state === 'fail';
+  });
+
+  afterAll(async () => {
+    await browser.stopTrace(failed ? { path: zipPath } : undefined);
+    if (!failed) rmSync(rawDir, { recursive: true, force: true });
+    await browser.quit();
+  });
+
+  // ...tests...
+});
+```
+
 ## API
 
 ### `browser.startTrace(opts)`
@@ -249,6 +328,7 @@ interface TraceStartOptions {
   network?: boolean;                            // default true
   console?: boolean;                            // default true
   screenshots?: boolean | 'auto' | 'off';       // default 'auto'
+  title?: string;                                // viewer title
 }
 ```
 
@@ -256,11 +336,12 @@ Creates `outDir` if missing, opens `outDir/trace.ndjson` for writing,
 and emits the start `meta` line. Throws if a trace is already running
 or BiDi is not enabled.
 
-### `browser.stopTrace()`
+### `browser.stopTrace(opts?)`
 
-Drains in-flight screenshot captures, writes the closing `meta` line,
-and closes the file. Returns `Promise<void>`. Throws if no trace is
-running.
+Captures the final page state, drains in-flight screenshot captures, writes the closing `meta` line,
+and closes the file. With `{ path: './trace.zip' }`, it also exports a
+Vibium/Playwright-compatible zip. Returns `Promise<void>`. Throws if no
+trace is active.
 
 ### Cleanup on `browser.quit()`
 
@@ -272,11 +353,8 @@ case. No file is deleted.
 
 By design, the tracer does not:
 
-* produce a self-contained `.zip` or hosted viewer,
 * record video / fixed-interval screencast,
-* emit HAR (the NDJSON already holds request/response events),
-* capture DOM snapshots or sourcemaps.
+* capture a restorable DOM or sourcemaps.
 
-Those features make sense at much larger scale (Playwright Trace
-Viewer). For a single failing test, a tail-able NDJSON log plus a
-handful of PNGs beats a zip you can't open.
+The raw NDJSON stays deliberately small and tail-able; richer portable
+features can be added to the zip format without weakening crash resilience.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craftdriver",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Modern WebDriver automation library for NodeJS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,6 @@
     "test:chromium": "BROWSER_NAME=chromium vitest run",
     "test:recipes": "HEADLESS=true vitest run --config vitest.recipes.config.ts",
     "bench": "HEADLESS=true vitest run --config vitest.perf.config.ts",
-    "bench:realapp": "HEADLESS=true vitest run --config vitest.perf.realapp.config.ts",
     "clean": "rimraf dist",
     "serve": "http-server ./examples -a 127.0.0.1 -p 8080 -c-1 --cors",
     "examples:start": "npm run serve",
@@ -82,13 +81,9 @@
     "@semantic-release/git": "^10.0.1",
     "@types/node": "^20.0.0",
     "@types/ws": "^8.18.1",
-    "@typescript-eslint/eslint-plugin": "^8.1.0",
+    "@types/yazl": "^3.3.1",
     "@typescript-eslint/parser": "^8.1.0",
     "eslint": "^9.8.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-n": "^17.10.1",
-    "eslint-plugin-promise": "^6.4.0",
     "http-server": "^14.1.1",
     "prettier": "^3.3.3",
     "rimraf": "^6.1.3",
@@ -99,7 +94,8 @@
   },
   "dependencies": {
     "axe-core": "^4.12.1",
-    "ws": "^8.21.0"
+    "ws": "^8.21.0",
+    "yazl": "^3.3.1"
   },
   "overrides": {
     "brace-expansion": "5.0.6",

package/skills/craftdriver/cheatsheet.md

@@ -159,8 +159,10 @@ const download = await browser.waitForDownload(() => browser.click('#download'))
 ```ts
 await browser.screenshot({ path: 'out.png', fullPage: true });
 
-await browser.startTrace({ outDir: './artefacts/run' });
-try { /* ... */ } finally { await browser.stopTrace(); }
+await browser.startTrace({ outDir: './artefacts/run', title: 'Smoke flow' });
+try { /* ... */ } finally {
+  await browser.stopTrace({ path: './artefacts/run.zip' }); // player.vibium.dev
+}
 ```
 
 ## Accessibility

package/skills/craftdriver/patterns.md

@@ -60,6 +60,7 @@ const due = await row.locator('[data-col=due]').text();
 ```ts
 await browser.startTrace({
   outDir: './artefacts/checkout-fail',
+  title: 'Checkout failure',
   screenshots: 'auto',
   network: true,
   console: true,
@@ -70,7 +71,7 @@ try {
   // Trace lands on disk regardless — thrown expects never lose data.
   throw e;
 } finally {
-  await browser.stopTrace();
+  await browser.stopTrace({ path: './artefacts/checkout-fail.zip' });
 }
 ```
 

package/docs/recipes/trace-failing-test.md

@@ -1,51 +0,0 @@
-# Capture Failure Evidence With Tracing
-
-When a complex or occasionally-flaky test fails, the message alone rarely tells
-you why. A trace records the actions, navigation, console output, JavaScript
-errors, network events, and screenshots so you can replay what happened. Wrap
-the flow in a helper that starts a trace, keeps it on failure, and always stops
-it. This recipe traces a sign-in against the live
-[login example](https://dtopuzov.github.io/craftdriver/examples/login.html).
-
-The `try/catch` here is deliberate — it is what keeps the trace directory when
-the flow throws.
-
-```ts
-async function withTrace(name: string, run: () => Promise<void>) {
-  const outDir = `./traces/${name}-${Date.now()}`;
-  await browser.startTrace({ outDir });
-
-  try {
-    await run();
-  } catch (error) {
-    console.error(`Trace kept at ${outDir}`);
-    throw error;
-  } finally {
-    await browser.stopTrace().catch(() => undefined);
-  }
-}
-
-await withTrace('login', async () => {
-  await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/login.html');
-  await browser.getByLabel('Username').fill('alice');
-  await browser.getByLabel('Password').fill('secret');
-  await browser.getByRole('button', { name: 'Sign in' }).click();
-  await browser.expect('#welcome').toContainText('Welcome back, alice!');
-});
-```
-
-## Notes
-
-- The trace file is NDJSON, so it stays useful even if the test throws before `stopTrace()`.
-- Screenshots are stored under the trace directory.
-- For high-volume suites, turn screenshots off unless a test is under investigation:
-
-```ts
-await browser.startTrace({ outDir: './traces/smoke', screenshots: 'off' });
-```
-
-## Learn More
-
-- [Tracing](../tracing.md)
-- [Screenshots](../screenshots.md)
-- [Console Logs And JavaScript Errors](../browser-logs.md)