@piwitests/reporter 0.38.0 → 0.39.0

package/dist/cli/index.js

@@ -1945,8 +1945,144 @@ async function runProbe(argv) {
   return EXIT_OK4;
 }
 
-// src/cli/index.ts
+// src/cli/quality-report.ts
+var fs11 = __toESM(require("fs"));
+var EXIT_OK5 = 0;
+var EXIT_VERDICT = 1;
+var EXIT_ERROR5 = 2;
+var FORMATS = ["md", "json", "html", "pdf", "csv"];
+var DASHBOARDS = ["executive", "engineering", "overview"];
 var USAGE7 = `
+piwi report \u2014 print a quality report from the dashboard
+
+Usage:
+  npx @piwitests/reporter report [options]
+
+Connection:
+  --server-url <url>     Dashboard URL                 (env PIWI_DASHBOARD_URL)
+  --api-key <key>        API key                       (env PIWI_API_KEY)
+
+What to report:
+  --project <names|ids>  Comma-separated projects (default: every project you can see)
+  --period <period>      7d, 30d (default), last-month, this-quarter, 2026-08-01..2026-08-31, \u2026
+  --compare <mode>       previous (default), year, none
+  --dashboard <name>     executive (default), engineering, overview
+  --branch <names>       Comma-separated branches (default: each project's default branch)
+  --environment <names>  Comma-separated environments
+  --selection <key>      Only the tests of this selection
+  --lang <code>          Report language, such as en or fr (default: the dashboard's default)
+
+Output:
+  --format <fmt>         md (default), json, html, pdf, csv
+  --output <file>        Write to a file instead of stdout (required for pdf)
+  --fail-on <tone>       Exit 1 when the verdict is bad, or mixed or bad (--fail-on mixed)
+  -h, --help             Show this help
+
+Exit codes: 0 written, 1 written and the verdict is at or below --fail-on, 2 no report.
+`.trim();
+function readOption7(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 normalizePeriod(raw) {
+  const days = raw.trim().match(/^(\d+)d$/);
+  return days ? `last-${days[1]}d` : raw.trim();
+}
+function parseReportArgs(argv, env) {
+  const serverUrl = (readOption7(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");
+  const format = (readOption7(argv, "--format") ?? "md").toLowerCase();
+  if (!FORMATS.includes(format)) {
+    throw new Error(`--format must be one of ${FORMATS.join(", ")}, got "${format}"`);
+  }
+  const dashboard = readOption7(argv, "--dashboard") ?? "executive";
+  if (!DASHBOARDS.includes(dashboard)) {
+    throw new Error(`--dashboard must be one of ${DASHBOARDS.join(", ")}, got "${dashboard}"`);
+  }
+  const lang = readOption7(argv, "--lang") ?? null;
+  if (lang !== null && !/^[a-z]{2,3}(-[a-z0-9]{2,8})*$/i.test(lang)) {
+    throw new Error(`--lang must be a language code such as en or fr, got "${lang}"`);
+  }
+  const failOn = readOption7(argv, "--fail-on") ?? null;
+  if (failOn !== null && failOn !== "bad" && failOn !== "mixed") {
+    throw new Error(`--fail-on must be bad or mixed, got "${failOn}"`);
+  }
+  const output = readOption7(argv, "--output") ?? null;
+  if (format === "pdf" && !output) throw new Error("A PDF needs --output <file>");
+  return {
+    serverUrl,
+    apiKey: readOption7(argv, "--api-key") ?? env.PIWI_API_KEY ?? null,
+    projects: (readOption7(argv, "--project") ?? "").split(",").map((p) => p.trim()).filter(Boolean),
+    period: normalizePeriod(readOption7(argv, "--period") ?? "30d"),
+    compare: readOption7(argv, "--compare") ?? null,
+    dashboard,
+    branches: readOption7(argv, "--branch") ?? null,
+    environments: readOption7(argv, "--environment") ?? null,
+    selection: readOption7(argv, "--selection") ?? null,
+    lang,
+    format,
+    output,
+    failOn
+  };
+}
+function reportQuery(args, projectIds, format) {
+  const q = new URLSearchParams({ dashboard: args.dashboard, format, period: args.period });
+  if (projectIds.length > 0) q.set("projects", projectIds.join(","));
+  if (args.compare) q.set("compare", args.compare);
+  if (args.branches) q.set("branches", args.branches);
+  if (args.environments) q.set("environments", args.environments);
+  if (args.selection) q.set("sel", args.selection);
+  if (args.lang) q.set("lang", args.lang);
+  return q;
+}
+function failsOn(tone, failOn) {
+  if (!failOn) return false;
+  return failOn === "mixed" ? tone !== "good" : tone === "bad";
+}
+async function fetchReport(args, query) {
+  const res = await fetch(`${args.serverUrl}/api/reports/preview?${query}`, {
+    headers: args.apiKey ? { "X-API-Key": args.apiKey } : {}
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.message || `Dashboard returned ${res.status}`);
+  }
+  return res;
+}
+async function runQualityReport(argv) {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    console.log(USAGE7);
+    return EXIT_OK5;
+  }
+  try {
+    const args = parseReportArgs(argv, process.env);
+    const projectIds = [];
+    for (const project of args.projects) {
+      projectIds.push(await resolveProjectId({ serverUrl: args.serverUrl, apiKey: args.apiKey, project, key: "" }));
+    }
+    const res = await fetchReport(args, reportQuery(args, projectIds, args.format));
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    if (args.output) fs11.writeFileSync(args.output, bytes);
+    else process.stdout.write(bytes);
+    if (!args.failOn) return EXIT_OK5;
+    const bundle = args.format === "json" ? JSON.parse(new TextDecoder().decode(bytes)) : await (await fetchReport(args, reportQuery(args, projectIds, "json"))).json();
+    if (failsOn(bundle.verdict.tone, args.failOn)) {
+      console.error(`piwi report: the verdict is ${bundle.verdict.tone}`);
+      return EXIT_VERDICT;
+    }
+    return EXIT_OK5;
+  } catch (e) {
+    console.error(`piwi report: ${e.message}`);
+    return EXIT_ERROR5;
+  }
+}
+
+// src/cli/index.ts
+var USAGE8 = `
 piwi \u2014 companion commands for the Piwi Dashboard reporter
 
 Usage:
@@ -1956,6 +2092,7 @@ Commands:
   init      Wire a Playwright project up to a Piwi Dashboard
   skills    Install the Piwi agent skills into this project
   gate      Fail a CI job on the dashboard's analysis of a run
+  report    Print a quality report (Markdown, PDF, HTML, CSV or JSON)
   select    Print the Playwright args for a saved test selection
   run       Run a saved test selection with playwright test
   probe     Run the dashboard's probe plan and record what the suite noticed
@@ -1974,6 +2111,8 @@ async function main() {
       return runSkills(rest, findTemplatesDir(__dirname));
     case "gate":
       return runGate(rest);
+    case "report":
+      return runQualityReport(rest);
     case "select":
       return runSelect(rest);
     case "run":
@@ -1985,12 +2124,12 @@ async function main() {
     case void 0:
     case "-h":
     case "--help":
-      console.log(USAGE7);
+      console.log(USAGE8);
       return 0;
     default:
       console.error(`piwi: unknown command "${command}"
 `);
-      console.error(USAGE7);
+      console.error(USAGE8);
       return 2;
   }
 }

package/dist/index.js

@@ -1382,7 +1382,7 @@ var MetadataCollector = class {
   /**
    * Walk the test's parent `describe` suites to extract the suite path (titles)
    * and per-level config (parallel mode + annotations). Reaches into Playwright
-   * suite internals (`_parallelMode`, `_annotations`) — kept here next to
+   * suite internals (`_parallelMode`, `_staticAnnotations`) — kept here next to
    * `getBrowserConfig` so all such access is guarded behind one class.
    */
   getSuiteInfo(test) {
@@ -1399,7 +1399,10 @@ var MetadataCollector = class {
       suitePath.push(s.title);
       const rawMode = s._parallelMode;
       const mode = rawMode === "parallel" ? "parallel" : rawMode === "serial" ? "serial" : "default";
-      const annotations = s._annotations ?? [];
+      const staticAnnotations = s._staticAnnotations ?? [];
+      const annotations = staticAnnotations.map(
+        (a) => a.description === void 0 ? { type: a.type } : { type: a.type, description: a.description }
+      );
       suiteConfig.push({ mode, annotations });
     }
     return { suitePath, suiteConfig };
@@ -1497,6 +1500,8 @@ var MetadataCollector = class {
           // The origin of `baseURL` is what the graph treats as the run's own
           // surface, so only requests to it become route nodes.
           baseURL: p.use?.baseURL,
+          // The attribute `getByTestId` reads, so the locator index can resolve those locators on a live page.
+          testIdAttribute: p.use?.testIdAttribute,
           viewport: p.use?.viewport,
           deviceScaleFactor: p.use?.deviceScaleFactor
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piwitests/reporter",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Playwright reporter that streams results, traces and HTML reports to a Piwi Dashboard instance",
   "url": "https://github.com/PiwiTests/platform",
   "homepage": "https://piwitests.dev",