tracereports 0.1.2 → 0.3.0

package/README.es.md

@@ -9,4 +9,19 @@ Selenium WebDriver y cualquier runner. Node 18+, sin dependencias.
 npm install --save-dev tracereports
 ```
 
+- **Playwright Test**: el reporter envía cada test con sus pasos, error y capturas, más los traces y
+  videos que guarda Playwright; con los fixtures, también la red que vio el navegador, el DOM al
+  fallar y la consola del navegador.
+- **Selenium WebDriver o cualquier runner**: con `seleniumOptions(options)` y `withDriver`, la red (pestaña
+  Red, Lab) y la consola de cada test, y la captura y el DOM al fallar ([guía de Selenium](https://github.com/josemiguellopez/tracereports/blob/main/docs/es/selenium.md)).
+- **Nunca frena ni rompe tus tests**: la evidencia sale en segundo plano, con reintentos y sin
+  duplicados; los shards pueden unirse a la misma ejecución.
+- **Sin servidor**: si el servidor está caído o rechaza el token, la ejecución se graba en local;
+  `tracereports report <carpeta>` arma el reporte HTML y `tracereports push <carpeta>` lo sube después.
+  Con `TRACEREPORTS_OFFLINE=both` además guarda esa copia local mientras envía al servidor
+  ([guía del reporte local](https://github.com/josemiguellopez/tracereports/blob/main/docs/es/local-report.md)).
+- **Configuración** desde el entorno o el `.env` del proyecto (`TRACEREPORTS_URL`, `TRACEREPORTS_TOKEN`…).
+
 Documentación completa: [docs/es/javascript.md](https://github.com/josemiguellopez/tracereports/blob/main/docs/es/javascript.md).
+
+Sin binario instalado, al cerrar se descarga y verifica el renderer v0.2.0 en la caché del usuario; `TRACEREPORTS_BIN_DOWNLOAD=0` permite trabajar sin internet con un binario instalado o en caché. Ver [modo offline](../../docs/es/offline.md).

package/README.md

@@ -9,4 +9,19 @@ Selenium WebDriver and any runner. Node 18+, no dependencies.
 npm install --save-dev tracereports
 ```
 
