@piwitests/reporter 0.38.0 → 0.40.0

package/README.md

@@ -18,7 +18,7 @@ From your Playwright project, `npx @piwitests/reporter init` installs the report
 npx @piwitests/reporter init --server-url http://localhost:3000 --project my-project
 ```
 
-Every step is idempotent (safe to re-run); a config shape it will not rewrite is reported as `manual` with the exact change to make, never mangled. Add `--dry-run` to preview or `--json` for a machine-readable plan an agent can act on. It also installs the [Piwi agent skills](https://piwitests.dev/features/mcp#agent-skills) so your coding agent can investigate failures, heal locators, and stabilize flaky tests. Run `npx @piwitests/reporter init --help` for all options, or wire it up by hand with the steps below.
+Every step is idempotent (safe to re-run); a config shape it will not rewrite is reported as `manual` with the exact change to make, never mangled. Add `--dry-run` to preview or `--json` for a machine-readable plan an agent can act on. It also installs the [Piwi agent skills](https://piwitests.dev/features/agent-skills) so your coding agent can investigate failures, heal locators, and stabilize flaky tests. Run `npx @piwitests/reporter init --help` for all options, or wire it up by hand with the steps below.
 
 > The package is `@piwitests/reporter`; its command is `piwi`. Invoke it through the package name (`npx @piwitests/reporter <command>`) so npx resolves this package — `npx piwi` would fetch an unrelated `piwi` from npm. Once the reporter is a project dependency, `npx piwi <command>` resolves the local binary and works too.
 
@@ -57,12 +57,12 @@ Import `test` from this file in your specs instead of `@playwright/test`. A spec
 
 - **Run history, statuses, errors, traces, reports and live streaming** — with no test-code changes.
 - **Capture fixtures** add slow-endpoint analysis, Web Vitals, console capture, failure-time ARIA snapshots and locator healing.
-- **AI steps** (`page.piwiLocator(...)` / `page.piwiRun(...)`) drive flows in plain English, compiled once and replayed deterministically with zero LLM calls in CI — see [AI steps](https://piwitests.dev/guide/ai-steps).
+- **AI steps** (`page.piwiLocator(...)` / `page.piwiRun(...)`) drive flows in plain English, compiled once and replayed deterministically with zero LLM calls in CI — see [AI steps](https://piwitests.dev/features/ai-steps).
 - **CI-aware** — auto-detects the run label, branch and commit, publishes the run URL back to the pipeline, and shards into a single run. See [CI & sharding](https://piwitests.dev/guide/ci).
 
 ## Configuration
 
-Every option can also be set via a `PIWI_*` environment variable (config wins over env). The full option and env-var reference lives in the [reporter documentation](https://piwitests.dev/guide/reporter); authentication for CI (API keys) is covered under [Authentication](https://piwitests.dev/operate/authentication).
+Every option can also be set via a `PIWI_*` environment variable (config wins over env). The full option and env-var reference lives in [Reporter options](https://piwitests.dev/reference/reporter-options); authentication for CI is covered under [API keys](https://piwitests.dev/operate/api-keys).
 
 ## Requirements
 

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.d.ts

@@ -3,6 +3,7 @@ import { PlaywrightTestConfig, Locator, TestType, Page, Fixtures, PlaywrightTest
 export { PlaywrightTestConfig } from '@playwright/test';
 export { PiwiFixtures, extendPiwiFixtures, piwiFixtures } from './internal/capture/capture-fixtures.js';
 import '@piwitests/picker-dom';
+import '@piwitests/core/wire';
 
 /**
  * Options for configuring the Piwi Dashboard reporter.
@@ -175,8 +176,8 @@ interface PiwiDashboardOptions {
     label?: string;
     /**
      * Keep this run forever: the dashboard's retention never deletes it. Set it
-     * for the runs worth keeping, such as release or tag builds. Can also be set
-     * with `PIWI_KEEP=true`.
+     * for the runs worth keeping, such as release or tag builds. Defaults to
+     * `false`. Can also be set with `PIWI_KEEP=true`.
      */
     keep?: boolean;
     /** Related issue reference, e.g. `"JIRA-123"` */