@piwitests/reporter 0.18.1 → 0.19.0

package/README.md

@@ -168,7 +168,7 @@ Then import `test` from your fixtures file in every spec — a spec that imports
 - **Console entries** — `warning`, `error`, and `assert` messages with their source location.
 - **Browser Web Vitals** — TTFB, DOM Interactive, DOMContentLoaded, Load Complete, First Paint, First Contentful Paint — displayed with color-coded thresholds.
 - **ARIA snapshot** — captured automatically when a test fails, shown as failure evidence and fed to the AI diagnosis.
-- **Locator snapshots** — for each acted-on element, its attributes plus ranked alternative locators, stamped with the call site. These power locator healing; when a failing locator matches nothing, a fresh suggestion is attached as a Playwright annotation.
+- **Locator snapshots** — for each element a test proves resolvable (successful actions and passing `expect(locator)` assertions alike), its attributes plus ranked alternative locators, stamped with the call site. These power locator healing; when a failing locator matches nothing, a fresh suggestion is attached as a Playwright annotation.
 
 Capture works for the `page` fixture, `browser.newPage()`, `browser.newContext().newPage()`, and popups. Everything is only collected when `collectPerformanceMetrics` is `true` (the default); locator snapshots can be disabled separately with `captureLocators: false`.
 

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli/gate.ts
+var fs = __toESM(require("fs"));
+
+// ../packages/core/src/gate.ts
+function formatGateResult(result) {
+  const { facts } = result;
+  const lines = [
+    result.passed ? `\u2714 Piwi gate passed \u2014 ${facts.projectName} run #${facts.runId}` : `\u2716 Piwi gate failed \u2014 ${facts.projectName} run #${facts.runId}`,
+    `  ${facts.totalTests} tests, ${facts.failedTests} failed, ${facts.newRegressions} new, ${facts.newFlaky} newly flaky`
+  ];
+  if (facts.quarantinedFailures > 0) {
+    lines.push(
+      `  ${facts.quarantinedFailures} failing ${facts.quarantinedFailures === 1 ? "test is" : "tests are"} quarantined and did not count`
+    );
+  }
+  for (const violation of result.violations) lines.push(`  \u2716 ${violation.message}`);
+  lines.push(`  ${facts.runUrl}`);
+  return lines.join("\n");
+}
+
+// src/cli/gate.ts
+var EXIT_OK = 0;
+var EXIT_VIOLATED = 1;
+var EXIT_ERROR = 2;
+var USAGE = `
+piwi gate \u2014 fail a CI job on the dashboard's analysis of a run
+
+Usage:
+  npx piwi gate [options]
+
+Where the run comes from (first match wins):
+  --run-id <id>            Run id to evaluate
+  --from-file <path>       Read runId from the reporter's output JSON
+  PIWI_OUTPUT_FILE         Same, from the environment
+  (default)                ./piwi-run.json, if it exists
+
+Connection:
+  --server-url <url>       Dashboard URL      (env PIWI_DASHBOARD_URL)
+  --api-key <key>          API key            (env PIWI_API_KEY)
+
+Policy (at least one is required):
+  --require-tag <tags>     Comma-separated; every test carrying the tag must pass
+  --max-failed <n>         Fail when more than n tests failed
+  --max-new-regressions <n>  Fail when more than n tests newly started failing
+  --max-new-flaky <n>      Fail when more than n tests newly became flaky
+  --max-quarantined <n>    Fail when more than n tests are quarantined
+  --fail-on-new-cluster    Fail when this run introduced a new failure cluster
+
+Other:
+  --json                   Print the raw result as JSON instead of a summary
+  -h, --help               Show this help
+
+Exit codes: 0 satisfied, 1 violated, 2 could not evaluate.
+`.trim();
+function readOption(argv, name) {
+  const withEquals = argv.find((arg) => arg.startsWith(`${name}=`));
+  if (withEquals) return withEquals.slice(name.length + 1);
+  const index = argv.indexOf(name);
+  if (index === -1) return void 0;
+  const value = argv[index + 1];
+  return value && !value.startsWith("--") ? value : void 0;
+}
+function readCount(argv, name) {
+  const raw = readOption(argv, name);
+  if (raw === void 0) return void 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) throw new Error(`${name} expects a non-negative number, got "${raw}"`);
+  return Math.floor(n);
+}
+function readRunIdFromFile(path) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path, "utf-8"));
+    const runId = Number(parsed.runId);
+    return Number.isFinite(runId) && runId > 0 ? runId : null;
+  } catch {
+    return null;
+  }
+}
+function parseGateArgs(argv, env) {
+  const serverUrl = (readOption(argv, "--server-url") ?? env.PIWI_DASHBOARD_URL ?? "").replace(/\/$/, "");
+  if (!serverUrl) throw new Error("No dashboard URL \u2014 pass --server-url or set PIWI_DASHBOARD_URL");
+  let runId = Number(readOption(argv, "--run-id") ?? NaN);
+  if (!Number.isFinite(runId) || runId <= 0) {
+    const candidate = readOption(argv, "--from-file") ?? env.PIWI_OUTPUT_FILE ?? "piwi-run.json";
+    runId = readRunIdFromFile(candidate) ?? NaN;
+  }
+  if (!Number.isFinite(runId) || runId <= 0) {
+    throw new Error(
+      "No run to evaluate \u2014 pass --run-id, or set PIWI_OUTPUT_FILE so the reporter records the run it submitted"
+    );
+  }
+  const requireTags = (readOption(argv, "--require-tag") ?? "").split(",").map((tag) => tag.trim().replace(/^@+/, "")).filter(Boolean);
+  const policy = {
+    requireTags,
+    maxFailed: readCount(argv, "--max-failed"),
+    maxNewRegressions: readCount(argv, "--max-new-regressions"),
+    maxNewFlaky: readCount(argv, "--max-new-flaky"),
+    maxQuarantined: readCount(argv, "--max-quarantined"),
+    failOnNewCluster: argv.includes("--fail-on-new-cluster")
+  };
+  return { serverUrl, apiKey: readOption(argv, "--api-key") ?? env.PIWI_API_KEY ?? null, runId, policy };
+}
+async function requestGate(args) {
+  const headers = { "Content-Type": "application/json" };
+  if (args.apiKey) headers["X-API-Key"] = args.apiKey;
+  const res = await fetch(`${args.serverUrl}/api/test-runs/${args.runId}/gate`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(args.policy)
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.message || `Dashboard returned ${res.status} evaluating the gate`);
+  }
+  return await res.json();
+}
+async function runGate(argv, env = process.env) {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    console.log(USAGE);
+    return EXIT_OK;
+  }
+  let args;
+  try {
+    args = parseGateArgs(argv, env);
+  } catch (e) {
+    console.error(`piwi gate: ${e.message}
+`);
+    console.error(USAGE);
+    return EXIT_ERROR;
+  }
+  let result;
+  try {
+    result = await requestGate(args);
+  } catch (e) {
+    console.error(`piwi gate: ${e.message}`);
+    return EXIT_ERROR;
+  }
+  if (argv.includes("--json")) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatGateResult(result));
+  }
+  return result.passed ? EXIT_OK : EXIT_VIOLATED;
+}
+
+// src/cli/index.ts
+var USAGE2 = `
+piwi \u2014 companion commands for the Piwi Dashboard reporter
+
+Usage:
+  npx piwi <command> [options]
+
+Commands:
+  gate    Fail a CI job on the dashboard's analysis of a run
+
+Run \`npx piwi gate --help\` for that command's options.
+`.trim();
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  switch (command) {
+    case "gate":
+      return runGate(rest);
+    case void 0:
+    case "-h":
+    case "--help":
+      console.log(USAGE2);
+      return 0;
+    default:
+      console.error(`piwi: unknown command "${command}"
+`);
+      console.error(USAGE2);
+      return 2;
+  }
+}
+main().then((code) => {
+  process.exitCode = code;
+}).catch((e) => {
+  console.error(`piwi: ${e.message}`);
+  process.exitCode = 2;
+});

