@piwitests/reporter 0.36.0 → 0.39.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 path4 = __toESM(require("path"));
+var path5 = __toESM(require("path"));
 
 // src/internal/support/errors.ts
 function errorMessage(error) {
@@ -44,7 +44,7 @@ function errorMessage(error) {
 }
 
 // src/public/global-setup.ts
-var fs4 = __toESM(require("fs"));
+var fs5 = __toESM(require("fs"));
 
 // src/internal/config/desktop.ts
 var fs = __toESM(require("fs"));
@@ -77,8 +77,12 @@ var DEFAULTS = {
   collectPerformanceMetrics: true,
   captureLocators: true,
   capturePageState: true,
+  // Off by default: the page inventory reads control and link names from every
+  // visited page, so it stays opt-in until a project turns it on.
+  capturePageInventory: false,
   captureServerTraces: true,
   sampleAriaOnPass: true,
+  uploadManifest: true,
   defaultCapture: true,
   streaming: true,
   streamingBatchSize: 5,
@@ -100,6 +104,7 @@ var PIWI_ENV_KEYS = {
   environment: "PIWI_ENVIRONMENT",
   label: "PIWI_LABEL",
   runLabel: "PIWI_RUN_LABEL",
+  keep: "PIWI_KEEP",
   streaming: "PIWI_STREAMING",
   streamingBatchSize: "PIWI_STREAMING_BATCH_SIZE",
   streamingBatchDelay: "PIWI_STREAMING_BATCH_DELAY",
@@ -110,8 +115,10 @@ var PIWI_ENV_KEYS = {
   uploadReport: "PIWI_UPLOAD_REPORT",
   captureLocators: "PIWI_CAPTURE_LOCATORS",
   capturePageState: "PIWI_CAPTURE_PAGE_STATE",
+  capturePageInventory: "PIWI_CAPTURE_PAGE_INVENTORY",
   captureServerTraces: "PIWI_CAPTURE_SERVER_TRACES",
   sampleAriaOnPass: "PIWI_SAMPLE_ARIA_ON_PASS",
+  uploadManifest: "PIWI_UPLOAD_MANIFEST",
   defaultCapture: "PIWI_DEFAULT_CAPTURE",
   inspectOnFailure: "PIWI_INSPECT_ON_FAIL",
   pickLocatorOnFailure: "PIWI_PICK_LOCATOR_ON_FAIL",
@@ -139,6 +146,7 @@ var ENV_FALLBACK_SPECS = [
   { option: "environment", env: PIWI_ENV_KEYS.environment, kind: "string" },
   { option: "label", env: PIWI_ENV_KEYS.label, kind: "string" },
   { option: "runLabel", env: PIWI_ENV_KEYS.runLabel, kind: "string" },
+  { option: "keep", env: PIWI_ENV_KEYS.keep, kind: "bool" },
   { 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" },
@@ -149,8 +157,10 @@ var ENV_FALLBACK_SPECS = [
   { option: "uploadReport", env: PIWI_ENV_KEYS.uploadReport, kind: "bool" },
   { option: "captureLocators", env: PIWI_ENV_KEYS.captureLocators, kind: "bool" },
   { option: "capturePageState", env: PIWI_ENV_KEYS.capturePageState, kind: "bool" },
+  { option: "capturePageInventory", env: PIWI_ENV_KEYS.capturePageInventory, kind: "bool" },
   { option: "captureServerTraces", env: PIWI_ENV_KEYS.captureServerTraces, kind: "bool" },
   { option: "sampleAriaOnPass", env: PIWI_ENV_KEYS.sampleAriaOnPass, kind: "bool" },
+  { option: "uploadManifest", env: PIWI_ENV_KEYS.uploadManifest, 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" },
@@ -351,6 +361,27 @@ var HttpClient = class {
       return {};
     }
   }
+  /** Send a JSON PUT request. Used for the declared-surface manifest upload. */
+  async putJSON(pathname, payload, auth) {
+    const body = JSON.stringify(payload);
+    const res = await this.request("PUT", pathname, {
+      headers: {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body)
+      },
+      body,
+      auth
+    });
+    if (res.status < 200 || res.status >= 300) {
+      this.logger.debugError(`Response: ${res.text}`);
+      throw new HttpError(res.status);
+    }
+    try {
+      return JSON.parse(res.text);
+    } catch {
+      return {};
+    }
+  }
   /** Send a multipart form-data POST request. Used for report and trace uploads. */
   async postFormData(pathname, form, auth) {
     const headers = form.getHeaders();
@@ -453,6 +484,36 @@ function detectCiRunLabel() {
   return null;
 }
 
+// src/internal/collect/metadata-collector.ts
+var import_node_child_process = require("child_process");
+var DETACHED_HEAD = "HEAD";
+function resolveScmBranch(env, gitBranch) {
+  const pick = (...names) => {
+    for (const name of names) {
+      const value = env[name]?.trim();
+      if (value) return value;
+    }
+    return void 0;
+  };
+  const override = env.PIWI_BRANCH?.trim();
+  if (override) return override;
+  let provider;
+  if (env.JENKINS_URL) provider = pick("CHANGE_BRANCH", "BRANCH_NAME");
+  else if (env.GITHUB_ACTIONS) provider = pick("GITHUB_HEAD_REF", "GITHUB_REF_NAME");
+  else if (env.GITLAB_CI) provider = pick("CI_MERGE_REQUEST_SOURCE_BRANCH_NAME", "CI_COMMIT_REF_NAME");
+  else if (env.CIRCLECI) provider = pick("CIRCLE_BRANCH");
+  else if (env.TRAVIS) provider = pick("TRAVIS_PULL_REQUEST_BRANCH", "TRAVIS_BRANCH");
+  else if (env.TF_BUILD) provider = pick("SYSTEM_PULLREQUEST_SOURCEBRANCH", "BUILD_SOURCEBRANCHNAME");
+  else if (env.BITBUCKET_BUILD_NUMBER) provider = pick("BITBUCKET_BRANCH");
+  if (provider) return normalizeRef(provider);
+  const trimmed = gitBranch?.trim();
+  if (trimmed && trimmed !== DETACHED_HEAD) return trimmed;
+  return void 0;
+}
+function normalizeRef(ref) {
+  return ref.replace(/^refs\/heads\//, "");
+}
+
 // src/internal/support/setup-file.ts
 var path2 = __toESM(require("path"));
 var os3 = __toESM(require("os"));
@@ -500,17 +561,83 @@ function isListMode(argv = process.argv) {
   return rest.some((tok) => PW_LIST_FLAGS.some((flag) => tok === flag || tok.startsWith(`${flag}=`)));
 }
 
+// src/internal/manifest/collect.ts
+var fs4 = __toESM(require("fs"));
+var path4 = __toESM(require("path"));
+var COMMITTED_MANIFEST_FILE = "piwi.manifest.json";
+var INSTRUMENTATION_MANIFEST_PATH = "/__piwi/manifest";
+var INSTRUMENTATION_HEADERS = ["x-piwi-logs", "x-piwi-trace"];
+function parseManifestJson(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed;
+  const routes = Array.isArray(obj.routes) ? obj.routes.filter((r) => !!r && typeof r === "object").filter((r) => typeof r.method === "string" && typeof r.pattern === "string").map((r) => ({
+    method: r.method,
+    pattern: r.pattern,
+    handler: typeof r.handler === "string" ? r.handler : void 0,
+    responses: Array.isArray(r.responses) ? r.responses.filter((c) => Number.isInteger(c)) : void 0
+  })) : void 0;
+  const pages = Array.isArray(obj.pages) ? obj.pages.filter((p) => !!p && typeof p === "object").filter((p) => typeof p.pattern === "string").map((p) => ({ pattern: p.pattern, name: typeof p.name === "string" ? p.name : void 0 })) : void 0;
+  if (!routes && !pages) return null;
+  return { routes, pages };
+}
+function hasInstrumentationHeader(headers) {
+  const get = (name) => typeof headers.get === "function" ? headers.get(name) : headers[name];
+  return INSTRUMENTATION_HEADERS.some((h) => get(h) != null && get(h) !== "");
+}
+function readCommittedManifest(configDir) {
+  const file = path4.join(configDir, COMMITTED_MANIFEST_FILE);
+  try {
+    if (!fs4.existsSync(file)) return null;
+    return parseManifestJson(fs4.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function configDirFromConfig(config) {
+  if (config?.configFile) return path4.dirname(config.configFile);
+  if (config?.rootDir) return config.rootDir;
+  return process.cwd();
+}
+function baseUrlFromConfig(config) {
+  const top = config?.use?.baseURL;
+  if (typeof top === "string" && top) return top;
+  for (const project of config?.projects ?? []) {
+    const url = project?.use?.baseURL;
+    if (typeof url === "string" && url) return url;
+  }
+  return null;
+}
+var INSTRUMENTATION_FETCH_TIMEOUT_MS = 5e3;
+async function fetchInstrumentationManifest(baseUrl, fetchImpl = fetch) {
+  try {
+    const probe = await fetchImpl(baseUrl, { signal: AbortSignal.timeout(INSTRUMENTATION_FETCH_TIMEOUT_MS) });
+    if (!hasInstrumentationHeader(probe.headers)) return null;
+    const manifestUrl = new URL(INSTRUMENTATION_MANIFEST_PATH, baseUrl).toString();
+    const res = await fetchImpl(manifestUrl, { signal: AbortSignal.timeout(INSTRUMENTATION_FETCH_TIMEOUT_MS) });
+    if (!res.ok) return null;
+    return parseManifestJson(await res.text());
+  } catch {
+    return null;
+  }
+}
+
 // src/public/global-setup.ts
 function createGlobalSetup(options, userSetup) {
   return async function globalSetupFn(config) {
-    const piwiReporterPath = path4.resolve(__dirname, "./index.js");
+    const piwiReporterPath = path5.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 path4.resolve(require.resolve(r[0])) === piwiReporterPath;
+            return path5.resolve(require.resolve(r[0])) === piwiReporterPath;
           } catch {
             return false;
           }
@@ -542,7 +669,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 path4.resolve(require.resolve(r[0])) === piwiReporterPath;
+        return path5.resolve(require.resolve(r[0])) === piwiReporterPath;
       } catch {
         return false;
       }
@@ -566,6 +693,7 @@ function createGlobalSetup(options, userSetup) {
           projectDescription: opts.projectDescription,
           environment: opts.environment || null,
           label: opts.label || null,
+          keep: opts.keep === true,
           startTime: (/* @__PURE__ */ new Date()).toISOString(),
           instanceId: computeInstanceId(opts.projectName, runLabel),
           shardIndex,
@@ -574,7 +702,7 @@ function createGlobalSetup(options, userSetup) {
         auth
       );
       if (response?.runId && response?.setupToken) {
-        fs4.writeFileSync(
+        fs5.writeFileSync(
           getSetupFilePath(opts.projectName),
           JSON.stringify({
             runId: response.runId,
@@ -585,18 +713,43 @@ 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 wantsAria = opts.sampleAriaOnPass !== false && !!opts.projectName;
+      const committedManifest = opts.uploadManifest !== false ? readCommittedManifest(configDirFromConfig(config)) : null;
+      const manifestBaseUrl = opts.uploadManifest !== false ? baseUrlFromConfig(config) : null;
+      const wantsManifest = opts.uploadManifest !== false && !!opts.projectName && (!!committedManifest || !!manifestBaseUrl);
+      let projectId;
+      if ((wantsAria || wantsManifest) && opts.projectName) {
         const menu = await httpClient.getJSON("/api/projects/menu", auth);
-        const projectId = menu?.items?.find(
+        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.`);
+      }
+      if (wantsAria && 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.`);
+        }
+      }
+      if (wantsManifest && projectId != null) {
+        const branch = resolveScmBranch(process.env) ?? null;
+        if (committedManifest) {
+          await httpClient.putJSON(
+            `/api/projects/${projectId}/surface/manifest`,
+            { source: "committed", branch, manifest: committedManifest },
+            auth
+          ).catch((e) => logger.debug(`Manifest upload (committed) skipped: ${errorMessage(e)}`));
+        }
+        if (manifestBaseUrl) {
+          const declared = await fetchInstrumentationManifest(manifestBaseUrl);
+          if (declared) {
+            await httpClient.putJSON(
+              `/api/projects/${projectId}/surface/manifest`,
+              { source: "instrumentation", branch, manifest: declared },
+              auth
+            ).catch((e) => logger.debug(`Manifest upload (instrumentation) skipped: ${errorMessage(e)}`));
           }
         }
       }

package/dist/index.d.ts

@@ -48,6 +48,17 @@ interface PiwiDashboardOptions {
      * also be forced off with `PIWI_CAPTURE_PAGE_STATE=false`.
      */
     capturePageState?: boolean;
+    /**
+     * Capture a lightweight inventory of each visited page on *passing* runs — the
+     * interactive controls (role + accessible name) and links (name, with the query
+     * and hash stripped from the href) present as the test navigates — so the
+     * dashboard can tell which controls and links the suite exposes but never
+     * exercises. Only names and hrefs are captured, never field values; a page's
+     * controls are read at most once per worker per run. **Defaults to `false`** —
+     * opt in with `capturePageInventory: true` (or `PIWI_CAPTURE_PAGE_INVENTORY=true`).
+     * Automatically disabled when `collectPerformanceMetrics` is `false`.
+     */
+    capturePageInventory?: boolean;
     /**
      * Capture server-side spans for each API/document request the test makes,
      * read from the `X-Piwi-Trace` response header emitted by a Piwi
@@ -68,6 +79,15 @@ interface PiwiDashboardOptions {
      * Set to `false` (or `PIWI_SAMPLE_ARIA_ON_PASS=false`) to never sample on pass.
      */
     sampleAriaOnPass?: boolean;
+    /**
+     * Upload the application's declared surface at run start: a committed
+     * `piwi.manifest.json` next to the Playwright config, and — when the base URL's
+     * first response carries an instrumentation header — the instrumentation
+     * package's `/__piwi/manifest`. A route or page the manifest declares that no
+     * test reaches becomes a "declared, never hit" gap. Defaults to `true`; set to
+     * `false` (or `PIWI_UPLOAD_MANIFEST=false`) to never upload.
+     */
+    uploadManifest?: 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
@@ -153,6 +173,12 @@ interface PiwiDashboardOptions {
     environment?: string;
     /** Optional display label for the test run (e.g. "v2.3.1 release") */
     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`.
+     */
+    keep?: boolean;
     /** Related issue reference, e.g. `"JIRA-123"` */
     relatedIssue?: string;
     /** CI job information */
@@ -332,12 +358,15 @@ declare class PiwiDashboardReporter {
     onTestBegin(test: TestCase, result: TestResult): void;
     /** Track suite-level setup steps (beforeAll/afterAll) not tied to any test */
     private setupSteps;
+    /** Step categories streamed live while the run executes. */
+    private static readonly LIVE_STEP_CATEGORIES;
     /**
-     * Step categories streamed live while the run executes. `pw:assert` is
-     * excluded: it is the polling noise of `expect()`, not a step a human
-     * watches; the meaningful readout is the `pw:expect` wrapper around it.
+     * Whether a step streams live: its category is in `LIVE_STEP_CATEGORIES`
+     * and no ancestor is an `expect` step. The steps inside an assertion are its
+     * polling — every `expect.poll` attempt and `toPass` retry — not a step a
+     * human watches; the meaningful readout is the assertion around them.
      */
-    private static readonly LIVE_STEP_CATEGORIES;
+    private static isLiveStep;
     /** Playwright reporter hook: called when a step (including hook/fixture) begins */
     onStepBegin(test: TestCase | undefined, _result: TestResult | undefined, step: any): void;
     /** Playwright reporter hook: called when a step (including hook/fixture) ends */