@piwitests/reporter 0.14.0 → 0.16.0

package/README.md

@@ -92,6 +92,7 @@ export default defineConfig({
 | `collectScmInfo`            | boolean  | `true`                    | Auto-collect git commit, branch, author                                |
 | `collectCiInfo`             | boolean  | `true`                    | Auto-collect CI environment info                                       |
 | `collectPerformanceMetrics` | boolean  | `true`                    | Collect step timings, network requests and web vitals from the fixture |
+| `outputFile`                | string   | —                         | Write a JSON file with the run URL/id/status so CI can consume it (see below) |
 | `apiKey`                    | string   | —                         | API key for authentication (preferred for CI)                          |
 | `username`                  | string   | —                         | Username for dashboard login (use `apiKey` instead when possible)      |
 | `password`                  | string   | —                         | Password for dashboard login (used with `username`)                    |
@@ -209,6 +210,51 @@ When `collectCiInfo` is enabled (default), the reporter auto-detects:
 - **Travis CI** — build number/URL, job number
 - **Azure Pipelines** — build number, build ID/URL, job name
 
+## Publishing the run URL to CI
+
+After a run is submitted, the reporter surfaces the dashboard run URL so a later
+CI step (a custom email, a Slack message, a deploy gate) can pick it up without
+scraping the log. The URL is always printed as `View run: <url>`, and in
+addition:
+
+- **Any CI — JSON output file.** Set `outputFile` (or `PIWI_OUTPUT_FILE`) and the
+  reporter writes a small JSON file when the run lands:
+
+  ```json
+  { "runUrl": "https://piwi.example.com/test-runs/1234", "runId": 1234, "projectId": 5, "projectName": "checkout", "status": "passed", "ciBuildUrl": "https://ci.example.com/build/9" }
+  ```
+
+  Read it from any pipeline, e.g. `node -e "console.log(require('./piwi-run.json').runUrl)"`
+  (portable) or `cat piwi-run.json` and parse it in your email step. In Jenkins,
+  `def run = readJSON file: 'piwi-run.json'` then use `run.runUrl`.
+
+- **GitHub Actions (automatic).** When `GITHUB_ACTIONS` is set, the reporter
+  appends step outputs to `$GITHUB_OUTPUT` (`piwi_run_url`, `piwi_run_id`,
+  `piwi_project_id`, `piwi_run_status`), writes a markdown link to the job
+  summary, and prints a `::notice::` annotation. Give the test step an `id` and a
+  downstream step can read it:
+
+  ```yaml
+  - id: tests
+    run: npx playwright test
+  - run: echo "Results at ${{ steps.tests.outputs.piwi_run_url }}"
+  ```
+
+- **GitLab CI (automatic).** When `GITLAB_CI` is set, the reporter writes a
+  dotenv report (`piwi.env` by default, override with `PIWI_DOTENV_FILE`).
+  Declare it so later jobs inherit `$PIWI_RUN_URL`:
+
+  ```yaml
+  test:
+    script: npx playwright test
+    artifacts:
+      reports:
+        dotenv: piwi.env
+  email:
+    needs: [test]
+    script: ./send-email.sh "$PIWI_RUN_URL"
+  ```
+
 ## How It Works
 
 1. When tests start, the reporter creates a run on the server (streaming mode) or collects results locally (batch mode)

package/dist/global-setup-module.js

@@ -57,6 +57,7 @@ var DEFAULTS = {
   collectPerformanceMetrics: true,
   captureLocators: true,
   capturePageState: true,
+  captureServerTraces: true,
   streaming: true,
   streamingBatchSize: 5,
   streamingBatchDelay: 2e3,
@@ -83,8 +84,10 @@ var PIWI_ENV_KEYS = {
   uploadReport: "PIWI_UPLOAD_REPORT",
   captureLocators: "PIWI_CAPTURE_LOCATORS",
   capturePageState: "PIWI_CAPTURE_PAGE_STATE",
+  captureServerTraces: "PIWI_CAPTURE_SERVER_TRACES",
   inspectOnFailure: "PIWI_INSPECT_ON_FAIL",
-  pickLocatorOnFailure: "PIWI_PICK_LOCATOR_ON_FAIL"
+  pickLocatorOnFailure: "PIWI_PICK_LOCATOR_ON_FAIL",
+  outputFile: "PIWI_OUTPUT_FILE"
 };
 function readBool(val) {
   if (val === void 0) return void 0;
@@ -107,8 +110,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: "captureServerTraces", env: PIWI_ENV_KEYS.captureServerTraces, kind: "bool" },
   { option: "inspectOnFailure", env: PIWI_ENV_KEYS.inspectOnFailure, kind: "bool" },
-  { option: "pickLocatorOnFailure", env: PIWI_ENV_KEYS.pickLocatorOnFailure, kind: "bool" }
+  { option: "pickLocatorOnFailure", env: PIWI_ENV_KEYS.pickLocatorOnFailure, kind: "bool" },
+  { option: "outputFile", env: PIWI_ENV_KEYS.outputFile, kind: "string" }
 ];
 function resolveOptions(raw) {
   const env = process.env;

package/dist/index.d.ts

@@ -41,6 +41,16 @@ interface PiwiDashboardOptions extends PlaywrightTestConfig {
      * also be forced off with `PIWI_CAPTURE_PAGE_STATE=false`.
      */
     capturePageState?: 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
+     * instrumentation plugin (e.g. `@piwitests/instrumentation`). The spans show
+     * up next to the network request in the dashboard and feed AI diagnosis. Free
+     * when no instrumentation is present (the header is simply absent). Defaults
+     * to `true`; automatically disabled when `collectPerformanceMetrics` is
+     * `false`. Can also be forced off with `PIWI_CAPTURE_SERVER_TRACES=false`.
+     */
+    captureServerTraces?: 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
@@ -97,6 +107,15 @@ interface PiwiDashboardOptions extends PlaywrightTestConfig {
     tags?: string[];
     /** Additional custom metadata as key-value pairs */
     customData?: Record<string, unknown>;
+    /**
+     * Write a JSON file with the submitted run's dashboard URL, id, project id and
+     * status after the run lands, so a CI pipeline can consume it (e.g. feed the
+     * run URL into a custom email step). Any CI can read the file. GitHub Actions
+     * step outputs / job summary and GitLab dotenv reports are emitted
+     * automatically when running under those systems, regardless of this option.
+     * Can also be set with `PIWI_OUTPUT_FILE`.
+     */
+    outputFile?: string;
     /** Enable verbose logging for debugging. Defaults to `false`. */
     verbose?: boolean;
 }

package/dist/index.js

@@ -40,7 +40,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/public/reporter.ts
-var path12 = __toESM(require("path"));
+var path13 = __toESM(require("path"));
 
 // src/internal/config/env.ts
 var DEFAULTS = {
@@ -53,6 +53,7 @@ var DEFAULTS = {
   collectPerformanceMetrics: true,
   captureLocators: true,
   capturePageState: true,
+  captureServerTraces: true,
   streaming: true,
   streamingBatchSize: 5,
   streamingBatchDelay: 2e3,
@@ -79,8 +80,10 @@ var PIWI_ENV_KEYS = {
   uploadReport: "PIWI_UPLOAD_REPORT",
   captureLocators: "PIWI_CAPTURE_LOCATORS",
   capturePageState: "PIWI_CAPTURE_PAGE_STATE",
+  captureServerTraces: "PIWI_CAPTURE_SERVER_TRACES",
   inspectOnFailure: "PIWI_INSPECT_ON_FAIL",
-  pickLocatorOnFailure: "PIWI_PICK_LOCATOR_ON_FAIL"
+  pickLocatorOnFailure: "PIWI_PICK_LOCATOR_ON_FAIL",
+  outputFile: "PIWI_OUTPUT_FILE"
 };
 function readBool(val) {
   if (val === void 0) return void 0;
@@ -103,8 +106,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: "captureServerTraces", env: PIWI_ENV_KEYS.captureServerTraces, kind: "bool" },
   { option: "inspectOnFailure", env: PIWI_ENV_KEYS.inspectOnFailure, kind: "bool" },
-  { option: "pickLocatorOnFailure", env: PIWI_ENV_KEYS.pickLocatorOnFailure, kind: "bool" }
+  { option: "pickLocatorOnFailure", env: PIWI_ENV_KEYS.pickLocatorOnFailure, kind: "bool" },
+  { option: "outputFile", env: PIWI_ENV_KEYS.outputFile, kind: "string" }
 ];
 function resolveOptions(raw) {
   const env = process.env;
@@ -139,6 +144,9 @@ function applyOptionsToEnv(options) {
   if (options.capturePageState === false || options.collectPerformanceMetrics === false)
     env[PIWI_ENV_KEYS.capturePageState] = "false";
   else if (options.capturePageState === true) env[PIWI_ENV_KEYS.capturePageState] = "true";
+  if (options.captureServerTraces === false || options.collectPerformanceMetrics === false)
+    env[PIWI_ENV_KEYS.captureServerTraces] = "false";
+  else if (options.captureServerTraces === true) env[PIWI_ENV_KEYS.captureServerTraces] = "true";
   if (options.inspectOnFailure !== void 0) env[PIWI_ENV_KEYS.inspectOnFailure] = String(options.inspectOnFailure);
   if (options.pickLocatorOnFailure !== void 0)
     env[PIWI_ENV_KEYS.pickLocatorOnFailure] = String(options.pickLocatorOnFailure);
@@ -353,6 +361,7 @@ function toWireTestCase(tc) {
     location: rest.location,
     status: rest.status,
     duration: rest.duration,
+    timeout: rest.timeout ?? null,
     error: rest.error,
     retries: rest.retries,
     workerIndex: rest.workerIndex ?? null,
@@ -407,11 +416,6 @@ function serializeRun(payload, opts) {
   return body;
 }
 
-// src/internal/support/run-url.ts
-function runUrl(serverUrl, runId) {
-  return `${serverUrl.replace(/\/+$/, "")}/test-runs/${runId}`;
-}
-
 // src/internal/submit/uploader.ts
 var Uploader = class {
   /**
@@ -434,7 +438,6 @@ var Uploader = class {
     this.logger.info(`Successfully uploaded test results`);
     if (response.testRunId) {
       this.logger.info(`Test Run ID: ${response.testRunId}, Project ID: ${response.projectId}`);
-      this.logger.info(`View run: ${runUrl(this.httpClient.baseUrl, response.testRunId)}`);
     }
     return response;
   }
@@ -450,7 +453,6 @@ var Uploader = class {
     this.logger.info(`Successfully uploaded test results with files`);
     if (response.testRunId) {
       this.logger.info(`Test Run ID: ${response.testRunId}, Project ID: ${response.projectId}`);
-      this.logger.info(`View run: ${runUrl(this.httpClient.baseUrl, response.testRunId)}`);
     }
     if (response.reports) {
       for (const r of response.reports) this.logger.info(`${r.label}: ${r.path}`);
@@ -1157,6 +1159,11 @@ function readSetupInfo(projectName) {
   return null;
 }
 
+// src/internal/support/run-url.ts
+function runUrl(serverUrl, runId) {
+  return `${serverUrl.replace(/\/+$/, "")}/test-runs/${runId}`;
+}
+
 // src/internal/streaming/stream-manager.ts
 var StreamManager = class {
   /**
@@ -2001,6 +2008,90 @@ function buildErrorText(result) {
   return text;
 }
 
+// src/internal/support/ci-output.ts
+var fs12 = __toESM(require("fs"));
+var path12 = __toESM(require("path"));
+function emitRunOutputs(output, logger, outputFile, env = process.env) {
+  logger.info(`View run: ${output.runUrl}`);
+  if (outputFile) writeOutputFile(outputFile, output, logger);
+  if (env.GITHUB_ACTIONS) emitGitHubActions(output, env, logger);
+  if (env.GITLAB_CI) emitGitLabDotenv(output, env, logger);
+}
+function writeOutputFile(file, output, logger) {
+  try {
+    const dir = path12.dirname(file);
+    if (dir && dir !== ".") fs12.mkdirSync(dir, { recursive: true });
+    fs12.writeFileSync(
+      file,
+      JSON.stringify(
+        {
+          runUrl: output.runUrl,
+          runId: output.runId,
+          projectId: output.projectId ?? null,
+          projectName: output.projectName,
+          status: output.status,
+          ciBuildUrl: output.ciBuildUrl ?? null
+        },
+        null,
+        2
+      ) + "\n"
+    );
+    logger.info(`Wrote run output to ${file}`);
+  } catch (error) {
+    logger.warn(`Failed to write run output file '${file}': ${errorMessage(error)}`);
+  }
+}
+function emitGitHubActions(output, env, logger) {
+  const pairs = [
+    ["piwi_run_url", output.runUrl],
+    ["piwi_run_id", String(output.runId)],
+    ["piwi_run_status", output.status]
+  ];
+  if (output.projectId != null) pairs.push(["piwi_project_id", String(output.projectId)]);
+  if (env.GITHUB_OUTPUT) {
+    appendFileLines(
+      env.GITHUB_OUTPUT,
+      pairs.map(([k, v]) => `${k}=${v}`),
+      logger,
+      "step output"
+    );
+  }
+  if (env.GITHUB_STEP_SUMMARY) {
+    appendFileLines(
+      env.GITHUB_STEP_SUMMARY,
+      ["### Piwi test run", "", `[View run](${output.runUrl}) \u2014 **${output.status}**`, ""],
+      logger,
+      "step summary"
+    );
+  }
+  process.stdout.write(`::notice title=Piwi test run::${output.runUrl}
+`);
+}
+function emitGitLabDotenv(output, env, logger) {
+  const file = env.PIWI_DOTENV_FILE || "piwi.env";
+  const lines = [`PIWI_RUN_URL=${output.runUrl}`, `PIWI_RUN_ID=${output.runId}`, `PIWI_RUN_STATUS=${output.status}`];
+  if (output.projectId != null) lines.push(`PIWI_PROJECT_ID=${output.projectId}`);
+  if (output.ciBuildUrl) lines.push(`PIWI_CI_BUILD_URL=${output.ciBuildUrl}`);
+  try {
+    fs12.writeFileSync(file, lines.join("\n") + "\n");
+    logger.info(`Wrote GitLab dotenv report to ${file} (declare it as artifacts:reports:dotenv)`);
+  } catch (error) {
+    logger.warn(`Failed to write GitLab dotenv file '${file}': ${errorMessage(error)}`);
+  }
+}
+function appendFileLines(file, lines, logger, label) {
+  try {
+    fs12.appendFileSync(file, lines.join("\n") + "\n");
+  } catch (error) {
+    logger.warn(`Failed to write GitHub Actions ${label}: ${errorMessage(error)}`);
+  }
+}
+function ciBuildUrlFromMetadata(metadata) {
+  const ci = metadata?.ci;
+  if (!ci) return void 0;
+  return ci.buildUrl || ci.pipelineUrl || ci.jobUrl || void 0;
+}
+
 // src/internal/submit/run-submitter.ts
 var RunSubmitter = class {
   /**
@@ -2045,13 +2136,29 @@ var RunSubmitter = class {
       this.logger.error(`Authentication failed: ${errorMessage(error)}`);
       throw error;
     }
+    let outcome = { done: false, output: null };
     if (sm?.enabled && sm?.runId != null) {
-      if (await this.tryFinishStreaming(run, overallStatus, duration, auth)) return;
+      outcome = await this.tryFinishStreaming(run, overallStatus, duration, auth);
+    }
+    if (!outcome.done && (this.hasReports(run) || run.options.uploadTraces)) {
+      outcome = await this.tryUploadWithFiles(run, overallStatus, duration, auth);
     }
-    if (this.hasReports(run) || run.options.uploadTraces) {
-      if (await this.tryUploadWithFiles(run, overallStatus, duration, auth)) return;
+    if (!outcome.done) {
+      outcome = await this.tryUploadJSON(run, overallStatus, duration, auth);
     }
-    await this.tryUploadJSON(run, overallStatus, duration, auth);
+    if (outcome.output) emitRunOutputs(outcome.output, this.logger, run.options.outputFile);
+  }
+  /** Assemble a CI-facing run output, or `null` when the server returned no run id. */
+  buildOutput(runId, projectId, run, status) {
+    if (runId == null) return null;
+    return {
+      runUrl: runUrl(this.httpClient.baseUrl, runId),
+      runId,
+      projectId,
+      projectName: run.options.projectName,
+      status,
+      ciBuildUrl: ciBuildUrlFromMetadata(run.metadata)
+    };
   }
   hasReports(run) {
     return !!run.options.uploadReport || (run.options.reports?.length ?? 0) > 0;
@@ -2122,9 +2229,6 @@ var RunSubmitter = class {
       }
       await this.httpClient.postJSON(`/api/test-runs/${sm.runId}/finish`, finishBody, auth);
       this.logger.info(`Successfully finalized streaming run #${sm.runId}`);
-      if (run.options.serverUrl) {
-        this.logger.info(`View run: ${runUrl(run.options.serverUrl, sm.runId)}`);
-      }
       this.recovery.clear();
       if (this.hasReports(run)) {
         try {
@@ -2139,22 +2243,22 @@ var RunSubmitter = class {
           this.logger.warn(`Failed to upload reports for streaming run: ${errorMessage(error)}`);
         }
       }
-      return true;
+      return { done: true, output: this.buildOutput(sm.runId, void 0, run, overallStatus) };
     } catch (error) {
       this.logger.warn(`Failed to finalize streaming run: ${errorMessage(error)}`);
       this.logger.info("Falling back to batch upload...");
-      return false;
+      return { done: false, output: null };
     }
   }
   async tryUploadWithFiles(run, overallStatus, duration, auth) {
     try {
-      await this.uploader.uploadWithFiles(
+      const response = await this.uploader.uploadWithFiles(
         this.buildRunPayload(run, overallStatus, duration),
         this.reportOptions(run),
         auth
       );
       this.recovery.clear();
-      return true;
+      return { done: true, output: this.buildOutput(response?.testRunId, response?.projectId, run, overallStatus) };
     } catch (error) {
       if (error instanceof HttpError && error.status === 401 && !auth) {
         this.logAuthRequired(run.options.serverUrl);
@@ -2162,14 +2266,15 @@ var RunSubmitter = class {
       }
       this.logger.warn(`Failed to upload with files: ${errorMessage(error)}`);
       this.logger.info("Falling back to JSON upload...");
-      return false;
+      return { done: false, output: null };
     }
   }
   async tryUploadJSON(run, overallStatus, duration, auth) {
     const payload = this.buildRunPayload(run, overallStatus, duration);
     try {
-      await this.uploader.uploadJSON(payload, auth);
+      const response = await this.uploader.uploadJSON(payload, auth);
       this.recovery.clear();
+      return { done: true, output: this.buildOutput(response?.testRunId, response?.projectId, run, overallStatus) };
     } catch (error) {
       if (error instanceof HttpError && error.status === 401 && !auth) {
         this.logAuthRequired(run.options.serverUrl);
@@ -2180,6 +2285,7 @@ var RunSubmitter = class {
         `Saved a local recovery copy \u2014 it will be uploaded automatically on your next test run. If this keeps happening, check that serverUrl (${run.options.serverUrl ?? "not set"}) is correct and reachable.`
       );
       this.recovery.save(serializeRun(payload, { includeTestCases: true }));
+      return { done: true, output: null };
     }
   }
   /** Log one actionable line explaining how to fix a 401 caused by a missing credential. */
@@ -2192,7 +2298,7 @@ var RunSubmitter = class {
 
 // src/public/reporter.ts
 function testLocation(test) {
-  const relativeFilePath = path12.relative(process.cwd(), test.location.file).split(path12.sep).join("/");
+  const relativeFilePath = path13.relative(process.cwd(), test.location.file).split(path13.sep).join("/");
   return `${relativeFilePath}:${test.location.line}:${test.location.column}`;
 }
 var PiwiDashboardReporter = class {
@@ -2373,6 +2479,9 @@ var PiwiDashboardReporter = class {
       location: testLocation(test),
       status,
       duration: result.duration,
+      // Effective per-test timeout (reflects project config + describe-level
+      // overrides). `0` means unbounded; kept as-is so the dashboard can flag it.
+      timeout: test.timeout ?? null,
       error: buildErrorText(result),
       retries: result.retry,
       workerIndex: workerIndexOf(result),
@@ -2448,6 +2557,7 @@ var PiwiDashboardReporter = class {
         location: testLocation(test),
         status: "didnotrun",
         duration: 0,
+        timeout: test.timeout ?? null,
         error: null,
         retries: 0,
         workerIndex: null,
@@ -2500,7 +2610,7 @@ var PiwiDashboardReporter = class {
 var import_node_zlib = require("zlib");
 
 // src/internal/capture/locator-healing.ts
-var path13 = __toESM(require("path"));
+var path14 = __toESM(require("path"));
 
 // ../packages/core/src/locator-fingerprint.ts
 var PRESENT_SIMILARITY = 0.8;
@@ -3057,10 +3167,10 @@ function captureCallerLocation(stack = new Error().stack ?? "") {
     }
     let rel = file;
     try {
-      rel = path13.relative(process.cwd(), file);
+      rel = path14.relative(process.cwd(), file);
     } catch {
     }
-    rel = rel.split(path13.sep).join("/");
+    rel = rel.split(path14.sep).join("/");
     if (rel.startsWith("./")) rel = rel.slice(2);
     return `${rel}:${m[3]}:${m[4]}`;
   }
@@ -3103,7 +3213,7 @@ function inspectionGateFromTestInfo(testInfo, enabled = process.env.PIWI_INSPECT
 }
 
 // src/internal/capture/pick-on-failure.ts
-var path14 = __toESM(require("path"));
+var path15 = __toESM(require("path"));
 var ANSI_RE = /\[[0-9;]*m/g;
 function endOfString(s, start) {
   const q = s[start];
@@ -3197,7 +3307,7 @@ ${err.stack ?? ""}`.replace(ANSI_RE, "");
     const parsed = parseLeafLocatorExpression(line[1].trim());
     if (!parsed) continue;
     const loc = err.location;
-    const location = loc ? `${path14.relative(process.cwd(), loc.file).split(path14.sep).join("/")}:${loc.line}:${loc.column}` : null;
+    const location = loc ? `${path15.relative(process.cwd(), loc.file).split(path15.sep).join("/")}:${loc.line}:${loc.column}` : null;
     return { method: parsed.method, args: parsed.args, location };
   }
   return null;
@@ -4528,6 +4638,13 @@ function instrumentPage(page) {
             } catch {
             }
           }
+          const traceHeader = headers["x-piwi-trace"];
+          if (traceHeader && process.env.PIWI_CAPTURE_SERVER_TRACES !== "false") {
+            try {
+              entry.serverTraces = JSON.parse((0, import_node_zlib.gunzipSync)(Buffer.from(traceHeader, "base64")).toString("utf-8"));
+            } catch {
+            }
+          }
         }
         sink.networkRequests.push(entry);
       } catch {

package/dist/internal/capture/capture-fixtures.js

@@ -2085,6 +2085,13 @@ function instrumentPage(page) {
             } catch {
             }
           }
+          const traceHeader = headers["x-piwi-trace"];
+          if (traceHeader && process.env.PIWI_CAPTURE_SERVER_TRACES !== "false") {
+            try {
+              entry.serverTraces = JSON.parse((0, import_node_zlib.gunzipSync)(Buffer.from(traceHeader, "base64")).toString("utf-8"));
+            } catch {
+            }
+          }
         }
         sink.networkRequests.push(entry);
       } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piwitests/reporter",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Playwright reporter for sending test results to Piwi Dashboard",
   "url": "https://github.com/PiwiTests/platform",
   "homepage": "https://piwitests.github.io",