kwikqa 0.0.0-stage → 0.1.0

package/dist/cypress-reporter.cjs

@@ -0,0 +1,282 @@
+"use strict";
+// KwikQA's Cypress reporter (KQA-081). A Mocha reporter, loaded by Cypress in its Node process:
+//
+//   reporter: "node_modules/kwikqa/dist/cypress-reporter.cjs"
+//
+// It writes one `kwikqa-test-report` JSON per spec run into `test-results/kwikqa/` (or
+// `reporterOptions.outputDir`, or $KWIKQA_REPORT_DIR), keeping what other Cypress reporters drop:
+// every retry attempt, the full title path, where each test is declared, and each error's code
+// frame and expected/actual values. `npx kwikqa analyze --report test-results/kwikqa` reads it.
+// This file has no dependencies and changes nothing about how tests run.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const SCHEMA = "kwikqa-test-report";
+const SCHEMA_VERSION = "1.0";
+const CAPTURE_TYPE = "application/vnd.kwikqa.capture+json";
+const MAX_SCREENSHOT_FILES = 5000;
+
+function fnv1a(text) {
+  let hash = 0x811c9dc5;
+  for (const byte of new TextEncoder().encode(text)) {
+    hash ^= byte;
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+/** Must match the key cypress-capture.js writes a failure capture under. */
+function captureKey(spec, titlePath, retry) {
+  const slug = String(spec)
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .slice(-60);
+  return `${slug}--${fnv1a(`${spec}\u0000${titlePath.join("\u0000")}`)}--${retry}`;
+}
+
+function text(value) {
+  if (value === undefined) return undefined;
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function convertError(err) {
+  if (err === undefined || err === null) return undefined;
+  const out = { message: String(err.message !== undefined ? err.message : err) };
+  if (err.name) out.name = String(err.name);
+  if (err.stack) out.stack = String(err.stack);
+  const frame = err.codeFrame;
+  if (frame && (frame.relativeFile || frame.originalFile) && frame.line) {
+    out.location = {
+      file: String(frame.relativeFile || frame.originalFile),
+      line: Number(frame.line),
+      column: Number(frame.column || 1),
+    };
+    if (frame.frame) out.snippet = String(frame.frame);
+  }
+  if (err.showDiff !== false && (err.actual !== undefined || err.expected !== undefined)) {
+    out.actual = text(err.actual);
+    out.expected = text(err.expected);
+  }
+  return out;
+}
+
+function titlePathOf(runnable) {
+  if (typeof runnable.titlePath === "function") return runnable.titlePath();
+  const titles = [];
+  for (let current = runnable; current; current = current.parent) {
+    if (current.title) titles.unshift(current.title);
+  }
+  return titles;
+}
+
+function frameworkVersion(cwd) {
+  try {
+    const manifest = require.resolve("cypress/package.json", { paths: [cwd] });
+    return JSON.parse(fs.readFileSync(manifest, "utf8")).version;
+  } catch {
+    return undefined;
+  }
+}
+
+function configFile(cwd) {
+  for (const extension of ["ts", "js", "mjs", "cjs", "mts", "cts"]) {
+    const candidate = path.join(cwd, `cypress.config.${extension}`);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function screenshotIndex(folder) {
+  const found = new Map();
+  let seen = 0;
+  const walk = (directory, depth) => {
+    if (depth > 6 || seen > MAX_SCREENSHOT_FILES) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      seen += 1;
+      const full = path.join(directory, entry.name);
+      if (entry.isDirectory()) walk(full, depth + 1);
+      else if (/\.png$/i.test(entry.name)) {
+        const list = found.get(entry.name) || [];
+        list.push(full);
+        found.set(entry.name, list);
+      }
+    }
+  };
+  walk(folder, 0);
+  return found;
+}
+
+function KwikqaCypressReporter(runner, options) {
+  const settings = options?.reporterOptions || {};
+  const cwd = process.cwd();
+  const outputDir = path.resolve(
+    cwd,
+    process.env.KWIKQA_REPORT_DIR || settings.outputDir || "test-results/kwikqa",
+  );
+  const captureDir = process.env.KWIKQA_CAPTURE_DIR || settings.captureDir;
+  const screenshotsFolder = path.resolve(
+    cwd,
+    process.env.KWIKQA_SCREENSHOTS_DIR || settings.screenshotsFolder || "cypress/screenshots",
+  );
+  const startedAt = new Date();
+  const tests = new Map();
+  const errors = [];
+  const specs = new Set();
+  let currentSpec = "";
+  let interrupted = false;
+
+  const recordFor = (test) => {
+    const titlePath = titlePathOf(test);
+    const details = test.invocationDetails || {};
+    const file = String(details.relativeFile || test.file || currentSpec || "");
+    const key = `${file}\u0000${titlePath.join("\u0000")}`;
+    let entry = tests.get(key);
+    if (!entry) {
+      entry = {
+        file,
+        titlePath,
+        project: "",
+        attempts: [],
+      };
+      if (details.line) {
+        entry.line = Number(details.line);
+        entry.column = Number(details.column || 1);
+      }
+      if (typeof test._timeout === "number") entry.timeout = test._timeout;
+      tests.set(key, entry);
+    }
+    return entry;
+  };
+  const open = (entry, retry) => {
+    const attempt = {
+      status: "interrupted",
+      retry,
+      startTime: new Date().toISOString(),
+      duration: 0,
+      errors: [],
+      attachments: [],
+    };
+    entry.attempts.push(attempt);
+    return attempt;
+  };
+  const current = (entry) => {
+    const last = entry.attempts[entry.attempts.length - 1];
+    return last && last.status === "interrupted" ? last : open(entry, entry.attempts.length);
+  };
+  const close = (entry, status, err, duration) => {
+    const attempt = current(entry);
+    attempt.status = status;
+    attempt.duration =
+      typeof duration === "number" ? duration : Date.now() - Date.parse(attempt.startTime);
+    const converted = convertError(err);
+    if (converted) attempt.errors.push(converted);
+  };
+
+  runner.on("suite", (suite) => {
+    if (suite.root && suite.file) {
+      currentSpec = String(suite.file);
+      specs.add(currentSpec);
+    }
+  });
+  // The test Cypress hands to `retry` is a detached copy without its parent suites, so the
+  // attempt is filed under the test that is running, as `test` announced it.
+  let running;
+  runner.on("test", (test) => {
+    running = recordFor(test);
+    open(running, 0);
+  });
+  runner.on("retry", (test, err) => {
+    const entry =
+      running && running.titlePath[running.titlePath.length - 1] === test.title
+        ? running
+        : recordFor(test);
+    close(entry, "failed", err || test.err, test.duration);
+    open(entry, entry.attempts.length);
+  });
+  runner.on("pass", (test) => close(recordFor(test), "passed", undefined, test.duration));
+  runner.on("pending", (test) => {
+    const entry = recordFor(test);
+    entry.attempts = [{ status: "skipped", retry: 0, duration: 0, errors: [], attachments: [] }];
+  });
+  runner.on("fail", (runnable, err) => {
+    if (runnable && runnable.type === "hook") {
+      const test = runnable.ctx?.currentTest;
+      const hookError = convertError(err) || { message: "hook failed" };
+      hookError.message = `${runnable.title}: ${hookError.message}`;
+      if (test) {
+        const entry = recordFor(test);
+        const attempt = current(entry);
+        attempt.status = "failed";
+        attempt.errors.push(hookError);
+      } else {
+        errors.push(hookError);
+      }
+      return;
+    }
+    if (!runnable) return;
+    const timedOut =
+      runnable.timedOut === true || /^Timeout of \d+ms exceeded/.test(String(err?.message));
+    close(recordFor(runnable), timedOut ? "timedOut" : "failed", err, runnable.duration);
+  });
+  runner.on("end", () => {
+    const shots = screenshotIndex(screenshotsFolder);
+    for (const entry of tests.values()) {
+      for (const attempt of entry.attempts) {
+        if (attempt.status !== "failed" && attempt.status !== "timedOut") continue;
+        const name = `${entry.titlePath.join(" -- ")} (failed)${attempt.retry > 0 ? ` (attempt ${attempt.retry + 1})` : ""}.png`;
+        for (const shot of shots.get(name) || []) {
+          attempt.attachments.push({ name: "screenshot", contentType: "image/png", path: shot });
+        }
+        if (captureDir) {
+          const capture = path.resolve(
+            cwd,
+            captureDir,
+            `${captureKey(entry.file, entry.titlePath, attempt.retry)}.json`,
+          );
+          if (fs.existsSync(capture)) {
+            attempt.attachments.push({
+              name: "kwikqa-capture",
+              contentType: CAPTURE_TYPE,
+              path: capture,
+            });
+          }
+        }
+      }
+      if (entry.attempts.some((attempt) => attempt.status === "interrupted")) interrupted = true;
+    }
+    const version = frameworkVersion(cwd);
+    const config = configFile(cwd);
+    const report = {
+      schema: SCHEMA,
+      schemaVersion: SCHEMA_VERSION,
+      framework: "cypress",
+      ...(version === undefined ? {} : { frameworkVersion: version }),
+      rootDir: cwd,
+      ...(config === undefined ? {} : { configFile: config }),
+      startTime: startedAt.toISOString(),
+      duration: Date.now() - startedAt.getTime(),
+      interrupted,
+      projects: [{ id: "", name: "", retries: 0 }],
+      tests: [...tests.values()],
+      errors,
+    };
+    const specKey = [...specs].sort().join("\u0000") || "run";
+    const fileName = `cypress-${specKey.replace(/[^A-Za-z0-9]+/g, "_").slice(-50)}-${fnv1a(specKey)}.json`;
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(path.join(outputDir, fileName), `${JSON.stringify(report, null, 2)}\n`);
+  });
+}
+
+module.exports = KwikqaCypressReporter;
+module.exports.captureKey = captureKey;

package/dist/cypress-reporter.d.cts

@@ -0,0 +1,20 @@
+import type { EventEmitter } from "node:events";
+
+/** KwikQA's Cypress reporter: `reporter: "node_modules/kwikqa/dist/cypress-reporter.cjs"`. */
+declare function KwikqaCypressReporter(
+  runner: EventEmitter,
+  options?: {
+    readonly reporterOptions?: {
+      readonly outputDir?: string;
+      readonly captureDir?: string;
+      readonly screenshotsFolder?: string;
+    };
+  },
+): void;
+
+declare namespace KwikqaCypressReporter {
+  /** The file name a failure capture of one attempt is written under. */
+  function captureKey(spec: string, titlePath: readonly string[], retry: number): string;
+}
+
+export = KwikqaCypressReporter;