@piwitests/reporter 0.45.0 → 0.46.0

package/dist/global-setup-module.js

@@ -88,6 +88,7 @@ var DEFAULTS = {
   sampleAriaOnPass: true,
   uploadManifest: true,
   defaultCapture: true,
+  checkBaseUrl: false,
   streaming: true,
   streamingBatchSize: 5,
   streamingBatchDelay: 2e3,
@@ -130,6 +131,7 @@ var PIWI_ENV_KEYS = {
   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",
@@ -177,6 +179,7 @@ var ENV_FALLBACK_SPECS = [
   { 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" }
@@ -619,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"));
@@ -718,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

@@ -165,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
@@ -328,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.
  */
@@ -558,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`.
  *
@@ -567,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 };