@piwitests/reporter 0.44.0 → 0.46.0

package/dist/global-setup-module.js

@@ -83,9 +83,12 @@ var DEFAULTS = {
   // Off by default: JavaScript coverage slows the page, so a scheduled job opts in.
   captureCodeReach: false,
   captureServerTraces: true,
+  captureResources: true,
+  leakCheck: "report",
   sampleAriaOnPass: true,
   uploadManifest: true,
   defaultCapture: true,
+  checkBaseUrl: false,
   streaming: true,
   streamingBatchSize: 5,
   streamingBatchDelay: 2e3,
@@ -123,9 +126,12 @@ var PIWI_ENV_KEYS = {
   captureCodeReach: "PIWI_CAPTURE_CODE_REACH",
   codeReachRoots: "PIWI_CODE_REACH_ROOTS",
   captureServerTraces: "PIWI_CAPTURE_SERVER_TRACES",
+  captureResources: "PIWI_CAPTURE_RESOURCES",
+  leakCheck: "PIWI_LEAK_CHECK",
   sampleAriaOnPass: "PIWI_SAMPLE_ARIA_ON_PASS",
   uploadManifest: "PIWI_UPLOAD_MANIFEST",
   defaultCapture: "PIWI_DEFAULT_CAPTURE",
+  checkBaseUrl: "PIWI_CHECK_BASE_URL",
   inspectOnFailure: "PIWI_INSPECT_ON_FAIL",
   pickLocatorOnFailure: "PIWI_PICK_LOCATOR_ON_FAIL",
   outputFile: "PIWI_OUTPUT_FILE",
@@ -168,9 +174,12 @@ var ENV_FALLBACK_SPECS = [
   { option: "capturePageInventory", env: PIWI_ENV_KEYS.capturePageInventory, kind: "bool" },
   { option: "captureCodeReach", env: PIWI_ENV_KEYS.captureCodeReach, kind: "bool" },
   { option: "captureServerTraces", env: PIWI_ENV_KEYS.captureServerTraces, kind: "bool" },
+  { option: "captureResources", env: PIWI_ENV_KEYS.captureResources, kind: "bool" },
+  { option: "leakCheck", env: PIWI_ENV_KEYS.leakCheck, kind: "string" },
   { 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: "checkBaseUrl", env: PIWI_ENV_KEYS.checkBaseUrl, 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" }
@@ -613,6 +622,131 @@ function isListMode(argv = process.argv) {
   return rest.some((tok) => PW_LIST_FLAGS.some((flag) => tok === flag || tok.startsWith(`${flag}=`)));
 }
 
+// src/internal/support/base-url-check.ts
+var BASE_URL_CHECK_ATTEMPTS = 3;
+var BASE_URL_CHECK_TIMEOUT_MS = 1e4;
+var BASE_URL_CHECK_DELAY_MS = 2e3;
+var GATEWAY_ANSWERS = {
+  502: "bad gateway",
+  503: "service unavailable",
+  504: "gateway timeout"
+};
+function cliProjectNames(argv = process.argv) {
+  let names = null;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--project=")) {
+      (names ??= []).push(arg.slice("--project=".length));
+    } else if (arg === "--project") {
+      names ??= [];
+      while (i + 1 < argv.length && !argv[i + 1].startsWith("-")) names.push(argv[++i]);
+    }
+  }
+  return names;
+}
+function wildcard(pattern) {
+  const escaped = pattern.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  return new RegExp(`^${escaped.join(".*")}$`, "i");
+}
+function selectedProjects(projects, argv = process.argv) {
+  const names = cliProjectNames(argv);
+  if (!names || names.length === 0) return projects;
+  const patterns = names.map(wildcard);
+  const chosen = new Set(projects.filter((p) => patterns.some((re) => re.test(p.name ?? ""))));
+  if (!argv.includes("--no-deps")) {
+    const byName = new Map(projects.map((p) => [p.name ?? "", p]));
+    const queue = [...chosen];
+    while (queue.length > 0) {
+      for (const dep of queue.shift().dependencies ?? []) {
+        const project = byName.get(dep);
+        if (project && !chosen.has(project)) {
+          chosen.add(project);
+          queue.push(project);
+        }
+      }
+    }
+  }
+  return projects.filter((p) => chosen.has(p));
+}
+function asProxy(value) {
+  const proxy = value;
+  return proxy && typeof proxy === "object" && typeof proxy.server === "string" ? proxy : void 0;
+}
+function baseUrlTargets(config, argv = process.argv) {
+  const projects = config.projects?.length ? config.projects : [{ name: "", use: config.use }];
+  const targets = /* @__PURE__ */ new Map();
+  for (const project of selectedProjects(projects, argv)) {
+    const url = project.use?.baseURL;
+    if (typeof url !== "string" || !/^https?:\/\//i.test(url)) continue;
+    const target = targets.get(url);
+    if (target) {
+      if (project.name) target.projects.push(project.name);
+      continue;
+    }
+    targets.set(url, {
+      url,
+      projects: project.name ? [project.name] : [],
+      ignoreHTTPSErrors: project.use?.ignoreHTTPSErrors === true,
+      proxy: asProxy(project.use?.proxy)
+    });
+  }
+  return [...targets.values()];
+}
+function requestError(error) {
+  const first = errorMessage(error).split("\n")[0].trim();
+  return first.replace(/^apiRequestContext\.\w+:\s*/, "");
+}
+var playwrightProbe = async (target, timeoutMs) => {
+  const { request } = await import("@playwright/test");
+  const context = await request.newContext({ ignoreHTTPSErrors: target.ignoreHTTPSErrors, proxy: target.proxy });
+  try {
+    const response = await context.get(target.url, { timeout: timeoutMs, maxRedirects: 0, failOnStatusCode: false });
+    return { status: response.status() };
+  } catch (error) {
+    return { error: requestError(error) };
+  } finally {
+    await context.dispose().catch(() => {
+    });
+  }
+};
+async function checkBaseUrl(target, options = {}) {
+  const attempts = Math.max(1, options.attempts ?? BASE_URL_CHECK_ATTEMPTS);
+  const timeoutMs = options.timeoutMs ?? BASE_URL_CHECK_TIMEOUT_MS;
+  const delayMs = options.delayMs ?? BASE_URL_CHECK_DELAY_MS;
+  const probe = options.probe ?? playwrightProbe;
+  let reason = "";
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const outcome = await probe(target, timeoutMs);
+    if ("status" in outcome) {
+      const gateway = GATEWAY_ANSWERS[outcome.status];
+      if (!gateway) return null;
+      reason = `${outcome.status} ${gateway}`;
+    } else {
+      reason = outcome.error;
+    }
+    if (attempt < attempts) await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+  }
+  return `${reason} (${attempts} ${attempts === 1 ? "attempt" : "attempts"})`;
+}
+async function checkBaseUrls(config, options = {}) {
+  const targets = baseUrlTargets(config, options.argv);
+  const reasons = await Promise.all(targets.map((target) => checkBaseUrl(target, options)));
+  const down = targets.flatMap((target, i) => reasons[i] ? [{ target, reason: reasons[i] }] : []);
+  if (down.length === 0) return targets;
+  const lines = down.map(({ target, reason }) => {
+    const used = target.projects.length > 0 ? ` (${target.projects.join(", ")})` : "";
+    return `  ${target.url}${used}: ${reason}`;
+  });
+  const message = [
+    `[Piwi Dashboard] The app under test did not answer, so no test ran:`,
+    ...lines,
+    `Bring the environment back and run again, or set checkBaseUrl: false (PIWI_CHECK_BASE_URL=false) to run the tests anyway.`
+  ].join("\n");
+  const error = new Error(message);
+  error.stack = message;
+  throw error;
+}
+
 // src/internal/manifest/collect.ts
 var fs4 = __toESM(require("fs"));
 var path4 = __toESM(require("path"));
@@ -712,6 +846,10 @@ function createGlobalSetup(options, userSetup) {
       if (userSetup) return userSetup(config);
       return;
     }
+    if (opts.checkBaseUrl === true) {
+      const checked = await checkBaseUrls(config ?? {});
+      for (const target of checked) logger.debug(`Base URL answered: ${target.url}`);
+    }
     if (opts.enabled === false || !opts.serverUrl) {
       logger.info("Not enabled \u2014 set PIWI_DASHBOARD_URL or serverUrl to enable.");
       if (userSetup) return userSetup(config);

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { FullConfig, Suite, TestCase, TestResult, FullResult } from '@playwright/test/reporter';
 import { PlaywrightTestConfig, Locator, TestType, Page, Fixtures, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions } from '@playwright/test';
 export { PlaywrightTestConfig } from '@playwright/test';
-export { PiwiFixtures, extendPiwiFixtures, piwiFixtures } from './internal/capture/capture-fixtures.js';
+export { PiwiFixtures, PiwiWorkerFixtures, extendPiwiFixtures, piwiFixtures } from './internal/capture/capture-fixtures.js';
 import '@piwitests/picker-dom';
 import '@piwitests/core/wire';
 import '@piwitests/core/code-reach';
@@ -100,6 +100,35 @@ interface PiwiDashboardOptions {
      * `false`. Can also be forced off with `PIWI_CAPTURE_SERVER_TRACES=false`.
      */
     captureServerTraces?: boolean;
+    /**
+     * Keep a ledger of the browsers, contexts, pages and API request contexts each
+     * test opens, and list at the end of the run the ones left open after the
+     * scope that created them ended (a context a test never closed, a `beforeAll`
+     * context no `afterAll` closes, a browser a test launched itself), the pages
+     * opened and never used, and the pages, listeners and route handlers piling up
+     * on a page or context that lives across tests. Each finding names the line or
+     * the fixture that opened the object. Rides the capture fixtures and costs a
+     * few bookkeeping steps per test. Also samples the run's processes and the
+     * machine, with or without the fixtures, and prints what the run cost: CPU by
+     * process, time spent waiting for a CPU, peak memory and disk. The findings,
+     * the run's cost and each test's go to the dashboard with the run, on its
+     * Resources tab. Defaults to `true`. Set to `false` (or
+     * `PIWI_CAPTURE_RESOURCES=false`) to turn both off.
+     */
+    captureResources?: boolean;
+    /**
+     * What the capture fixtures do when a test leaves open a browser, context,
+     * page or API request context that the test itself opened (its body or its
+     * `beforeEach`/`afterEach` hooks; a fixture's objects are the fixture's):
+     * `'report'` lists it in the end-of-run summary, `'fail'` also fails the test
+     * with the line that opened it, and `'close'` closes it when the test ends and
+     * still lists it. A `beforeAll` object left open is only ever reported. Each
+     * test is judged when it ends, so a test that hands what it opened to the next
+     * one fails under `'fail'` and loses it under `'close'`: open such objects in
+     * `beforeAll` and close them in `afterAll`. Defaults to `'report'`. Can also
+     * be set with `PIWI_LEAK_CHECK`.
+     */
+    leakCheck?: 'report' | 'fail' | 'close';
     /**
      * 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
@@ -136,6 +165,20 @@ interface PiwiDashboardOptions {
      * to opt out and let Playwright's own defaults stand.
      */
     defaultCapture?: boolean;
+    /**
+     * Check that each `baseURL` the run's projects use answers before any worker
+     * starts, and stop the run with a message naming the ones that do not, so a
+     * suite never runs against an environment that is down. Any HTTP answer
+     * counts (a redirect or a 404 included) except a 502, 503 or 504 from a
+     * gateway; each base URL gets three tries of 10 seconds, 2 seconds apart,
+     * sent with the project's `ignoreHTTPSErrors` and `proxy`. A stopped run
+     * runs no test and reaches no dashboard. The check runs in the reporter's
+     * global setup, after `webServer` has started and before the config's own
+     * `globalSetup`, so leave it off when that setup is what starts the app. Only
+     * the projects `--project` selects are checked. **Defaults to `false`**. Can
+     * also be set with `PIWI_CHECK_BASE_URL=true`.
+     */
+    checkBaseUrl?: 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
@@ -299,6 +342,10 @@ interface PiwiDashboardOptions {
  * The server-run ID and a one-time token are written to a temp file so the
  * reporter instance can pick them up during the streaming handshake.
  *
+ * With `checkBaseUrl`, every `baseURL` the run's projects use is checked first,
+ * and the setup throws, stopping the run before any worker starts, when one
+ * does not answer.
+ *
  * @param options   Piwi Dashboard options (uses `serverUrl`, `projectName`, …).
  * @param userSetup An existing global setup to chain after the Piwi registration.
  */
@@ -375,6 +422,20 @@ declare class PiwiDashboardReporter {
     private filterDetails;
     /** Configured `maxFailures` (0 = unlimited) — disambiguates an interrupted run's unrun reason. */
     private maxFailures;
+    /** The resource censuses the capture fixtures attached, one per test attempt. */
+    private resourceCensuses;
+    /** Lifecycle steps of the tests that ran without the fixtures. */
+    private lifecycleTallies;
+    /** The user fixtures set up by the tests that left a page unused, by test id. */
+    private fixturesByTest;
+    /** The file workers append their shutdown census to, set in `onBegin`. */
+    private resourcesFile;
+    /** Samples the run's processes and the machine from `onBegin` to `onEnd`. */
+    private sampler;
+    /** Bytes of the files the tests attached, by kind. */
+    private artifactBytes;
+    /** The run's resource report for the dashboard, built in `onEnd`. */
+    private resourceReport;
     private httpClient;
     private uploader;
     private fileHandler;
@@ -408,6 +469,17 @@ declare class PiwiDashboardReporter {
     onStepEnd(test: TestCase | undefined, _result: TestResult | undefined, step: any): void;
     /** Playwright reporter hook: called when an individual test finishes */
     onTestEnd(test: TestCase, result: TestResult): void;
+    /**
+     * Add up the files a test attached, and keep its resource census; for a test
+     * that ran without the capture fixtures, tally the browsers and contexts its
+     * steps opened and closed.
+     */
+    private collectResources;
+    /**
+     * Print what the run left open or opened for nothing, from the censuses and
+     * the workers' shutdown file, then what the run cost the machine.
+     */
+    private reportResources;
     /**
      * Synthesize `didnotrun` cases for tests Playwright planned but never reported
      * (no `onTestEnd`) — typically because `maxFailures` cut the run short. These
@@ -504,6 +576,48 @@ declare function extendPiwiAi<TestArgs extends FixtureArgs, WorkerArgs extends F
     page: Page & PiwiAi;
 }, WorkerArgs>;
 
+/** How the code a recording writes looks, for everyone working in the repository. */
+interface PiwiCodegenConfig {
+    /**
+     * After a step that leads to another page, wait for that page's URL and for the next step's element before going
+     * on. `true` by default. A call to one of your own functions waits for its pages itself either way.
+     */
+    pageWaits?: boolean;
+    /**
+     * `literal` (default): typed values are written in the code, and only passwords are read from the environment.
+     * `env`: every typed value is read from an environment variable named after its field.
+     */
+    values?: 'literal' | 'env';
+    /**
+     * What those environment variables start with: `E2E_` by default, as in `E2E_PASSWORD`. Upper-case letters, digits
+     * and underscores, starting with a letter.
+     */
+    envPrefix?: string;
+    /**
+     * `page` wraps the steps of each page in `await test.step('<path>', …)`, in a test (not in a page object or a
+     * helper); `none` (default) does not.
+     */
+    testSteps?: 'none' | 'page';
+    /** Tags a new test gets, such as `@recorded`; a missing `@` is added. */
+    tags?: string[];
+    /** Annotations a new test gets, such as `{ type: 'piwi:owner', description: '@shop-team' }`. */
+    annotations?: Array<{
+        type: string;
+        description?: string;
+    }>;
+}
+/** Piwi's section of a Playwright config, `'@piwi'`. */
+interface PiwiConfig {
+    /** How the code a recording writes looks. */
+    codegen?: PiwiCodegenConfig;
+}
+declare module '@playwright/test' {
+    interface Config<TestArgs, WorkerArgs> {
+        /** Piwi's options, read from the repository by the editor extensions: how the code a recording writes looks. */
+        '@piwi'?: PiwiConfig;
+    }
+}
+
 /**
  * Public API of `@piwitests/reporter`.
  *
@@ -513,4 +627,4 @@ declare function extendPiwiAi<TestArgs extends FixtureArgs, WorkerArgs extends F
  * exported from this file, it isn't part of the supported API.
  */
 
-export { type AiMode, type AiOnMiss, type PiwiAi, type PiwiDashboardOptions, PiwiDashboardReporter, type ResolveSelectionOptions, type ResolveSelectionResult, createGlobalSetup, PiwiDashboardReporter as default, extendPiwiAi, piwiAiFixtures, resolveSelection, wrapConfig };
+export { type AiMode, type AiOnMiss, type PiwiAi, type PiwiCodegenConfig, type PiwiConfig, type PiwiDashboardOptions, PiwiDashboardReporter, type ResolveSelectionOptions, type ResolveSelectionResult, createGlobalSetup, PiwiDashboardReporter as default, extendPiwiAi, piwiAiFixtures, resolveSelection, wrapConfig };