+- **Playwright Test**: the reporter sends each test with its steps, error and screenshots, plus the
+  traces and videos Playwright keeps; with the fixtures, also the network the browser saw, the DOM
+  at the failure and the browser console.
+- **Selenium WebDriver or any runner**: with `seleniumOptions(options)` and `withDriver`, each test's network
+  (Network tab, Lab) and console, and the screenshot and DOM on failure ([Selenium guide](https://github.com/josemiguellopez/tracereports/blob/main/docs/en/selenium.md)).
+- **Never slows down or breaks your tests**: evidence goes out in the background with retries and
+  no duplicates; shards can join the same run.
+- **Without a server**: if the server is down or rejects the token, the run is recorded locally;
+  `tracereports report <folder>` builds the HTML report and `tracereports push <folder>` uploads it later.
+  With `TRACEREPORTS_OFFLINE=both` it also keeps that local copy while sending to the server
+  ([local report guide](https://github.com/josemiguellopez/tracereports/blob/main/docs/en/local-report.md)).
+- **Configuration** from the environment or the project's `.env` (`TRACEREPORTS_URL`, `TRACEREPORTS_TOKEN`…).
+
 Full documentation: [docs/en/javascript.md](https://github.com/josemiguellopez/tracereports/blob/main/docs/en/javascript.md).
+
+Without an installed binary, closing downloads and verifies the v0.2.0 renderer in the user cache; `TRACEREPORTS_BIN_DOWNLOAD=0` supports offline use with an installed or cached binary. See [offline mode](../../docs/en/offline.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracereports",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "TraceReports client for JavaScript/TypeScript: Playwright Test reporter and fixtures, Selenium WebDriver helpers and a client for any runner.",
   "keywords": [
     "testing",
@@ -43,7 +43,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test \"test/*.test.js\""
+    "test": "node --test \"test/*.test.js\"",
+    "typecheck": "npx --yes -p typescript@7.0.2 tsc --noEmit --strict --skipLibCheck --target es2022 --module nodenext --moduleResolution nodenext test/types/public-api.ts"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.40"

package/src/binary.js

@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { gunzipSync, inflateRawSync } from "node:zlib";
+import { setTimeout as sleep } from "node:timers/promises";
+import { env } from "./env.js";
+
+export const REPORT_VERSION = "0.2.0";
+const RELEASES = "https://github.com/josemiguellopez/tracereports/releases/download";
+const MAX_BINARY = 256 * 1024 * 1024;
+const STALE_LOCK_MS = 300_000;
+const sha = data => createHash("sha256").update(data).digest("hex");
+
+// Read only the exact executable member; archive paths are never used as output paths.
+function executable(archive, name, windows) {
+  let found;
+  const accept = data => { if (found || !data.length || data.length > MAX_BINARY) throw Error("invalid release executable"); found = data; };
+  if (windows) {
+    let end = archive.length - 22;
+    while (end >= Math.max(0, archive.length - 65557) && archive.readUInt32LE(end) !== 0x06054b50) end--;
+    if (end < 0 || archive.readUInt32LE(end) !== 0x06054b50) throw Error("invalid ZIP");
+    let offset = archive.readUInt32LE(end + 16);
+    for (let i = 0; i < archive.readUInt16LE(end + 10); i++) {
+      if (archive.readUInt32LE(offset) !== 0x02014b50) throw Error("invalid ZIP directory");
+      const length = archive.readUInt16LE(offset + 28);
+      if (archive.toString("utf8", offset + 46, offset + 46 + length) === name) {
+        const method = archive.readUInt16LE(offset + 10), size = archive.readUInt32LE(offset + 20);
+        const local = archive.readUInt32LE(offset + 42);
+        if (archive.readUInt32LE(local) !== 0x04034b50 || archive.readUInt32LE(offset + 24) > MAX_BINARY) throw Error("invalid ZIP executable");
+        const start = local + 30 + archive.readUInt16LE(local + 26) + archive.readUInt16LE(local + 28);
+        if (start + size > archive.length) throw Error("truncated ZIP");
+        const compressed = archive.subarray(start, start + size);
+        if (![0, 8].includes(method)) throw Error("unsupported ZIP compression");
+        accept(method === 0 ? compressed : inflateRawSync(compressed, { maxOutputLength: MAX_BINARY }));
+      }
+      offset += 46 + length + archive.readUInt16LE(offset + 30) + archive.readUInt16LE(offset + 32);
+    }
+  } else {
+    const tar = gunzipSync(archive, { maxOutputLength: MAX_BINARY + 8 * 1024 * 1024 });
+    for (let offset = 0; offset + 512 <= tar.length; ) {
+      const header = tar.subarray(offset, offset + 512);
+      if (header.every(b => b === 0)) break;
+      const member = header.toString("utf8", 0, 100).split("\0")[0];
+      const size = parseInt(header.toString("ascii", 124, 136).replace(/\0/g, "").trim(), 8);
+      if (!Number.isSafeInteger(size) || size < 0 || offset + 512 + size > tar.length) throw Error("invalid TAR member");
+      if (member === name && [0, 48].includes(header[156]) && header[345] === 0) accept(tar.subarray(offset + 512, offset + 512 + size));
+      offset += 512 + Math.ceil(size / 512) * 512;
+    }
+  }
+  if (!found) throw Error("release executable missing");
+  return found;
+}
+
+export async function downloadBinary(timeoutMs = 60_000) {
+  const system = { win32: "windows", linux: "linux", darwin: "darwin" }[process.platform];
+  const arch = { x64: "amd64", arm64: "arm64" }[process.arch];
+  if (!system || !arch) throw Error("unsupported report platform");
+  const base = (system === "windows" ? process.env.LOCALAPPDATA : system === "darwin" ? "" : process.env.XDG_CACHE_HOME) ||
+    (system === "darwin" ? path.join(os.homedir(), "Library", "Caches") : path.join(os.homedir(), ".cache"));
+  const parent = path.join(base, "tracereports", REPORT_VERSION), target = path.join(parent, `${system}_${arch}`);
+  const name = system === "windows" ? "tracereports.exe" : "tracereports", binary = path.join(target, name);
+  const cached = () => {
+    try { return fs.lstatSync(binary).isFile() && sha(fs.readFileSync(binary)) === fs.readFileSync(path.join(target, "binary.sha256"), "utf8").trim(); }
+    catch { return false; }
+  };
+  if (cached()) return binary;
+  if (env("BIN_DOWNLOAD", "1") === "0") throw Error("binary download disabled");
+  const deadline = Date.now() + timeoutMs, lock = path.join(parent, `${system}_${arch}.lock`);
+  fs.mkdirSync(parent, { recursive: true });
+  while (true) {
+    if (cached()) return binary;
+    if (Date.now() >= deadline) throw Error("waiting for report binary cache timed out");
+    try { fs.mkdirSync(lock); break; }
+    catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      // A download holds the lock for at most its timeout: an older one was left by a process that
+      // died mid-download and would otherwise block every later run.
+      try { if (Date.now() - fs.statSync(lock).mtimeMs > STALE_LOCK_MS) { fs.rmdirSync(lock); continue; } } catch { /* removed meanwhile */ }
+      await sleep(50);
+    }
+  }
+  let staging;
+  const controller = new AbortController(), timer = setTimeout(() => controller.abort(), Math.max(1, deadline - Date.now()));
+  try {
+    if (cached()) return binary;
+    const baseUrl = env("BIN_BASE_URL") || RELEASES;
+    if (baseUrl !== RELEASES) {
+      const url = new URL(baseUrl);
+      if (url.protocol !== "http:" || !["127.0.0.1", "localhost", "[::1]"].includes(url.hostname) || url.username || url.password) throw Error("BIN_BASE_URL must be a loopback test server");
+    }
+    const asset = `tracereports_${REPORT_VERSION}_${system}_${arch}.${system === "windows" ? "zip" : "tar.gz"}`;
+    const download = async (filename, limit) => {
+      const response = await fetch(`${baseUrl.replace(/\/$/, "")}/v${REPORT_VERSION}/${filename}`, { signal: controller.signal });
+      if (!response.ok) { await response.body?.cancel(); throw Error(`release download HTTP ${response.status}`); }
+      const chunks = []; let size = 0;
+      for await (const chunk of response.body) {
+        size += chunk.length;
+        if (size > limit) throw Error("release download too large");
+        chunks.push(chunk);
+      }
+      return Buffer.concat(chunks);
+    };
+    const checksums = (await download("checksums.txt", 1024 * 1024)).toString("utf8");
+    const hashes = checksums.split(/\r?\n/).map(line => line.trim().split(/\s+/)).filter(p => p.length === 2 && p[1].replace(/^\*/, "") === asset).map(p => p[0].toLowerCase());
+    if (hashes.length !== 1 || !/^[a-f0-9]{64}$/.test(hashes[0])) throw Error("release checksum missing or ambiguous");
+    const archive = await download(asset, 128 * 1024 * 1024);
+    if (sha(archive) !== hashes[0]) throw Error("release checksum mismatch");
+    const data = executable(archive, name, system === "windows");
+    fs.mkdirSync(target, { recursive: true });
+    staging = fs.mkdtempSync(path.join(parent, ".download-"));
+    fs.writeFileSync(path.join(staging, name), data, { mode: 0o755 });
+    fs.writeFileSync(path.join(staging, "binary.sha256"), sha(data));
+    // Other processes wait on the lock while the two cache files are replaced.
+    fs.rmSync(binary, { force: true });
+    fs.rmSync(path.join(target, "binary.sha256"), { force: true });
+    fs.renameSync(path.join(staging, "binary.sha256"), path.join(target, "binary.sha256"));
+    fs.renameSync(path.join(staging, name), binary);
+    return binary;
+  } finally {
+    clearTimeout(timer);
+    if (staging) fs.rmSync(staging, { recursive: true, force: true });
+    fs.rmdirSync(lock);
+  }
+}

package/src/env.js

@@ -86,10 +86,13 @@ export function resetEnvFile() {
   filePath = null;
 }
 
-/** TRACEREPORTS_<name>: primero del entorno, después del .env del proyecto. */
+/**
+ * TRACEREPORTS_<name>: del entorno y, si no está definida ahí, del .env del proyecto. Definida en el
+ * entorno manda aunque esté vacía (como en el servidor): vacía es "sin configurar" (fallback) y el
+ * .env no la reemplaza.
+ */
 export function env(name, fallback = undefined) {
-  for (const v of [process.env[PREFIX + name], fromFile()[PREFIX + name]]) {
-    if (v !== undefined && v !== "") return v;
-  }
-  return fallback;
+  const own = process.env[PREFIX + name];
+  const v = own !== undefined ? own : fromFile()[PREFIX + name];
+  return v !== undefined && v !== "" ? v : fallback;
 }

package/src/index.d.ts

@@ -4,11 +4,21 @@ export interface Delivery {
   sent: number; retried: number; rejected: number; dropped: number; lost: number; pending: number; unregisteredTests: number;
   /** 1 si el servidor no confirmó el cierre de la ejecución. */
   runNotClosed: number;
+  /** Events recorded locally, including the copy in both mode. */
+  recorded?: number;
 }
 
 export interface TraceReportsOptions {
   baseUrl?: string; token?: string; enabled?: boolean; timeoutMs?: number; uploadTimeoutMs?: number;
   flushTimeoutMs?: number; maxQueueItems?: number; maxQueueMB?: number;
+  /** Exact recording folder, shared by the processes of one run (default $TRACEREPORTS_OFFLINE_DIR; without it, a new folder per session inside offlineBase). */
+  offlineDir?: string;
+  /** Folder where each session creates its own recording folder (default $TRACEREPORTS_OFFLINE_BASE or ./tracereports-offline). */
+  offlineBase?: string;
+  /** Label for automatically created recording folders (default: the run name). */
+  offlineName?: string;
+  /** auto (default): record if run creation fails; always: no server; both: send and record; off: never record. */
+  offline?: "auto" | "always" | "both" | "off";
 }
 
 export interface RunOptions { environment?: string; project?: string; branch?: string; commit?: string; framework?: string }
@@ -16,6 +26,10 @@ export interface RunOptions { environment?: string; project?: string; branch?: s
 export interface TestOptions {
   category?: string; description?: string; key?: string; suite?: string; params?: string; worker?: string | number;
   status?: string; onFailure?: (t: TraceTest, err: unknown) => unknown | Promise<unknown>;
+  /** Right after the test starts (e.g. discard the browser logs of earlier tests). */
+  onStart?: (t: TraceTest) => unknown | Promise<unknown>;
+  /** Before the test is closed, passed or failed (`err` is null when it passed): network, console... */
+  onEnd?: (t: TraceTest, err: unknown) => unknown | Promise<unknown>;
 }
 
 export type Status = "INFO" | "PASS" | "FAIL" | "WARNING" | "SKIP";
@@ -25,6 +39,8 @@ export interface Connection {
   failed?: boolean; error_text?: string; started_at?: number; duration_ms?: number | null;
   request_headers?: Record<string, string>; post_data?: string; response_headers?: Record<string, string>;
   response_body?: string; body_size?: number; expected?: boolean;
+  /** The body was already cut before reaching the client (body_size keeps the original size). */
+  body_truncated?: boolean;
 }
 
 export class TraceReports {
@@ -32,9 +48,13 @@ export class TraceReports {
   baseUrl: string; runId: number | null; runCreated: boolean; enabled: boolean;
   readonly delivery: Delivery;
   readonly reportUrl: string;
+  /** True when evidence is recorded locally, including both mode. */
+  readonly recording: boolean;
+  offlineDir: string | null;
+  offlineReport: string | null;
   deliveryProblems(): number;
   startRun(name: string, opts?: RunOptions): Promise<number | null>;
-  joinRun(runId: number | string): number | null;
+  joinRun(runId: number | string, opts?: { offlineDir?: string }): number | null;
   finishRun(opts?: { interrupted?: boolean }): Promise<unknown>;
   flush(timeoutMs?: number): Promise<number>;
   startTest(name: string, opts?: TestOptions): Promise<TraceTest>;
@@ -42,7 +62,13 @@ export class TraceReports {
   test<T>(name: string, opts: TestOptions, fn: (t: TraceTest) => T | Promise<T>): Promise<T>;
 }
 
+export interface ConsoleEntry { level: "error" | "warning" | "pageerror" | "info" | "log" | "debug"; text: string; location?: string; timestamp?: number }
+
 export class TraceTest {
+  /** Browser console of the test (its "Console" tab). Captured by the tracereports/playwright fixtures. */
+  console(entries: ConsoleEntry[]): boolean;
+  /** Attaches the Playwright trace (trace.zip) or the test video (WebM/MP4): a Buffer or a file path. */
+  artifact(kind: "trace" | "video", data: Buffer | Uint8Array | string, name?: string): boolean;
   readonly id: number | null; readonly active: boolean; attempts: number;
   log(status: Status, message: string, timestamp?: number): void;
   info(message: string): void; pass(message: string): void; fail(message: string): void; warn(message: string): void; skip(message: string): void;
@@ -53,6 +79,10 @@ export class TraceTest {
   finish(status?: Status | "", opts?: { errorMessage?: string; errorTrace?: string; error?: unknown; attempts?: number }): void;
 }
 
+/** Lotes de red (bytes del JSON enviado): el servidor acepta hasta 48 MiB por request. */
+export const NETWORK_BATCH_BYTES: number;
+export const NETWORK_ALONE_BYTES: number;
+export function networkBatches(payload: object[], opts?: { maxCount?: number; maxBytes?: number; aloneBytes?: number }): string[];
 export const DOM_SCRIPT: string;
 
 export function domSnapshotInPage(): unknown;

package/src/index.js

@@ -12,18 +12,71 @@
 //   await cr.finishRun();                                  // espera la cola y cierra la ejecución
 //
 // Nunca rompe ni frena la suite: la evidencia sale en segundo plano con reintentos e
-// Idempotency-Key (sin duplicados); si el servidor no responde, los métodos siguen funcionando
-// como no-op y `cr.delivery` dice qué no llegó.
+// Idempotency-Key (sin duplicados); `cr.delivery` dice qué no llegó. Si la ejecución no se puede
+// crear (sin servidor, caído o con el token equivocado) la evidencia se graba en una carpeta
+// ($TRACEREPORTS_OFFLINE_DIR, default ./tracereports-offline/<sesión>) en vez de perderse:
+// `tracereports report <carpeta>` arma el reporte HTML y `tracereports push <carpeta>` la sube.
 
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 import { detectBranch, detectCommit } from "./context.js";
 import { env } from "./env.js";
+import { Recorder, newSessionDir } from "./offline.js";
+import { Mirror } from "./mirror.js";
 import { Sender } from "./transport.js";
+import { downloadBinary } from "./binary.js";
 
-export const VERSION = "0.1.0";
+export const VERSION = "0.3.0";
 const STATUSES = new Set(["INFO", "PASS", "FAIL", "WARNING", "SKIP"]);
 const truthy = (v) => ["1", "true", "yes"].includes(String(v || "").toLowerCase());
 
+// Lotes de red: el servidor acepta hasta 48 MiB por request. Se arma cada lote por los bytes del
+// JSON que realmente se envía (UTF-8, con escapes), hasta NETWORK_BATCH_BYTES y batchSize
+// conexiones. Una conexión más grande va sola; si sola pasa NETWORK_ALONE_BYTES, se envía sin
+// bodies ni headers (body_truncated, con su body_size original) para que siempre entre.
+export const NETWORK_BATCH_BYTES = 8 << 20;
+export const NETWORK_ALONE_BYTES = 40 << 20;
+
+const cut = (s, n) => {
+  const str = String(s ?? "");
+  if (str.length <= n) return str;
+  const end = /[\uD800-\uDBFF]/.test(str[n - 1]) ? n - 1 : n; // sin partir un par sustituto
+  return str.slice(0, end);
+};
+
+function slimConnection(c) {
+  return {
+    ...c, url: cut(c.url, 4096), status_text: cut(c.status_text, 256), mime_type: cut(c.mime_type, 256),
+    resource_type: cut(c.resource_type, 32), error_text: cut(c.error_text, 2048), method: cut(c.method, 16),
+    request_headers: {}, response_headers: {}, post_data: "", response_body: "", body_truncated: true,
+  };
+}
+
+/** Lotes de JSON {"connections":[...]} de a lo sumo maxBytes y maxCount, en orden. */
+export function networkBatches(payload, { maxCount = 200, maxBytes = NETWORK_BATCH_BYTES, aloneBytes = NETWORK_ALONE_BYTES } = {}) {
+  const head = '{"connections":[', tail = "]}";
+  const out = [];
+  let parts = [], size = 0;
+  for (let c of payload) {
+    let raw = JSON.stringify(c), n = Buffer.byteLength(raw);
+    if (n + head.length + tail.length > aloneBytes) {
+      raw = JSON.stringify(slimConnection(c));
+      n = Buffer.byteLength(raw);
+    }
+    if (parts.length && (parts.length >= maxCount || size + 1 + n > maxBytes)) {
+      out.push(head + parts.join(",") + tail);
+      parts = [];
+      size = head.length + tail.length;
+    }
+    if (!parts.length) size = head.length + tail.length;
+    size += (parts.length ? 1 : 0) + n;
+    parts.push(raw);
+  }
+  if (parts.length) out.push(head + parts.join(",") + tail);
+  return out;
+}
+
 export class TraceReports {
   /**
    * @param {object} [opts]
@@ -35,6 +88,10 @@ export class TraceReports {
    * @param {number} [opts.flushTimeoutMs]  cuánto espera finishRun la cola (default $TRACEREPORTS_FLUSH_TIMEOUT s o 30 s)
    * @param {number} [opts.maxQueueItems]   default 5000
    * @param {number} [opts.maxQueueMB]      default 64
+   * @param {string} [opts.offlineDir] dónde grabar sin servidor (default $TRACEREPORTS_OFFLINE_DIR; sin
+   *   ella, una carpeta nueva por sesión dentro de ./tracereports-offline)
+   * @param {"auto"|"always"|"both"|"off"} [opts.offline] auto (default, $TRACEREPORTS_OFFLINE): grabar solo si
+   *   la ejecución no se puede crear; always: grabar sin intentar un servidor; off: nunca
    */
   constructor(opts = {}) {
     this.baseUrl = (opts.baseUrl || env("URL") || "http://localhost:8080").replace(/\/+$/, "");
@@ -51,6 +108,68 @@ export class TraceReports {
     this.runCreated = false;
     this.runNotClosed = false;
     this.unregisteredTests = 0;
+
+    let mode = String(opts.offline ?? env("OFFLINE", "auto")).trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(mode)) mode = "always";
+    if (["0", "false", "no"].includes(mode)) mode = "off";
+    this.offlineMode = mode;
+    const explicit = opts.offlineDir || env("OFFLINE_DIR") || "";
+    // sin carpeta exacta, cada sesión crea la suya dentro de la base: corridas sucesivas no se pisan
+    this.offlineBase = explicit || opts.offlineBase || env("OFFLINE_BASE") || "tracereports-offline";
+   this.offlineExplicit = Boolean(explicit);
+    this.offlineName = opts.offlineName || env("OFFLINE_NAME", "");
+    this.offlineDir = null; // carpeta donde se graba (null: se envía al servidor)
+    this.offlineReport = null; // index.html generado al cerrar
+  }
+
+  /** true si la evidencia se graba localmente (sin servidor). */
+  get recording() {
+    return this.offlineDir != null;
+  }
+
+  goOffline(reason = "") {
+    const dir = this.offlineExplicit ? this.offlineBase : newSessionDir(this.offlineBase, this.offlineName);
+    try {
+      this.sender = new Recorder(dir);
+    } catch (err) {
+      console.warn(`tracereports: no se pudo grabar en ${dir}: ${err.message}`);
+      return;
+    }
+    this.offlineDir = dir;
+    if (reason) {
+      console.warn(`tracereports: ${reason}; la evidencia se graba en ${dir}`);
+    }
+  }
+
+  goMirror(runId, payload, directory) {
+    const dir = directory || (this.offlineExplicit ? this.offlineBase : newSessionDir(this.offlineBase, this.offlineName));
+    try {
+      this.sender = new Mirror(this.sender, dir, this.baseUrl, runId, payload);
+      this.offlineDir = dir;
+    } catch (err) { console.warn(`tracereports: no se pudo iniciar la copia local en ${dir}: ${err.message}`); }
+  }
+
+  /** Arma el HTML con el binario instalado o el renderer verificado de la caché. */
+  async buildOfflineReport({ zip } = {}) {
+    try {
+      if (["0", "false", "no"].includes(String(env("OFFLINE_REPORT", "1")).toLowerCase())) throw Error("automatic report disabled");
+      const bin = env("BIN") || findInPath("tracereports") || await downloadBinary();
+      const out = path.join(this.offlineDir, "report");
+      const args = ["report", "-o", out, ...(zip ? ["--zip", zip] : []), this.offlineDir];
+      const res = spawnSync(bin, args, { timeout: 300_000, encoding: "utf8" });
+      if (res.status !== 0) throw Error((res.stderr || res.error?.message || "renderer failed").trim());
+      const index = path.join(out, "index.html");
+      if (!fs.statSync(index).isFile()) throw Error("renderer did not create index.html");
+      this.offlineReport = index;
+      if (this.runId > 0) console.warn(`tracereports: server report: ${this.reportUrl}`);
+      console.warn(`tracereports: reporte local: ${this.offlineReport}`);
+      return this.offlineReport;
+    } catch (err) {
+      console.warn(`tracereports: local report unavailable (${err.message}); evidence retained in ${this.offlineDir}. ` +
+        `install the binary and run \`tracereports report ${this.offlineDir}\`, or run ` +
+        `\`tracereports push ${this.offlineDir}\` with the correct token when the server is available.`);
+      return null;
+    }
   }
 
   headers() {
@@ -76,6 +195,7 @@ export class TraceReports {
   }
 
   get reportUrl() {
+    if (this.recording && this.runId < 0) return this.offlineReport || "";
     return this.runId ? `${this.baseUrl}/#run=${this.runId}&view=dashboard` : "";
   }
 
@@ -98,16 +218,26 @@ export class TraceReports {
    * ambiente y rama.
    */
   async startRun(name, { environment = "", project, branch, commit, framework = "" } = {}) {
+    this.offlineName = name || this.offlineName;
     if (env("RUN_ID")) return this.joinRun(env("RUN_ID"));
-    const res = await this.request("POST", "/api/v1/runs", {
+    const payload = {
       name,
       environment,
       project: project ?? env("PROJECT") ?? path.basename(process.cwd()),
       branch: branch ?? detectBranch(),
       commit: commit ?? detectCommit(),
       framework,
-    });
-    this.runId = res?.run_id ?? null;
+    };
+    if (this.enabled && this.offlineMode === "always" && !this.recording) this.goOffline("offline mode");
+    const res = await this.request("POST", "/api/v1/runs", payload);
+    let created = res;
+    if (!created && this.enabled && ["auto", "both"].includes(this.offlineMode) && !this.recording) {
+      // sin servidor, caído o con el token equivocado: se graba en vez de perderlo todo
+      this.goOffline(`no se pudo crear la ejecución en ${this.baseUrl} (servidor caído o token incorrecto)`);
+      if (this.recording) created = await this.request("POST", "/api/v1/runs", payload);
+    }
+    if (created?.run_id > 0 && this.offlineMode === "both" && !this.recording) this.goMirror(created.run_id, payload);
+    this.runId = created?.run_id ?? null;
     this.runCreated = Boolean(this.runId);
     if (this.enabled && !this.runId) {
       console.warn(`tracereports: no se pudo crear la ejecución en ${this.baseUrl}; los tests siguen sin reporte.`);
@@ -115,8 +245,19 @@ export class TraceReports {
     return this.runId;
   }
 
-  /** Reporta en una ejecución creada en otro proceso; quien la creó la cierra. */
-  joinRun(runId) {
+  /**
+   * Reporta en una ejecución creada en otro proceso; quien la creó la cierra. Un runId negativo es
+   * una ejecución que se graba sin servidor: pasa la misma `offlineDir`.
+   */
+  joinRun(runId, { offlineDir } = {}) {
+    if (runId && Number(runId) < 0 && this.enabled && !this.recording) {
+      if (offlineDir || env("OFFLINE_DIR")) {
+        this.offlineBase = offlineDir || env("OFFLINE_DIR");
+        this.offlineExplicit = true;
+      }
+      this.goOffline();
+    }
+    if (Number(runId) > 0 && this.enabled && this.offlineMode === "both" && !this.recording) this.goMirror(Number(runId), null, offlineDir);
     this.runId = runId ? Number(runId) : null;
     this.runCreated = false;
     return this.runId;
@@ -124,13 +265,26 @@ export class TraceReports {
 
   /** Espera la cola (flushTimeoutMs) y cierra la ejecución. interrupted: incompleta, nunca verde. */
   async finishRun({ interrupted = false } = {}) {
-    await this.flush();
+    if (this.sender instanceof Mirror && this.sender.closed) return null;
+    const pending = await this.flush();
     this.sender.abandon();
+    if (!this.runCreated && this.sender instanceof Mirror) this.sender.close(pending === 0 && this.deliveryProblems() === 0 && !interrupted);
     if (!this.runId || !this.runCreated || !this.enabled) return null; // unido a otra: la cierra su dueño
     // el cierre importa más que un paso: más reintentos, siempre con la misma Idempotency-Key
     const res = await this.sender.sendNow("PATCH", `/api/v1/runs/${this.runId}/finish`,
       JSON.stringify({ interrupted }), "application/json", this.timeoutMs, 4, { ignoreCircuit: true });
     this.runNotClosed = res == null;
+    if (this.recording) {
+      if (this.sender instanceof Mirror) {
+        this.sender.close(pending === 0 && this.deliveryProblems() === 0 && !interrupted);
+        const before = this.sender.prepare();
+        await this.buildOfflineReport();
+        this.sender.finalize(this.offlineReport, env("OFFLINE_KEEP") === "1", before);
+        return res;
+      }
+      await this.buildOfflineReport();
+      return res;
+    }
     if (this.runNotClosed) {
       console.warn(`tracereports: el servidor no confirmó el cierre de la ejecución #${this.runId}: quedó abierta ` +
         `(ciérrala con PATCH ${this.baseUrl}/api/v1/runs/${this.runId}/finish)`);
@@ -154,25 +308,29 @@ export class TraceReports {
     if (!this.runId) return new TraceTest(this, null);
     const res = await this.request("POST", `/api/v1/runs/${this.runId}/tests`,
       { name, category, description, key, suite, params, worker: String(worker ?? "") });
-    if (this.enabled && !res?.test_id) this.unregisteredTests++;
+    if (this.enabled && (!res?.test_id || (this.sender instanceof Mirror && res.test_id < 0))) this.unregisteredTests++;
     return new TraceTest(this, res?.test_id ?? null);
   }
 
   /**
    * Corre `fn` como un test: lo inicia, lo cierra según el resultado y, si falla, adjunta la
-   * captura y el snapshot de `onFailure` (opcional). El error se vuelve a lanzar.
+   * captura y el snapshot de `onFailure` (opcional). `onStart` corre al empezar y `onEnd` antes de
+   * cerrarlo, pase o falle (la red y la consola de `withDriver`). El error se vuelve a lanzar.
    */
   async test(name, opts, fn) {
     if (typeof opts === "function") [fn, opts] = [opts, {}];
     const t = await this.startTest(name, opts);
+    // la evidencia nunca rompe el test
+    const hook = async (h, ...args) => { if (h) { try { await h(t, ...args); } catch { /* sin evidencia */ } } };
+    await hook(opts.onStart);
     try {
       const out = await fn(t);
+      await hook(opts.onEnd, null);
       t.finish(opts.status);
       return out;
     } catch (err) {
-      if (opts.onFailure) {
-        try { await opts.onFailure(t, err); } catch { /* la evidencia nunca rompe el test */ }
-      }
+      await hook(opts.onFailure, err);
+      await hook(opts.onEnd, err);
       t.fail(`${err?.name || "Error"}: ${err?.message ?? err}`);
       t.finish("FAIL", { error: err });
       throw err;
@@ -224,6 +382,47 @@ export class TraceTest {
     this.cr.emit("POST", `/api/v1/tests/${this.id}/screenshot`, body, `multipart/form-data; boundary=${boundary}`, this.cr.uploadTimeoutMs);
   }
 
+  /**
+   * Consola del navegador del test (pestaña "Consola"): [{level: "error"|"warning"|"pageerror"|...,
+   * text, location, timestamp}]. Con los fixtures de `tracereports/playwright` se captura sola.
+   */
+  console(entries) {
+    if (!this.active || !entries?.length) return false;
+    return this.cr.emit("POST", `/api/v1/tests/${this.id}/console`, JSON.stringify({ entries: entries.slice(0, 500) }), "application/json",
+      Math.max(this.cr.uploadTimeoutMs, 10_000));
+  }
+
+  /**
+   * Adjunta el trace de Playwright (`kind: "trace"`, el trace.zip) o el video del test
+   * (`kind: "video"`, WebM o MP4): Buffer o ruta. Hasta 100 MB; el reporte muestra el video y abre el
+   * trace en el Trace Viewer.
+   */
+  artifact(kind, data, name = "") {
+    if (!this.active || !data) return false;
+    let body = data;
+    if (typeof data === "string") {
+      try {
+        body = fs.readFileSync(data);
+        name ||= path.basename(data);
+      } catch {
+        return false;
+      }
+    }
+    if (body.length > 100 << 20) {
+      console.warn(`tracereports: ${name || kind} pesa más de 100 MB: no se adjunta`);
+      return false;
+    }
+    const boundary = `----tracereports${Math.random().toString(16).slice(2)}`;
+    const part = (n, v) => `--${boundary}\r\nContent-Disposition: form-data; name="${n}"\r\n\r\n${v}\r\n`;
+    const multipart = Buffer.concat([
+      Buffer.from(part("kind", kind) + part("name", String(name).replace(/[\r\n"]/g, " "))),
+      Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="artifact"\r\nContent-Type: application/octet-stream\r\n\r\n`),
+      Buffer.from(body),
+      Buffer.from(`\r\n--${boundary}--\r\n`),
+    ]);
+    return this.cr.emit("POST", `/api/v1/tests/${this.id}/artifact`, multipart, `multipart/form-data; boundary=${boundary}`, Math.max(this.cr.uploadTimeoutMs, 60_000));
+  }
+
   /**
    * Declara una respuesta negativa que el test verifica a propósito (p. ej. un 401 con
    * credenciales inválidas): no cuenta como error ni como causa del fallo. `url`: texto contenido
@@ -256,14 +455,14 @@ export class TraceTest {
         error_text: String(c.error_text || ""), started_at: Math.round(c.started_at || 0),
         duration_ms: c.duration_ms == null ? null : Math.round(c.duration_ms),
         request_headers: c.request_headers || {}, post_data: String(c.post_data || ""),
-        response_headers: c.response_headers || {}, response_body: body.slice(0, limit),
-        body_size: Math.max(Number(c.body_size || 0), body.length), body_truncated: body.length > limit,
+        // el body pudo llegar ya recortado (captura): su indicador y su tamaño original (bytes) se conservan
+        response_headers: c.response_headers || {}, response_body: cut(body, limit),
+        body_size: Math.max(Number(c.body_size || 0), Buffer.byteLength(body)), body_truncated: Boolean(c.body_truncated) || body.length > limit,
         expected: Boolean(c.expected) || this.isExpected(c),
       };
     });
-    for (let i = 0; i < payload.length; i += batchSize) {
-      this.cr.emit("POST", `/api/v1/tests/${this.id}/network`, JSON.stringify({ connections: payload.slice(i, i + batchSize) }),
-        "application/json", this.cr.uploadTimeoutMs);
+    for (const body of networkBatches(payload, { maxCount: batchSize })) {
+      this.cr.emit("POST", `/api/v1/tests/${this.id}/network`, body, "application/json", this.cr.uploadTimeoutMs);
     }
     return { stored: payload.length, errors: payload.filter((p) => !p.expected && (p.failed || p.status >= 400)).length };
   }
@@ -294,3 +493,17 @@ export class TraceTest {
 
 export { DOM_SCRIPT, domSnapshotInPage } from "./dom.js";
 
+function findInPath(name) {
+  const exts = process.platform === "win32" ? (process.env.PATHEXT || ".EXE").split(";") : [""];
+  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+    for (const ext of exts) {
+      const file = path.join(dir, name + ext.toLowerCase());
+      try {
+        if (dir && fs.statSync(file).isFile()) return file;
+      } catch {
+        // no está aquí
+      }
+    }
+  }
+  return null;
+}