package/dist/global-setup-module.js

@@ -35,7 +35,7 @@ __export(global_setup_module_exports, {
 module.exports = __toCommonJS(global_setup_module_exports);
 
 // src/public/global-setup.ts
-var path2 = __toESM(require("path"));
+var path3 = __toESM(require("path"));
 
 // src/internal/support/errors.ts
 function errorMessage(error) {
@@ -44,7 +44,27 @@ function errorMessage(error) {
 }
 
 // src/public/global-setup.ts
-var fs2 = __toESM(require("fs"));
+var fs3 = __toESM(require("fs"));
+
+// src/internal/config/desktop.ts
+var fs = __toESM(require("fs"));
+var os = __toESM(require("os"));
+var path = __toESM(require("path"));
+function defaultDesktopConfigPath() {
+  return path.join(os.homedir(), ".piwi", "desktop.json");
+}
+function readDesktopConfig(filePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    const url = parsed?.url;
+    const token = parsed?.token;
+    if (typeof url !== "string" || !url) return null;
+    if (typeof token !== "string" || !token) return null;
+    return { url, token };
+  } catch {
+    return null;
+  }
+}
 
 // src/internal/config/env.ts
 var DEFAULTS = {
@@ -89,6 +109,7 @@ var PIWI_ENV_KEYS = {
   pickLocatorOnFailure: "PIWI_PICK_LOCATOR_ON_FAIL",
   outputFile: "PIWI_OUTPUT_FILE"
 };
+var PIWI_DESKTOP_CONFIG_ENV = "PIWI_DESKTOP_CONFIG";
 function readBool(val) {
   if (val === void 0) return void 0;
   return val === "true";
@@ -115,6 +136,7 @@ var ENV_FALLBACK_SPECS = [
   { option: "pickLocatorOnFailure", env: PIWI_ENV_KEYS.pickLocatorOnFailure, kind: "bool" },
   { option: "outputFile", env: PIWI_ENV_KEYS.outputFile, kind: "string" }
 ];
+var desktopDiscovered = false;
 function resolveOptions(raw) {
   const env = process.env;
   const mergedRaw = { ...raw };
@@ -127,6 +149,17 @@ function resolveOptions(raw) {
       mergedRaw[spec.option] = spec.kind === "number" ? Number(value) : value;
     }
   }
+  desktopDiscovered = false;
+  const serverUrlUnset = mergedRaw.serverUrl === void 0;
+  const apiKeyUnset = mergedRaw.apiKey === void 0 || mergedRaw.apiKey === null;
+  if (serverUrlUnset && apiKeyUnset) {
+    const desktop = readDesktopConfig(env[PIWI_DESKTOP_CONFIG_ENV] || defaultDesktopConfigPath());
+    if (desktop) {
+      mergedRaw.serverUrl = desktop.url;
+      mergedRaw.apiKey = desktop.token;
+      desktopDiscovered = true;
+    }
+  }
   const opts = { ...DEFAULTS, ...mergedRaw };
   if (env[PIWI_ENV_KEYS.verbose] !== void 0) opts.verbose = env[PIWI_ENV_KEYS.verbose] === "true";
   return opts;
@@ -318,12 +351,12 @@ var HttpClient = class {
 
 // src/internal/support/instance-id.ts
 var crypto = __toESM(require("crypto"));
-var os = __toESM(require("os"));
+var os2 = __toESM(require("os"));
 function hashForProject(projectName) {
   return crypto.createHash("sha1").update(projectName).digest("hex").slice(0, 16);
 }
 function computeInstanceId(projectName, runLabel) {
-  const seed = runLabel ? `${projectName}|${runLabel}` : `${os.hostname()}|${projectName}`;
+  const seed = runLabel ? `${projectName}|${runLabel}` : `${os2.hostname()}|${projectName}`;
   return crypto.createHash("sha256").update(seed).digest("hex").slice(0, 16);
 }
 
@@ -346,24 +379,33 @@ function detectCiRunLabel() {
 }
 
 // src/internal/support/setup-file.ts
-var path = __toESM(require("path"));
-var os2 = __toESM(require("os"));
-var fs = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+var os3 = __toESM(require("os"));
+var fs2 = __toESM(require("fs"));
 function getSetupFilePath(projectName) {
-  return path.join(os2.tmpdir(), `piwi-dashboard-setup-${hashForProject(projectName)}.json`);
+  return path2.join(os3.tmpdir(), `piwi-dashboard-setup-${hashForProject(projectName)}.json`);
+}
+
+// src/internal/support/run-mode.ts
+var PW_UI_FLAGS = ["--ui", "--ui-host", "--ui-port"];
+function isUiMode(argv = process.argv) {
+  const args = argv.slice(2);
+  const testIdx = args.indexOf("test");
+  const rest = testIdx >= 0 ? args.slice(testIdx + 1) : args;
+  return rest.some((tok) => PW_UI_FLAGS.some((flag) => tok === flag || tok.startsWith(`${flag}=`)));
 }
 
 // src/public/global-setup.ts
 function createGlobalSetup(options, userSetup) {
   return async function globalSetupFn(config) {
-    const piwiReporterPath = path2.resolve(__dirname, "./index.js");
+    const piwiReporterPath = path3.resolve(__dirname, "./index.js");
     let inlineReporterOptions = {};
     if (Array.isArray(config?.reporter)) {
       for (const r of config.reporter) {
         if (!Array.isArray(r) || typeof r[0] !== "string") continue;
         const isPiwi = r[0].toLowerCase().includes("piwi") || (() => {
           try {
-            return path2.resolve(require.resolve(r[0])) === piwiReporterPath;
+            return path3.resolve(require.resolve(r[0])) === piwiReporterPath;
           } catch {
             return false;
           }
@@ -376,6 +418,11 @@ function createGlobalSetup(options, userSetup) {
     }
     const opts = resolveOptions({ ...inlineReporterOptions, ...options });
     const logger = new Logger(opts.verbose ?? false);
+    if (isUiMode()) {
+      logger.debug("UI mode detected \u2014 skipping run registration.");
+      if (userSetup) return userSetup(config);
+      return;
+    }
     if (opts.enabled === false || !opts.serverUrl) {
       logger.info("Not enabled \u2014 set PIWI_DASHBOARD_URL or serverUrl to enable.");
       if (userSetup) return userSetup(config);
@@ -385,7 +432,7 @@ function createGlobalSetup(options, userSetup) {
       if (!Array.isArray(r) || typeof r[0] !== "string") return false;
       if (r[0].toLowerCase().includes("piwi")) return true;
       try {
-        return path2.resolve(require.resolve(r[0])) === piwiReporterPath;
+        return path3.resolve(require.resolve(r[0])) === piwiReporterPath;
       } catch {
         return false;
       }
@@ -417,7 +464,7 @@ function createGlobalSetup(options, userSetup) {
         auth
       );
       if (response?.runId && response?.setupToken) {
-        fs2.writeFileSync(
+        fs3.writeFileSync(
           getSetupFilePath(opts.projectName),
           JSON.stringify({
             runId: response.runId,

package/dist/index.d.ts

@@ -3,8 +3,14 @@ import { PlaywrightTestConfig } from '@playwright/test';
 export { PlaywrightTestConfig } from '@playwright/test';
 export { PiwiFixtures, extendPiwiFixtures, piwiFixtures } from './internal/capture/capture-fixtures.js';
 
-/** Options for configuring the Piwi Dashboard reporter */
-interface PiwiDashboardOptions extends PlaywrightTestConfig {
+/**
+ * Options for configuring the Piwi Dashboard reporter.
+ *
+ * Piwi options only — the Playwright config belongs in `defineConfig` (i.e. in
+ * `wrapConfig`'s first argument). These go in `wrapConfig`'s second argument or
+ * in the reporter entry's options (`['@piwitests/reporter', { … }]`).
+ */
+interface PiwiDashboardOptions {
     /** Explicitly enable or disable the reporter. Defaults to `true` when `serverUrl` is set. Set to `false` to disable even if `serverUrl` is provided. */
     enabled?: boolean;
     /** URL of the Piwi Dashboard server */
@@ -182,6 +188,8 @@ declare class PiwiDashboardReporter {
     private shardInfo;
     private metadata;
     private enabled;
+    /** True when the server URL and API key came from the desktop app, not from config. */
+    private viaDesktopApp;
     private isFullRun;
     private filterDetails;
     private httpClient;