@piwitests/reporter 0.26.1 → 0.28.0

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 path3 = __toESM(require("path"));
+var path4 = __toESM(require("path"));
 
 // src/internal/support/errors.ts
 function errorMessage(error) {
@@ -44,7 +44,7 @@ function errorMessage(error) {
 }
 
 // src/public/global-setup.ts
-var fs3 = __toESM(require("fs"));
+var fs4 = __toESM(require("fs"));
 
 // src/internal/config/desktop.ts
 var fs = __toESM(require("fs"));
@@ -78,9 +78,12 @@ var DEFAULTS = {
   captureLocators: true,
   capturePageState: true,
   captureServerTraces: true,
+  sampleAriaOnPass: true,
+  defaultCapture: true,
   streaming: true,
   streamingBatchSize: 5,
   streamingBatchDelay: 2e3,
+  maxStreamBufferBytes: 100 * 1024 * 1024,
   failOnFlakyTests: false,
   username: null,
   password: null,
@@ -100,6 +103,7 @@ var PIWI_ENV_KEYS = {
   streaming: "PIWI_STREAMING",
   streamingBatchSize: "PIWI_STREAMING_BATCH_SIZE",
   streamingBatchDelay: "PIWI_STREAMING_BATCH_DELAY",
+  maxStreamBufferBytes: "PIWI_MAX_STREAM_BUFFER_BYTES",
   liveFileUploads: "PIWI_LIVE_FILE_UPLOADS",
   failOnFlakyTests: "PIWI_FAIL_ON_FLAKY_TESTS",
   uploadTraces: "PIWI_UPLOAD_TRACES",
@@ -107,6 +111,8 @@ var PIWI_ENV_KEYS = {
   captureLocators: "PIWI_CAPTURE_LOCATORS",
   capturePageState: "PIWI_CAPTURE_PAGE_STATE",
   captureServerTraces: "PIWI_CAPTURE_SERVER_TRACES",
+  sampleAriaOnPass: "PIWI_SAMPLE_ARIA_ON_PASS",
+  defaultCapture: "PIWI_DEFAULT_CAPTURE",
   inspectOnFailure: "PIWI_INSPECT_ON_FAIL",
   pickLocatorOnFailure: "PIWI_PICK_LOCATOR_ON_FAIL",
   outputFile: "PIWI_OUTPUT_FILE",
@@ -136,6 +142,7 @@ var ENV_FALLBACK_SPECS = [
   { option: "streaming", env: PIWI_ENV_KEYS.streaming, kind: "bool" },
   { option: "streamingBatchSize", env: PIWI_ENV_KEYS.streamingBatchSize, kind: "number" },
   { option: "streamingBatchDelay", env: PIWI_ENV_KEYS.streamingBatchDelay, kind: "number" },
+  { option: "maxStreamBufferBytes", env: PIWI_ENV_KEYS.maxStreamBufferBytes, kind: "number" },
   { option: "liveFileUploads", env: PIWI_ENV_KEYS.liveFileUploads, kind: "bool" },
   { option: "failOnFlakyTests", env: PIWI_ENV_KEYS.failOnFlakyTests, kind: "bool" },
   { option: "uploadTraces", env: PIWI_ENV_KEYS.uploadTraces, kind: "bool" },
@@ -143,6 +150,8 @@ var ENV_FALLBACK_SPECS = [
   { option: "captureLocators", env: PIWI_ENV_KEYS.captureLocators, kind: "bool" },
   { option: "capturePageState", env: PIWI_ENV_KEYS.capturePageState, kind: "bool" },
   { option: "captureServerTraces", env: PIWI_ENV_KEYS.captureServerTraces, kind: "bool" },
+  { option: "sampleAriaOnPass", env: PIWI_ENV_KEYS.sampleAriaOnPass, kind: "bool" },
+  { option: "defaultCapture", env: PIWI_ENV_KEYS.defaultCapture, kind: "bool" },
   { option: "inspectOnFailure", env: PIWI_ENV_KEYS.inspectOnFailure, kind: "bool" },
   { option: "pickLocatorOnFailure", env: PIWI_ENV_KEYS.pickLocatorOnFailure, kind: "bool" },
   { option: "outputFile", env: PIWI_ENV_KEYS.outputFile, kind: "string" }
@@ -298,6 +307,29 @@ var HttpClient = class {
     this.logger.debug("Logged in successfully");
     return cookie;
   }
+  /**
+   * Send a JSON GET request, returning the parsed body, or `null` on any non-2xx
+   * status or parse failure. Unlike `postJSON` this never throws — its callers
+   * treat a missing or unreachable endpoint as "feature unavailable".
+   */
+  async getJSON(pathname, auth) {
+    let res;
+    try {
+      res = await this.request("GET", pathname, { auth });
+    } catch (error) {
+      this.logger.debug(`GET ${pathname} failed: ${error.message}`);
+      return null;
+    }
+    if (res.status < 200 || res.status >= 300) {
+      this.logger.debug(`GET ${pathname} returned ${res.status}`);
+      return null;
+    }
+    try {
+      return JSON.parse(res.text);
+    } catch {
+      return null;
+    }
+  }
   /** Send a JSON POST request. `auth` can be an API key (prefix `pd_`) or a session cookie string. */
   async postJSON(pathname, payload, auth) {
     const body = JSON.stringify(payload);
@@ -348,7 +380,7 @@ var HttpClient = class {
         {
           hostname: url.hostname,
           port: url.port || (url.protocol === "https:" ? 443 : 80),
-          path: url.pathname,
+          path: url.pathname + url.search,
           method,
           headers
         },
@@ -360,6 +392,12 @@ var HttpClient = class {
           res.on("end", () => {
             resolve2({ status: res.statusCode ?? 0, text: data, headers: res.headers });
           });
+          res.on("error", reject);
+          res.on("close", () => {
+            if (!res.complete) {
+              reject(new Error(`Connection to ${pathname} closed before the response completed`));
+            }
+          });
         }
       );
       req.on("error", reject);
@@ -423,6 +461,29 @@ function getSetupFilePath(projectName) {
   return path2.join(os3.tmpdir(), `piwi-dashboard-setup-${hashForProject(projectName)}.json`);
 }
 
+// src/internal/support/aria-sampling.ts
+var path3 = __toESM(require("path"));
+var os4 = __toESM(require("os"));
+var fs3 = __toESM(require("fs"));
+function ariaSampleIdentity(filePath, title) {
+  return `${filePath}\0${title}`;
+}
+function getAriaSampleFilePath(projectName) {
+  return path3.join(os4.tmpdir(), `piwi-dashboard-aria-sample-${hashForProject(projectName)}.json`);
+}
+function writeAriaSampleFile(projectName, identities) {
+  try {
+    fs3.writeFileSync(getAriaSampleFilePath(projectName), JSON.stringify({ projectName, identities }));
+  } catch {
+  }
+}
+function clearAriaSampleFile(projectName) {
+  try {
+    fs3.rmSync(getAriaSampleFilePath(projectName), { force: true });
+  } catch {
+  }
+}
+
 // src/internal/support/run-mode.ts
 var PW_UI_FLAGS = ["--ui", "--ui-host", "--ui-port"];
 function isUiMode(argv = process.argv) {
@@ -431,18 +492,25 @@ function isUiMode(argv = process.argv) {
   const rest = testIdx >= 0 ? args.slice(testIdx + 1) : args;
   return rest.some((tok) => PW_UI_FLAGS.some((flag) => tok === flag || tok.startsWith(`${flag}=`)));
 }
+var PW_LIST_FLAGS = ["--list"];
+function isListMode(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_LIST_FLAGS.some((flag) => tok === flag || tok.startsWith(`${flag}=`)));
+}
 
 // src/public/global-setup.ts
 function createGlobalSetup(options, userSetup) {
   return async function globalSetupFn(config) {
-    const piwiReporterPath = path3.resolve(__dirname, "./index.js");
+    const piwiReporterPath = path4.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 path3.resolve(require.resolve(r[0])) === piwiReporterPath;
+            return path4.resolve(require.resolve(r[0])) === piwiReporterPath;
           } catch {
             return false;
           }
@@ -460,6 +528,11 @@ function createGlobalSetup(options, userSetup) {
       if (userSetup) return userSetup(config);
       return;
     }
+    if (isListMode()) {
+      logger.debug("List 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);
@@ -469,7 +542,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 path3.resolve(require.resolve(r[0])) === piwiReporterPath;
+        return path4.resolve(require.resolve(r[0])) === piwiReporterPath;
       } catch {
         return false;
       }
@@ -501,7 +574,7 @@ function createGlobalSetup(options, userSetup) {
         auth
       );
       if (response?.runId && response?.setupToken) {
-        fs3.writeFileSync(
+        fs4.writeFileSync(
           getSetupFilePath(opts.projectName),
           JSON.stringify({
             runId: response.runId,
@@ -511,6 +584,22 @@ function createGlobalSetup(options, userSetup) {
         );
         logger.debug(`Global setup: initializing run #${response.runId}`);
       }
+      if (opts.projectName) clearAriaSampleFile(opts.projectName);
+      if (opts.sampleAriaOnPass !== false && opts.projectName) {
+        const menu = await httpClient.getJSON("/api/projects/menu", auth);
+        const projectId = menu?.items?.find(
+          (p) => p.name.toLowerCase() === opts.projectName.toLowerCase()
+        )?.id;
+        if (projectId != null) {
+          const sampling = await httpClient.getJSON(`/api/projects/${projectId}/aria-sampling`, auth);
+          const tests = Array.isArray(sampling?.tests) ? sampling.tests : null;
+          if (tests) {
+            const identities = tests.filter((t) => typeof t.filePath === "string" && typeof t.title === "string").map((t) => ariaSampleIdentity(t.filePath, t.title));
+            writeAriaSampleFile(opts.projectName, identities);
+            logger.debug(`Green ARIA sampling: ${identities.length} test(s) due a sample.`);
+          }
+        }
+      }
     } catch (error) {
       logger.warn(`Could not register global setup: ${errorMessage(error)}`);
     }

package/dist/index.d.ts

@@ -58,6 +58,33 @@ interface PiwiDashboardOptions {
      * `false`. Can also be forced off with `PIWI_CAPTURE_SERVER_TRACES=false`.
      */
     captureServerTraces?: boolean;
+    /**
+     * Sample the ARIA snapshot at the end of a *passing* test, so a later failure
+     * can be diffed against the page as it last looked when green. Rate-limited by
+     * the server: at run start the reporter asks which tests are due a fresh
+     * sample (their newest green snapshot is older than a day, or missing) and
+     * captures only those, so steady-state runs pay nothing. Rides the existing
+     * capture fixtures — no snapshot is taken without them. Defaults to `true`.
+     * Set to `false` (or `PIWI_SAMPLE_ARIA_ON_PASS=false`) to never sample on pass.
+     */
+    sampleAriaOnPass?: boolean;
+    /**
+     * When installed via `wrapConfig`, default Playwright's own `screenshot` and
+     * `trace` options on the top-level `use` block so a failing test keeps a
+     * screenshot (`'only-on-failure'`) and a trace (`'retain-on-failure'`) even
+     * without the capture fixtures — the trace alone unlocks the DOM snapshot,
+     * full call stack, full network with bodies and the visual diff. On Playwright
+     * 1.63 or later the trace default also turns on the per-action aria tree
+     * (`snapshots: { dom: true, aria: true }`), which adds the accessibility tree
+     * before and after each action at negligible size. The `screen` snapshot kind
+     * (a PNG per action, the trace's biggest cost) stays opt-in — set it yourself
+     * with `use: { trace: { mode: 'retain-on-failure', snapshots: { dom: true,
+     * aria: true, screen: true } } }`. Only fills options the config leaves unset;
+     * an explicit value (including `'off'`) and per-project `use` blocks are never
+     * touched. Defaults to `true`. Set to `false` (or `PIWI_DEFAULT_CAPTURE=false`)
+     * to opt out and let Playwright's own defaults stand.
+     */
+    defaultCapture?: boolean;
     /**
      * Open Piwi's own failure-time overlay on the failing page — for inspecting
      * the page and picking a locator for any element (click an element → confirm
@@ -88,6 +115,18 @@ interface PiwiDashboardOptions {
     streamingBatchSize?: number;
     /** Max delay (ms) before flushing pending events during streaming. Defaults to `2000`. */
     streamingBatchDelay?: number;
+    /**
+     * Byte budget for the in-memory stream buffer (the queue of events waiting to
+     * reach the dashboard, and the crash-recovery file it writes if delivery
+     * fails). When the server is unreachable or a huge suite outruns delivery, the
+     * queue is capped here instead of growing without bound: the lowest-value
+     * events are shed first — live step progress, then per-test `begin` markers,
+     * and only as a last resort test results (the final counts and the end-of-run
+     * batch submit stay complete regardless). Defaults to `104857600` (100 MB).
+     * Set to `0` to disable the cap (unbounded, the pre-`0.28` behavior). Can also
+     * be set with `PIWI_MAX_STREAM_BUFFER_BYTES`.
+     */
+    maxStreamBufferBytes?: number;
     /**
      * Fail the run when any test was flaky (passed only after a retry). Forwarded
      * to Playwright's native `failOnFlakyTests` config option (Playwright 1.52+)
@@ -210,14 +249,23 @@ declare function createGlobalSetup(options?: PiwiDashboardOptions, userSetup?: (
  *
  * The `globalSetup` field is set to a `string` (or `string[]` if the user
  * already has a global setup) referencing the Piwi global setup module,
- * which registers the run on the server. The original setup path(s) are
- * preserved and executed first.
+ * which registers the run on the server. Piwi's module is chained first so the
+ * run registers before the user's own setup, appearing as "initializing" on the
+ * dashboard while that setup runs; the original setup path(s) are preserved and
+ * executed after it.
  *
  * Playwright options required in `globalSetup` are forwarded via `PIWI_*`
  * environment variables (see `applyOptionsToEnv` in `config.ts` for the
  * supported set — `serverUrl`, `projectName`, `verbose`, `apiKey`,
  * `username`, `password`, `environment`, `label`, `runLabel`).
  *
+ * The top-level `use` block's `screenshot` and `trace` are defaulted to
+ * `'only-on-failure'` / `'retain-on-failure'` when unset so failure evidence is
+ * captured without the fixtures; on Playwright 1.63 or later `trace` also turns
+ * on the per-action aria tree (`snapshots: { dom: true, aria: true }`). An
+ * explicit value (including `'off'`) is kept. Opt out with `defaultCapture:
+ * false` (or `PIWI_DEFAULT_CAPTURE=false`).
+ *
  * @param config      The user's Playwright config.
  * @param piwiOptions Optional Piwi Dashboard options (serverUrl, projectName, …).
  */
@@ -254,6 +302,12 @@ declare class PiwiDashboardReporter {
     private shardInfo;
     private metadata;
     private enabled;
+    /**
+     * True under `playwright test --list`, where Playwright still constructs this
+     * reporter and fires `onBegin`/`onEnd` but runs no tests. Registering and
+     * finalizing a run would create an empty phantom run and upload an empty report.
+     */
+    private readonly listMode;
     /** True when the server URL and API key came from the desktop app, not from config. */
     private viaDesktopApp;
     private isFullRun;
@@ -267,6 +321,7 @@ declare class PiwiDashboardReporter {
     private streamManager;
     private recovery;
     private submitter;
+    private readonly failureLinks;
     private readonly logger;
     static wrapConfig: typeof wrapConfig;
     static createGlobalSetup: typeof createGlobalSetup;