testdossier 0.2.3 → 0.3.0

package/README.md

@@ -8,7 +8,7 @@ Upload a completed test report from a developer laptop, test machine, or CI
 job. Run these commands in the project containing your automated tests:
 
 1. Install the latest CLI in the project. To pin a release instead, replace
-   `@latest` with an exact version such as `@0.2.3`:
+   `@latest` with an exact version such as `@0.3.0`:
 
 ```bash
 npm install --save-dev testdossier@latest
@@ -70,9 +70,11 @@ requires Node.js 18 or newer.
 
 ## Why this is intentionally small
 
-The uploader does one thing: read a completed report and make an outbound HTTPS
-request to TestDossier. It does not run tests, accept remote commands, install a
-background service, watch files, or keep a process running.
+The upload path does one thing: read a completed report and make an outbound
+HTTPS request to TestDossier. It does not run tests, accept remote commands,
+install a background service, watch files, or keep a process running. The
+optional `setup cypress` command performs one fixed local write using the
+template already present in the installed package.
 
 The access token is read from the first available source: an explicitly passed
 `--env-file`, the `TD_CI_TOKEN` process environment, then `.env.testdossier` in
@@ -108,6 +110,43 @@ creates an ambiguous shape, pass `--format playwright`, `--format cypress`,
 `--format cucumber`, `--format junit`, or `--format generic`. The `upload`
 word may be omitted: `npx testdossier playwright-results.json` works too.
 
+For Playwright, configure `screenshot: 'only-on-failure'`. During upload the
+CLI reads one screenshot from each test whose final attempt failed and sends it
+through TestDossier's durable image path. Screenshots from passing tests and
+earlier retries are omitted, while video/trace files remain link-first. Every
+CI run stays immutable; identical images are hash-deduplicated in storage.
+
+### Generate the Cypress helper from the installed package
+
+Cypress's normal command does not write its complete Module API result to a
+file, and local screenshot paths are not enough once the runner disappears.
+After installing TestDossier in the client repository, generate the helper
+from that installed, lockfile-pinned version:
+
+```bash
+npx testdossier setup cypress
+```
+
+The command creates only `scripts/dossier-cypress.mjs`, prints its SHA-256
+digest, and never downloads code or contacts TestDossier. It is safe to run
+again when the file still matches. If the file has been edited or came from a
+different template, setup stops and leaves it untouched—there is deliberately
+no force-overwrite option.
+
+Review the generated file before committing it, then add a project script:
+
+```json
+{
+  "scripts": {
+    "cy:testdossier": "node scripts/dossier-cypress.mjs --output cypress-results.json"
+  }
+}
+```
+
+Run `npm run cy:testdossier`, then upload `cypress-results.json`. The helper
+uses the client project's own Cypress dependency; TestDossier does not bundle
+or silently install Cypress.
+
 ## Local setup
 
 For repeat use, install and pin the CLI in the test repository so its source
@@ -118,7 +157,7 @@ npm install --save-dev testdossier@latest
 npx testdossier init
 ```
 
-Use `npm install --save-dev testdossier@0.2.3` when the repository should pin
+Use `npm install --save-dev testdossier@0.3.0` when the repository should pin
 that exact release. In either case, subsequent commands remain
 `npx testdossier ...`; the version selector belongs only to installation.
 

package/assets/mark.svg

@@ -1,5 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="TestDossier">
   <title>TestDossier</title>
   <path fill="#006b61" fill-rule="evenodd" d="M20 6h14c17 0 28 10 28 26S51 58 34 58H20V6Zm14 14v24c9 0 14-4 14-12s-5-12-14-12Z"/>
-  <path fill="#006b61" d="M2 6h32v10H2z"/>
+  <path fill="#006b61" d="M2 6h32v14H2z"/>
 </svg>

package/lib/testdossier.mjs

@@ -1,14 +1,20 @@
 import { createHash, randomUUID } from "node:crypto";
-import { readFile, stat, writeFile } from "node:fs/promises";
-import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
-export const VERSION = "0.2.3";
+export const VERSION = "0.3.0";
 const DEFAULT_ORIGIN = "https://testdossier.com";
 const ENV_FILE_NAME = ".env.testdossier";
 const CONFIG_FILE_NAME = "testdossier.json";
+const CYPRESS_HELPER_PATH = "scripts/dossier-cypress.mjs";
+const CYPRESS_HELPER_TEMPLATE_URL = new URL("../templates/dossier-cypress.mjs", import.meta.url);
 const TOKEN_PLACEHOLDER = "replace_with_your_td_token";
 const REPORT_FORMATS = new Set(["cypress", "playwright", "cucumber", "junit", "generic"]);
 const MAX_REPORT_BYTES = 25 * 1024 * 1024;
+// Keep encoded bodies below both the endpoint's 25 MiB request ceiling and
+// its 16 MiB decoded-evidence budget (base64 expands bytes by roughly 4/3).
+const MAX_PAGE_BYTES = 20 * 1024 * 1024;
+const MAX_FAILURE_SCREENSHOT_BYTES = 10 * 1024 * 1024;
 const MAX_TESTS_PER_PAGE = 200;
 const RETRYABLE_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
 const FORMAT_LABELS = {
@@ -130,6 +136,86 @@ export function detectReportFormat(text) {
   return analyzeReport(text).format;
 }
 
+const SCREENSHOT_MIME = new Map([
+  [".png", "image/png"], [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"], [".gif", "image/gif"], [".webp", "image/webp"],
+]);
+
+function isPlaywrightScreenshot(att) {
+  if (!isObject(att)) return false;
+  const contentType = String(att.contentType || "").toLowerCase();
+  const extension = extname(String(att.path || att.name || "")).toLowerCase();
+  return contentType.startsWith("image/") || SCREENSHOT_MIME.has(extension);
+}
+
+function playwrightFinalFailure(test, result) {
+  const status = String(result && result.status || "").toLowerCase();
+  if (status === "timedout" || status === "interrupted") return true;
+  if (status !== "failed") return false;
+  return String(test && test.expectedStatus || "passed").toLowerCase() !== "failed";
+}
+
+/** Promote one screenshot from each final Playwright failure into the inline
+ * transport understood by the ingest endpoint. Earlier-retry screenshots are
+ * deliberately omitted from this upload copy to keep evidence bounded. */
+export async function hydratePlaywrightFailureScreenshots(document, reportPath) {
+  if (!isObject(document) || !Array.isArray(document.suites)) return { inlined: 0, skipped: 0 };
+  let inlined = 0;
+  let skipped = 0;
+
+  const visitSuites = async (suites) => {
+    for (const suite of suites || []) {
+      for (const spec of Array.isArray(suite && suite.specs) ? suite.specs : []) {
+        for (const test of Array.isArray(spec && spec.tests) ? spec.tests : []) {
+          const results = Array.isArray(test && test.results) ? test.results : [];
+          const ordered = results.slice().sort((a, b) => Number(a.retry || 0) - Number(b.retry || 0));
+          const finalResult = ordered[ordered.length - 1];
+          const finalAttachments = Array.isArray(finalResult && finalResult.attachments) ? finalResult.attachments : [];
+          const selected = finalResult && playwrightFinalFailure(test, finalResult)
+            ? finalAttachments.find((att) => isPlaywrightScreenshot(att) && typeof att.path === "string" && att.path.trim()) || null
+            : null;
+
+          for (const result of results) {
+            if (!Array.isArray(result.attachments)) continue;
+            const next = [];
+            for (const att of result.attachments) {
+              if (!isPlaywrightScreenshot(att)) { next.push(att); continue; }
+              if (att !== selected) continue;
+              const rawPath = String(att.path || "").trim();
+              const absolutePath = isAbsolute(rawPath) ? rawPath : resolve(dirname(reportPath), rawPath);
+              const mime = SCREENSHOT_MIME.get(extname(absolutePath).toLowerCase())
+                || (/^image\/(png|jpeg|gif|webp)$/i.test(String(att.contentType || "")) ? String(att.contentType).toLowerCase() : "");
+              try {
+                const info = await stat(absolutePath);
+                if (!mime || !info.isFile() || info.size <= 0 || info.size > MAX_FAILURE_SCREENSHOT_BYTES) {
+                  skipped += 1;
+                  continue;
+                }
+                const bytes = await readFile(absolutePath);
+                next.push({
+                  ...att,
+                  name: att.name || basename(absolutePath),
+                  contentType: mime,
+                  data_url: `data:${mime};base64,${bytes.toString("base64")}`,
+                  path: undefined,
+                });
+                inlined += 1;
+              } catch {
+                skipped += 1;
+              }
+            }
+            result.attachments = next;
+          }
+        }
+      }
+      if (Array.isArray(suite && suite.suites)) await visitSuites(suite.suites);
+    }
+  };
+
+  await visitSuites(document.suites);
+  return { inlined, skipped };
+}
+
 function playwrightTestNodes(suites, found = []) {
   for (const suite of Array.isArray(suites) ? suites : []) {
     if (!suite || typeof suite !== "object") continue;
@@ -160,6 +246,175 @@ function selectedPlaywrightSuite(suite, selectedTests) {
   return next.specs.length > 0 || next.suites.length > 0 ? next : null;
 }
 
+async function inspectPlaywrightFailureScreenshot(test, reportPath) {
+  const results = Array.isArray(test && test.results) ? test.results : [];
+  const ordered = results.slice().sort((a, b) => Number(a.retry || 0) - Number(b.retry || 0));
+  const finalResult = ordered[ordered.length - 1];
+  const attachments = Array.isArray(finalResult && finalResult.attachments) ? finalResult.attachments : [];
+  const selected = finalResult && playwrightFinalFailure(test, finalResult)
+    ? attachments.find((att) => isPlaywrightScreenshot(att) && typeof att.path === "string" && att.path.trim()) || null
+    : null;
+  if (!selected) return { selected: null, skipped: 0, dataUrlLength: 0 };
+
+  const rawPath = String(selected.path || "").trim();
+  const absolutePath = isAbsolute(rawPath) ? rawPath : resolve(dirname(reportPath), rawPath);
+  const mime = SCREENSHOT_MIME.get(extname(absolutePath).toLowerCase())
+    || (/^image\/(png|jpeg|gif|webp)$/i.test(String(selected.contentType || "")) ? String(selected.contentType).toLowerCase() : "");
+  try {
+    const info = await stat(absolutePath);
+    if (!mime || !info.isFile() || info.size <= 0 || info.size > MAX_FAILURE_SCREENSHOT_BYTES) {
+      return { selected, skipped: 1, dataUrlLength: 0 };
+    }
+    const prefix = `data:${mime};base64,`;
+    return {
+      selected,
+      absolutePath,
+      mime,
+      size: info.size,
+      skipped: 0,
+      dataUrlLength: prefix.length + 4 * Math.ceil(info.size / 3),
+    };
+  } catch {
+    return { selected, skipped: 1, dataUrlLength: 0 };
+  }
+}
+
+function playwrightUploadTest(test, evidence, dataUrl, estimate) {
+  return {
+    ...test,
+    results: (Array.isArray(test && test.results) ? test.results : []).map((result) => ({
+      ...result,
+      attachments: (Array.isArray(result && result.attachments) ? result.attachments : []).flatMap((att) => {
+        if (!isPlaywrightScreenshot(att)) return [att];
+        if (att !== evidence.selected || !evidence.absolutePath || !evidence.mime) return [];
+        if (!estimate && typeof dataUrl !== "string") return [];
+        return [{
+          ...att,
+          name: att.name || basename(evidence.absolutePath),
+          contentType: evidence.mime,
+          data_url: estimate ? "" : dataUrl,
+          path: undefined,
+        }];
+      }),
+    })),
+  };
+}
+
+function playwrightUploadPageBody(document, tests, evidenceByTest, dataUrls = null, estimate = false) {
+  const selected = new Set(tests);
+  const replacements = new Map(tests.map((test) => [
+    test,
+    playwrightUploadTest(test, evidenceByTest.get(test), dataUrls && dataUrls.get(test), estimate),
+  ]));
+  const selectSuite = (suite) => {
+    if (!suite || typeof suite !== "object") return null;
+    const next = { ...suite };
+    next.specs = (Array.isArray(suite.specs) ? suite.specs : [])
+      .filter((spec) => spec && typeof spec === "object")
+      .map((spec) => ({
+        ...spec,
+        tests: (Array.isArray(spec.tests) ? spec.tests : [])
+          .filter((test) => selected.has(test))
+          .map((test) => replacements.get(test)),
+      }))
+      .filter((spec) => spec.tests.length > 0);
+    next.suites = (Array.isArray(suite.suites) ? suite.suites : [])
+      .map(selectSuite)
+      .filter(Boolean);
+    return next.specs.length > 0 || next.suites.length > 0 ? next : null;
+  };
+  const suites = document.suites.map(selectSuite).filter(Boolean);
+  return Buffer.from(JSON.stringify({ ...document, suites }));
+}
+
+function estimatedPlaywrightUploadPageBytes(document, tests, evidenceByTest) {
+  const placeholder = playwrightUploadPageBody(document, tests, evidenceByTest, null, true);
+  return placeholder.byteLength + tests.reduce(
+    (sum, test) => sum + Number(evidenceByTest.get(test)?.dataUrlLength || 0),
+    0,
+  );
+}
+
+/** Plan Playwright pages using screenshot stat metadata only. No image bytes or
+ * base64 strings are retained here, so a failure storm cannot exhaust the Node
+ * heap before the first request is sent. */
+export async function planPlaywrightUploadPages(
+  document,
+  reportPath,
+  maxTests = MAX_TESTS_PER_PAGE,
+  maxPageBytes = MAX_PAGE_BYTES,
+) {
+  const tests = playwrightTestNodes(document.suites);
+  const evidenceByTest = new Map();
+  let inlined = 0;
+  let skipped = 0;
+  for (const test of tests) {
+    const evidence = await inspectPlaywrightFailureScreenshot(test, reportPath);
+    evidenceByTest.set(test, evidence);
+    if (evidence.dataUrlLength > 0) inlined += 1;
+    skipped += evidence.skipped;
+  }
+
+  const pages = [];
+  let current = [];
+  const pushCurrent = () => {
+    if (!current.length) return;
+    pages.push({
+      tests: current.slice(),
+      testCount: current.length,
+      estimatedBytes: estimatedPlaywrightUploadPageBytes(document, current, evidenceByTest),
+      maxPageBytes,
+    });
+  };
+  for (const test of tests) {
+    const candidate = [...current, test];
+    const estimatedBytes = estimatedPlaywrightUploadPageBytes(document, candidate, evidenceByTest);
+    if (candidate.length > maxTests || estimatedBytes > maxPageBytes) {
+      if (current.length === 0) {
+        throw new CliError("one Playwright test plus its failure screenshot exceeds the 20 MiB page limit; reduce the screenshot size.");
+      }
+      pushCurrent();
+      current = [test];
+      if (estimatedPlaywrightUploadPageBytes(document, current, evidenceByTest) > maxPageBytes) {
+        throw new CliError("one Playwright test plus its failure screenshot exceeds the 20 MiB page limit; reduce the screenshot size.");
+      }
+    } else {
+      current = candidate;
+    }
+  }
+  pushCurrent();
+  if (pages.length === 0) {
+    pages.push({ tests: [], testCount: 0, estimatedBytes: playwrightUploadPageBody(document, [], evidenceByTest).byteLength, maxPageBytes });
+  }
+  return { pages, evidenceByTest, inlined, skipped };
+}
+
+/** Read and encode only one already-planned page. The caller uploads it before
+ * materializing the next page, bounding live screenshot data to one request. */
+export async function materializePlaywrightUploadPage(document, page, evidenceByTest) {
+  const dataUrls = new Map();
+  let skipped = 0;
+  for (const test of page.tests) {
+    const evidence = evidenceByTest.get(test);
+    if (!evidence?.absolutePath || !evidence.mime) continue;
+    try {
+      const bytes = await readFile(evidence.absolutePath);
+      if (bytes.length <= 0 || bytes.length > MAX_FAILURE_SCREENSHOT_BYTES) {
+        skipped += 1;
+        continue;
+      }
+      dataUrls.set(test, `data:${evidence.mime};base64,${bytes.toString("base64")}`);
+    } catch {
+      skipped += 1;
+    }
+  }
+  const body = playwrightUploadPageBody(document, page.tests, evidenceByTest, dataUrls, false);
+  if (body.byteLength > page.maxPageBytes) {
+    throw new CliError("one Playwright page exceeds the 20 MiB page limit because its screenshot changed during upload; reduce the screenshot size.");
+  }
+  return { body, skipped };
+}
+
 // Counts <testcase> elements the way the server's parser does: real tags
 // only, so a failure message inside CDATA that happens to contain
 // "<testcase" is not counted.
@@ -231,7 +486,7 @@ function selectedCypressRun(run, selectedTests) {
   };
 }
 
-export function splitReportPages(format, report, maxTests = MAX_TESTS_PER_PAGE, document = null) {
+export function splitReportPages(format, report, maxTests = MAX_TESTS_PER_PAGE, document = null, maxPageBytes = MAX_PAGE_BYTES) {
   if (!Number.isInteger(maxTests) || maxTests < 1 || maxTests > MAX_TESTS_PER_PAGE) {
     throw new CliError(`page size must be an integer from 1 to ${MAX_TESTS_PER_PAGE}.`);
   }
@@ -259,14 +514,37 @@ export function splitReportPages(format, report, maxTests = MAX_TESTS_PER_PAGE,
 
   if (format === "playwright") {
     const tests = playwrightTestNodes(doc.suites);
-    if (tests.length <= maxTests) return [{ body: report, tests: tests.length }];
-    return pagedSlices(tests, maxTests).map((slice) => {
+    const pageBody = (slice) => {
       const selected = new Set(slice);
       const suites = doc.suites
         .map((suite) => selectedPlaywrightSuite(suite, selected))
         .filter(Boolean);
-      return { body: Buffer.from(JSON.stringify({ ...doc, suites })), tests: slice.length };
-    });
+      return Buffer.from(JSON.stringify({ ...doc, suites }));
+    };
+    if (tests.length <= maxTests && report.byteLength <= maxPageBytes) {
+      return [{ body: report, tests: tests.length }];
+    }
+    const pages = [];
+    let current = [];
+    for (const test of tests) {
+      const candidate = [...current, test];
+      const candidateBody = pageBody(candidate);
+      if (candidate.length > maxTests || candidateBody.byteLength > maxPageBytes) {
+        if (current.length === 0) {
+          throw new CliError("one Playwright test plus its failure screenshot exceeds the 20 MiB page limit; reduce the screenshot size.");
+        }
+        const body = pageBody(current);
+        pages.push({ body, tests: current.length });
+        current = [test];
+        if (pageBody(current).byteLength > maxPageBytes) {
+          throw new CliError("one Playwright test plus its failure screenshot exceeds the 20 MiB page limit; reduce the screenshot size.");
+        }
+      } else {
+        current = candidate;
+      }
+    }
+    if (current.length > 0) pages.push({ body: pageBody(current), tests: current.length });
+    return pages;
   }
 
   if (format === "cypress") {
@@ -519,6 +797,57 @@ async function runInit({ cwd, stdout }) {
   return 0;
 }
 
+async function runCypressSetup({ cwd, stdout }) {
+  let template;
+  try {
+    template = await readFile(CYPRESS_HELPER_TEMPLATE_URL, "utf8");
+  } catch (error) {
+    throw new CliError(`installed Cypress helper template is unavailable: ${error && error.message}`);
+  }
+  const targetPath = join(cwd, "scripts", "dossier-cypress.mjs");
+  const digest = createHash("sha256").update(template).digest("hex");
+
+  const describeExisting = async () => {
+    let existing;
+    try {
+      existing = await readFile(targetPath, "utf8");
+    } catch (error) {
+      if (error && error.code === "ENOENT") return false;
+      throw new CliError(
+        `${CYPRESS_HELPER_PATH} already exists but could not be read; left unchanged: ${error && error.message}`,
+      );
+    }
+    if (existing !== template) {
+      throw new CliError(
+        `${CYPRESS_HELPER_PATH} already exists and differs from the testdossier ${VERSION} template; ` +
+        "left unchanged. Review or remove it before trying again.",
+      );
+    }
+    stdout(`${CYPRESS_HELPER_PATH} already matches testdossier ${VERSION}; left unchanged.`);
+    stdout(`SHA-256 ${digest}`);
+    return true;
+  };
+
+  if (await describeExisting()) return 0;
+  try {
+    await mkdir(dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, template, { flag: "wx", mode: 0o644 });
+  } catch (error) {
+    // Another process may have created the fixed target after our first read.
+    // Re-check it rather than overwriting or reporting a false failure.
+    if (error && error.code === "EEXIST" && await describeExisting()) return 0;
+    throw new CliError(`could not create ${CYPRESS_HELPER_PATH}: ${error && error.message}`);
+  }
+
+  stdout(`Created ${CYPRESS_HELPER_PATH} from installed testdossier ${VERSION}.`);
+  stdout(`SHA-256 ${digest}`);
+  stdout([
+    "Review the generated file before committing it, then add this script to package.json:",
+    '  "cy:testdossier": "node scripts/dossier-cypress.mjs --output cypress-results.json"',
+  ].join("\n"));
+  return 0;
+}
+
 function normalizedHeader(value, name) {
   if (value == null || value === "") return "";
   const normalized = String(value);
@@ -805,6 +1134,7 @@ function helpText() {
 
 Usage:
   testdossier init                  One-time setup: create ${ENV_FILE_NAME} and gitignore it
+  testdossier setup cypress         Create a reviewable Cypress helper without overwriting files
   testdossier verify                Check the token and destination without sending a report
   testdossier upload <report-file> [options]
   testdossier <report-file> [options]    "upload" may be omitted
@@ -845,6 +1175,7 @@ Large reports:
 
 Examples:
   npx testdossier init
+  npx testdossier setup cypress
   npx testdossier verify
   npx testdossier upload playwright-results.json
   npx testdossier upload junit-results.xml --build abc123
@@ -909,6 +1240,12 @@ export async function runCli(
       if (args.length > 1) throw new CliError("init takes no arguments.");
       return await runInit({ cwd, stdout });
     }
+    if (args[0] === "setup") {
+      if (args.length !== 2 || args[1] !== "cypress") {
+        throw new CliError("setup requires exactly one supported target: cypress.");
+      }
+      return await runCypressSetup({ cwd, stdout });
+    }
     if (args[0] === "verify") {
       const options = parseUploadArgs(args.slice(1));
       if (options.help) {
@@ -981,13 +1318,26 @@ export async function runCli(
     const reportText = report.toString("utf8");
     const requestedFormat = options.format !== "auto" ? options.format : (config && config.format) || "auto";
     const { format, document } = analyzeReport(reportText, requestedFormat);
-    const pages = splitReportPages(format, report, MAX_TESTS_PER_PAGE, document);
-    const testCount = pages.reduce((sum, page) => sum + page.tests, 0);
+    let playwrightUpload = null;
+    let pages;
+    if (format === "playwright" && document) {
+      playwrightUpload = await planPlaywrightUploadPages(document, options.reportPath);
+      pages = playwrightUpload.pages;
+      if (playwrightUpload.inlined || playwrightUpload.skipped) {
+        stdout(`Prepared ${playwrightUpload.inlined} failure screenshot${playwrightUpload.inlined === 1 ? "" : "s"} for durable CI evidence${playwrightUpload.skipped ? ` (${playwrightUpload.skipped} skipped)` : ""}.`);
+      }
+    } else {
+      pages = splitReportPages(format, report, MAX_TESTS_PER_PAGE, document);
+    }
+    const testCount = pages.reduce((sum, page) => sum + (page.testCount ?? page.tests), 0);
+    const validatedBytes = playwrightUpload
+      ? pages.reduce((sum, page) => sum + page.estimatedBytes, 0)
+      : report.byteLength;
 
     const endpoint = normalizeEndpoint(options.url || env.TD_URL || (config && config.url) || DEFAULT_ORIGIN);
     const destination = new URL(endpoint).origin;
     stdout(
-      `Validated ${FORMAT_LABELS[format]} (${report.byteLength} bytes, ${testCount} tests` +
+      `Validated ${FORMAT_LABELS[format]} (${validatedBytes} bytes, ${testCount} tests` +
       `${pages.length > 1 ? ` across ${pages.length} pages` : ""}).`,
     );
     if (options.dryRun) {
@@ -1014,7 +1364,7 @@ export async function runCli(
 
     if (pages.length > 1) {
       stdout(
-        `Uploading ${pages.reduce((sum, page) => sum + (page.tests || 0), 0)} tests in ` +
+        `Uploading ${pages.reduce((sum, page) => sum + (page.testCount ?? page.tests ?? 0), 0)} tests in ` +
         `${pages.length} pages (run ${metadata.runId}).`,
       );
     }
@@ -1026,6 +1376,12 @@ export async function runCli(
     const pageResults = [];
     for (let index = 0; index < pages.length; index += 1) {
       const page = pages[index];
+      const materialized = playwrightUpload
+        ? await materializePlaywrightUploadPage(document, page, playwrightUpload.evidenceByTest)
+        : null;
+      if (materialized?.skipped) {
+        stderr(`Warning: ${materialized.skipped} failure screenshot${materialized.skipped === 1 ? " was" : "s were"} no longer readable and were skipped.`);
+      }
       const result = await postWithRetry({
         endpoint,
         headers: {
@@ -1035,14 +1391,14 @@ export async function runCli(
           "X-CI-Page-Index": String(index + 1),
           "X-CI-Page-Count": String(pages.length),
         },
-        body: page.body,
+        body: materialized ? materialized.body : page.body,
         env,
         fetchImpl,
         stderr,
       });
       pageResults.push(result);
       if (pages.length > 1) {
-        stdout(`Uploaded page ${index + 1}/${pages.length} (${page.tests} tests).`);
+        stdout(`Uploaded page ${index + 1}/${pages.length} (${page.testCount ?? page.tests} tests).`);
       }
     }
     stdout(`Uploaded ${FORMAT_LABELS[format]} to ${destination} (run ${metadata.runId}).`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdossier",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Upload Playwright, Cypress, Cucumber, JUnit, and JSON test evidence to TestDossier.",
   "license": "MIT",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "bin",
     "lib",
+    "templates",
     "assets",
     "README.md",
     "LICENSE",

package/templates/dossier-cypress.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// TestDossier Cypress runner — zero dependencies beyond the project's Cypress.
+// Uses Cypress's Module API so the output is the native { runs: [...] } shape
+// accepted by X-CI-Format: cypress. Failure screenshots are embedded as data
+// URLs; /api/ci/ingest uploads them to R2 and stores only durable references.
+
+import cypress from "cypress";
+import { readFileSync, writeFileSync, existsSync, statSync } from "node:fs";
+import { extname, resolve } from "node:path";
+
+const args = process.argv.slice(2);
+const outputFlag = args.indexOf("--output");
+const output = outputFlag >= 0 && args[outputFlag + 1]
+  ? args[outputFlag + 1]
+  : "cypress-results.json";
+const cypressArgs = outputFlag >= 0
+  ? args.filter((_, i) => i !== outputFlag && i !== outputFlag + 1)
+  : args;
+
+const MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+};
+const MAX_SCREENSHOTS = 20;
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+// Base64 adds roughly 33%; keeping raw bytes at 15 MB leaves room under the
+// ingest endpoint's 25 MB request limit for the Cypress result JSON itself.
+const MAX_TOTAL_IMAGE_BYTES = 15 * 1024 * 1024;
+
+const options = {};
+for (let i = 0; i < cypressArgs.length; i += 1) {
+  const arg = cypressArgs[i];
+  if (arg === "--browser" && cypressArgs[i + 1]) options.browser = cypressArgs[++i];
+  else if (arg === "--spec" && cypressArgs[i + 1]) options.spec = cypressArgs[++i];
+  else if (arg === "--config-file" && cypressArgs[i + 1]) options.configFile = cypressArgs[++i];
+  else if (arg === "--component") options.component = true;
+  else if (arg === "--headed") options.headed = true;
+}
+
+let result;
+try {
+  result = await cypress.run(options);
+} catch (error) {
+  console.error("Cypress could not start:", error instanceof Error ? error.message : error);
+  process.exit(2);
+}
+
+if (!result || !Array.isArray(result.runs)) {
+  console.error("Cypress did not return a test-run result:", result?.message || "unknown error");
+  process.exit(2);
+}
+
+let embedded = 0;
+let embeddedBytes = 0;
+let skipped = 0;
+for (const run of result.runs) {
+  for (const screenshot of run.screenshots || []) {
+    const path = resolve(String(screenshot.path || ""));
+    const mime = MIME[extname(path).toLowerCase()];
+    if (!path || !mime || !existsSync(path)) { skipped += 1; continue; }
+    const bytes = statSync(path).size;
+    if (
+      bytes > MAX_IMAGE_BYTES ||
+      embedded >= MAX_SCREENSHOTS ||
+      embeddedBytes + bytes > MAX_TOTAL_IMAGE_BYTES
+    ) {
+      skipped += 1;
+      continue;
+    }
+    screenshot.data_url = `data:${mime};base64,${readFileSync(path).toString("base64")}`;
+    screenshot.content_type = mime;
+    embedded += 1;
+    embeddedBytes += bytes;
+  }
+}
+
+writeFileSync(output, JSON.stringify(result));
+console.log(`Wrote ${output}: ${result.totalTests || 0} test(s), ${embedded} screenshot(s) embedded${skipped ? `, ${skipped} skipped by size/count limits` : ""}.`);
+console.warn("Review CI screenshots for secrets or personal data before sharing them externally.");
+
+const failed = Number(result.totalFailed || 0) || result.runs.reduce(
+  (sum, run) => sum + Number(run?.stats?.failures || 0),
+  0,
+);
+process.exitCode = failed > 0 ? 1 : 0;