playwright-ctrf-json-reporter 0.0.28 → 0.0.30-next.0

package/README.md

@@ -165,6 +165,64 @@ The test object in the report includes the following [CTRF properties](https://c
 | `screenshot`  | String           | Optional | A base64 encoded screenshot taken during the test.                                  |
 | `steps`       | Array of Objects | Optional | Individual steps in the test, especially for BDD-style testing.                     |
 
+## Extra
+
+The `extra` field lets you attach custom metadata to individual test results at runtime. This data is merged into the `extra` field of each test in the CTRF report.
+
+See the [CTRF extra specification](https://www.ctrf.io/docs/specification/extra) for full details.
+
+### Usage
+
+Import `ctrf` from the reporter and call `ctrf.extra()` inside any test:
+
+```typescript
+import { test, expect } from '@playwright/test'
+import { ctrf } from 'playwright-ctrf-json-reporter'
+
+test('checkout flow', async ({ page }) => {
+  ctrf.extra({ owner: 'checkout-team', priority: 'P1' })
+
+  // ... test logic ...
+})
+```
+
+You can call it multiple times in a single test:
+
+```typescript
+test('search results', async ({ page }) => {
+  ctrf.extra({ owner: 'search-team' })
+  ctrf.extra({ feature: 'search', environment: 'staging' })
+
+  // ... test logic ...
+
+  ctrf.extra({ customMetric: 'some-value' })
+})
+```
+
+The resulting `extra` field in the CTRF report:
+
+```json
+{
+  "name": "search results",
+  "status": "passed",
+  "duration": 300,
+  "extra": {
+    "owner": "search-team",
+    "feature": "search",
+    "environment": "staging",
+    "customMetric": "some-value"
+  }
+}
+```
+
+### Merge behaviour
+
+| Data type  | Behaviour                           | Example                                                                                                        |
+| ---------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Primitives | Later call overwrites earlier       | `extra({ owner: 'a' })` then `extra({ owner: 'b' })` → `{ owner: 'b' }`                                        |
+| Objects    | Deep merged - nested keys preserved | `extra({ build: { id: '1' } })` then `extra({ build: { url: '...' } })` → `{ build: { id: '1', url: '...' } }` |
+| Arrays     | Concatenated across calls           | `extra({ tags: ['smoke'] })` then `extra({ tags: ['e2e'] })` → `{ tags: ['smoke', 'e2e'] }`                    |
+
 ## Advanced usage
 
 Some features require additional setup or usage considerations.

package/dist/index.cjs

@@ -0,0 +1,534 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ctrf: () => ctrf,
+  default: () => generate_report_default,
+  extra: () => extra
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/generate-report.ts
+var import_node_path = __toESM(require("path"), 1);
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_crypto = __toESM(require("crypto"), 1);
+
+// src/adapter/runtime.ts
+var import_test = require("@playwright/test");
+var CTRF_RUNTIME_MESSAGE_CONTENT_TYPE = "application/vnd.ctrf.message+json";
+var nullTransport = {
+  send: async () => {
+  }
+};
+function createPlaywrightTransport() {
+  let sequence = 0;
+  return {
+    async send(payload) {
+      const tag = `__ctrf_${++sequence}_${Date.now()}`;
+      const data = JSON.stringify(payload);
+      await import_test.test.info().attach(tag, {
+        contentType: CTRF_RUNTIME_MESSAGE_CONTENT_TYPE,
+        body: Buffer.from(data)
+      });
+    }
+  };
+}
+var activeTransport = createPlaywrightTransport();
+var resolveTransport = () => {
+  try {
+    import_test.test.info();
+    return activeTransport;
+  } catch {
+  }
+  return nullTransport;
+};
+async function extra(data) {
+  await resolveTransport().send({ type: "metadata", data });
+}
+var ctrf = { extra };
+
+// src/generate-report.ts
+var GenerateCtrfReport = class {
+  ctrfReport;
+  ctrfEnvironment;
+  reporterConfigOptions;
+  reporterName = "playwright-ctrf-json-reporter";
+  defaultOutputFile = "ctrf-report.json";
+  defaultOutputDir = "ctrf";
+  suite;
+  startTime;
+  constructor(config) {
+    this.reporterConfigOptions = {
+      outputFile: config?.outputFile ?? this.defaultOutputFile,
+      outputDir: config?.outputDir ?? this.defaultOutputDir,
+      minimal: config?.minimal ?? false,
+      screenshot: config?.screenshot ?? false,
+      annotations: config?.annotations ?? false,
+      testType: config?.testType ?? "e2e",
+      appName: config?.appName ?? void 0,
+      appVersion: config?.appVersion ?? void 0,
+      osPlatform: config?.osPlatform ?? void 0,
+      osRelease: config?.osRelease ?? void 0,
+      osVersion: config?.osVersion ?? void 0,
+      buildName: config?.buildName ?? void 0,
+      buildNumber: config?.buildNumber ?? void 0,
+      buildUrl: config?.buildUrl ?? void 0,
+      repositoryName: config?.repositoryName ?? void 0,
+      repositoryUrl: config?.repositoryUrl ?? void 0,
+      branchName: config?.branchName ?? void 0,
+      commit: config?.commit ?? void 0,
+      testEnvironment: config?.testEnvironment ?? void 0
+    };
+    this.ctrfReport = {
+      reportFormat: "CTRF",
+      specVersion: "0.0.0",
+      reportId: import_node_crypto.default.randomUUID(),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      generatedBy: "playwright-ctrf-json-reporter",
+      results: {
+        tool: {
+          name: "playwright"
+        },
+        summary: {
+          tests: 0,
+          passed: 0,
+          failed: 0,
+          pending: 0,
+          skipped: 0,
+          other: 0,
+          start: 0,
+          stop: 0
+        },
+        tests: []
+      }
+    };
+    this.ctrfEnvironment = {};
+  }
+  onBegin(_config, suite) {
+    this.suite = suite;
+    this.startTime = Date.now();
+    this.ctrfReport.results.summary.start = this.startTime;
+    if (!import_node_fs.default.existsSync(
+      this.reporterConfigOptions.outputDir ?? this.defaultOutputDir
+    )) {
+      import_node_fs.default.mkdirSync(
+        this.reporterConfigOptions.outputDir ?? this.defaultOutputDir,
+        { recursive: true }
+      );
+    }
+    this.setEnvironmentDetails(this.reporterConfigOptions);
+    if (this.hasEnvironmentDetails(this.ctrfEnvironment)) {
+      this.ctrfReport.results.environment = this.ctrfEnvironment;
+    }
+    this.setFilename(
+      this.reporterConfigOptions.outputFile ?? this.defaultOutputFile
+    );
+  }
+  onEnd() {
+    this.ctrfReport.results.summary.stop = Date.now();
+    if (this.suite !== void 0) {
+      if (this.suite.allTests().length > 0) {
+        this.processSuite(this.suite);
+        this.ctrfReport.results.summary.suites = this.countSuites(this.suite);
+      }
+    }
+    this.writeReportToFile(this.ctrfReport);
+  }
+  printsToStdio() {
+    return false;
+  }
+  processSuite(suite) {
+    for (const test2 of suite.tests) {
+      this.processTest(test2);
+    }
+    for (const childSuite of suite.suites) {
+      this.processSuite(childSuite);
+    }
+  }
+  processTest(testCase) {
+    if (testCase.results.length === 0) {
+      return;
+    }
+    const latestResult = testCase.results[testCase.results.length - 1];
+    if (latestResult !== void 0) {
+      this.updateCtrfTestResultsFromTestResult(
+        testCase,
+        latestResult,
+        this.ctrfReport
+      );
+      this.updateSummaryFromTestResult(latestResult, this.ctrfReport);
+    }
+  }
+  setFilename(filename) {
+    if (filename.endsWith(".json")) {
+      this.reporterConfigOptions.outputFile = filename;
+    } else {
+      this.reporterConfigOptions.outputFile = `${filename}.json`;
+    }
+  }
+  updateCtrfTestResultsFromTestResult(testCase, testResult, ctrfReport) {
+    const test2 = {
+      name: testCase.title,
+      status: testResult.status === testCase.expectedStatus && testResult.status !== "skipped" ? "passed" : this.mapPlaywrightStatusToCtrf(testResult.status),
+      duration: testResult.duration
+    };
+    if (this.reporterConfigOptions.minimal === false) {
+      test2.start = this.updateStart(testResult.startTime);
+      test2.stop = this.calculateStopTime(
+        testResult.startTime,
+        testResult.duration
+      );
+      test2.message = this.extractFailureDetails(testResult).message;
+      test2.trace = this.extractFailureDetails(testResult).trace;
+      test2.snippet = this.extractFailureDetails(testResult).snippet;
+      test2.rawStatus = testResult.status;
+      test2.tags = testCase.tags ?? [];
+      test2.type = this.reporterConfigOptions.testType ?? "e2e";
+      test2.filePath = testCase.location.file;
+      test2.retries = testResult.retry;
+      test2.flaky = testResult.status === "passed" && testResult.retry > 0;
+      test2.steps = [];
+      if (testResult.steps.length > 0) {
+        testResult.steps.forEach((step) => {
+          this.processStep(test2, step);
+        });
+      }
+      if (this.reporterConfigOptions.screenshot === true) {
+        test2.screenshot = this.extractScreenshotBase64(testResult);
+      }
+      test2.suite = this.buildSuitePath(testCase);
+      if (this.extractMetadata(testResult)?.name !== void 0 || this.extractMetadata(testResult)?.version !== void 0)
+        test2.browser = `${this.extractMetadata(testResult)?.name} ${this.extractMetadata(testResult)?.version}`;
+      test2.attachments = this.filterValidAttachments(testResult.attachments);
+      test2.stdout = testResult.stdout.map(
+        (item) => Buffer.isBuffer(item) ? item.toString() : String(item)
+      );
+      test2.stderr = testResult.stderr.map(
+        (item) => Buffer.isBuffer(item) ? item.toString() : String(item)
+      );
+      if (this.reporterConfigOptions.annotations !== void 0) {
+        test2.extra = { annotations: testCase.annotations };
+      }
+      const runtimeData = this.extractRuntimeData(testResult);
+      if (runtimeData !== null) {
+        test2.extra = { ...test2.extra, ...runtimeData };
+      }
+      if (testCase.results.length > 1) {
+        const retryResults = testCase.results.slice(0, -1);
+        test2.retryAttempts = [];
+        for (let i = 0; i < retryResults.length; i++) {
+          const retryResult = retryResults[i];
+          const retryAttempt = {
+            attempt: i + 1,
+            status: this.mapPlaywrightStatusToCtrf(retryResult.status),
+            duration: retryResult.duration,
+            message: this.extractFailureDetails(retryResult).message,
+            trace: this.extractFailureDetails(retryResult).trace,
+            snippet: this.extractFailureDetails(retryResult).snippet
+          };
+          test2.retryAttempts.push(retryAttempt);
+        }
+      }
+    }
+    ctrfReport.results.tests.push(test2);
+  }
+  updateSummaryFromTestResult(testResult, ctrfReport) {
+    ctrfReport.results.summary.tests++;
+    const ctrfStatus = this.mapPlaywrightStatusToCtrf(testResult.status);
+    if (ctrfStatus in ctrfReport.results.summary) {
+      ctrfReport.results.summary[ctrfStatus]++;
+    } else {
+      ctrfReport.results.summary.other++;
+    }
+  }
+  mapPlaywrightStatusToCtrf(testStatus) {
+    switch (testStatus) {
+      case "passed":
+        return "passed";
+      case "failed":
+      case "timedOut":
+      case "interrupted":
+        return "failed";
+      case "skipped":
+        return "skipped";
+      case "pending":
+        return "pending";
+      default:
+        return "other";
+    }
+  }
+  setEnvironmentDetails(reporterConfigOptions) {
+    if (reporterConfigOptions.appName !== void 0) {
+      this.ctrfEnvironment.appName = reporterConfigOptions.appName;
+    }
+    if (reporterConfigOptions.appVersion !== void 0) {
+      this.ctrfEnvironment.appVersion = reporterConfigOptions.appVersion;
+    }
+    if (reporterConfigOptions.osPlatform !== void 0) {
+      this.ctrfEnvironment.osPlatform = reporterConfigOptions.osPlatform;
+    }
+    if (reporterConfigOptions.osRelease !== void 0) {
+      this.ctrfEnvironment.osRelease = reporterConfigOptions.osRelease;
+    }
+    if (reporterConfigOptions.osVersion !== void 0) {
+      this.ctrfEnvironment.osVersion = reporterConfigOptions.osVersion;
+    }
+    if (reporterConfigOptions.buildName !== void 0) {
+      this.ctrfEnvironment.buildName = reporterConfigOptions.buildName;
+    }
+    if (reporterConfigOptions.buildNumber !== void 0) {
+      this.ctrfEnvironment.buildNumber = Number(
+        reporterConfigOptions.buildNumber
+      );
+    }
+    if (reporterConfigOptions.buildUrl !== void 0) {
+      this.ctrfEnvironment.buildUrl = reporterConfigOptions.buildUrl;
+    }
+    if (reporterConfigOptions.repositoryName !== void 0) {
+      this.ctrfEnvironment.repositoryName = reporterConfigOptions.repositoryName;
+    }
+    if (reporterConfigOptions.repositoryUrl !== void 0) {
+      this.ctrfEnvironment.repositoryUrl = reporterConfigOptions.repositoryUrl;
+    }
+    if (reporterConfigOptions.branchName !== void 0) {
+      this.ctrfEnvironment.branchName = reporterConfigOptions.branchName;
+    }
+    if (reporterConfigOptions.commit !== void 0) {
+      this.ctrfEnvironment.commit = reporterConfigOptions.commit;
+    }
+    if (reporterConfigOptions.testEnvironment !== void 0) {
+      this.ctrfEnvironment.testEnvironment = reporterConfigOptions.testEnvironment;
+    }
+  }
+  hasEnvironmentDetails(environment) {
+    return Object.keys(environment).length > 0;
+  }
+  extractMetadata(testResult) {
+    const metadataAttachment = testResult.attachments.find(
+      (attachment) => attachment.name === "metadata.json"
+    );
+    if (metadataAttachment?.body !== null && metadataAttachment?.body !== void 0) {
+      try {
+        const metadataRaw = metadataAttachment.body.toString("utf-8");
+        return JSON.parse(metadataRaw);
+      } catch (e) {
+        if (e instanceof Error) {
+          console.error(`Error parsing browser metadata: ${e.message}`);
+        } else {
+          console.error(
+            "An unknown error occurred in parsing browser metadata"
+          );
+        }
+      }
+    }
+    return null;
+  }
+  /**
+   * Deep merge with array concatenation.
+   * Arrays are concatenated, objects are recursively merged, primitives overwrite.
+   */
+  deepMerge(target, source) {
+    const result = { ...target };
+    for (const [key, sourceValue] of Object.entries(source)) {
+      const targetValue = result[key];
+      if (Array.isArray(sourceValue)) {
+        result[key] = Array.isArray(targetValue) ? [...targetValue, ...sourceValue] : [...sourceValue];
+      } else if (sourceValue !== null && typeof sourceValue === "object" && !Array.isArray(sourceValue)) {
+        result[key] = targetValue !== null && typeof targetValue === "object" && !Array.isArray(targetValue) ? this.deepMerge(
+          targetValue,
+          sourceValue
+        ) : { ...sourceValue };
+      } else {
+        result[key] = sourceValue;
+      }
+    }
+    return result;
+  }
+  /**
+   * Extract and merge runtime data from CTRF message attachments.
+   *
+   * Runtime messages are internal transport artifacts used to send data from
+   * test code to the reporter via test.info().attach(). They are identified
+   * by the CTRF_RUNTIME_MESSAGE_CONTENT_TYPE content type.
+   *
+   * ## Merge Semantics (deep merge with array concatenation)
+   *
+   * Messages are processed in attachment order with intelligent merging:
+   * - Arrays: Concatenated across calls (duplicates allowed)
+   * - Objects: Deep merged (nested keys preserved)
+   * - Primitives: Later values overwrite earlier ones
+   *
+   * @param testResult - The test result containing attachments
+   * @returns Merged runtime data or null if no CTRF messages found
+   */
+  extractRuntimeData(testResult) {
+    const runtimeData = {};
+    let hasData = false;
+    for (const attachment of testResult.attachments) {
+      if (attachment.contentType !== CTRF_RUNTIME_MESSAGE_CONTENT_TYPE) {
+        continue;
+      }
+      if (attachment.body === void 0) {
+        continue;
+      }
+      try {
+        const message = JSON.parse(
+          attachment.body.toString("utf-8")
+        );
+        if (message.type === "metadata" && message.data !== null) {
+          Object.assign(runtimeData, this.deepMerge(runtimeData, message.data));
+          hasData = true;
+        }
+      } catch (e) {
+        if (e instanceof Error) {
+          console.error(`Error parsing CTRF runtime message: ${e.message}`);
+        }
+      }
+    }
+    return hasData ? runtimeData : null;
+  }
+  updateStart(startTime) {
+    const date = new Date(startTime);
+    const unixEpochTime = Math.floor(date.getTime() / 1e3);
+    return unixEpochTime;
+  }
+  calculateStopTime(startTime, duration) {
+    const startDate = new Date(startTime);
+    const stopDate = new Date(startDate.getTime() + duration);
+    return Math.floor(stopDate.getTime() / 1e3);
+  }
+  // TODO(v1): change return type to string[] and update Test.suite to match canonical ctrf type.
+  buildSuitePath(test2) {
+    const pathComponents = [];
+    let currentSuite = test2.parent;
+    while (currentSuite !== void 0) {
+      if (currentSuite.title !== "") {
+        pathComponents.unshift(currentSuite.title);
+      }
+      currentSuite = currentSuite.parent;
+    }
+    return pathComponents.join(" > ");
+  }
+  extractScreenshotBase64(testResult) {
+    const screenshotAttachment = testResult.attachments.find(
+      (attachment) => attachment.name === "screenshot" && (attachment.contentType === "image/jpeg" || attachment.contentType === "image/png")
+    );
+    return screenshotAttachment?.body?.toString("base64");
+  }
+  extractFailureDetails(testResult) {
+    if ((testResult.status === "failed" || testResult.status === "timedOut" || testResult.status === "interrupted") && testResult.error !== void 0) {
+      const failureDetails = {};
+      if (testResult.error.message !== void 0) {
+        failureDetails.message = testResult.error.message;
+      }
+      if (testResult.error.stack !== void 0) {
+        failureDetails.trace = testResult.error.stack;
+      }
+      if (testResult.error.snippet !== void 0) {
+        failureDetails.snippet = testResult.error.snippet;
+      }
+      return failureDetails;
+    }
+    return {};
+  }
+  countSuites(suite) {
+    let count = 0;
+    suite.suites.forEach((childSuite) => {
+      count += this.countSuites(childSuite);
+    });
+    return count;
+  }
+  writeReportToFile(data) {
+    const filePath = import_node_path.default.join(
+      this.reporterConfigOptions.outputDir ?? this.defaultOutputDir,
+      this.reporterConfigOptions.outputFile ?? this.defaultOutputFile
+    );
+    const str = JSON.stringify(data, null, 2);
+    try {
+      import_node_fs.default.writeFileSync(filePath, `${str}
+`);
+      console.log(
+        `${this.reporterName}: successfully written ctrf json to %s/%s`,
+        this.reporterConfigOptions.outputDir,
+        this.reporterConfigOptions.outputFile
+      );
+    } catch (error) {
+      console.error(`Error writing ctrf json report:, ${String(error)}`);
+    }
+  }
+  processStep(test2, step) {
+    if (step.category === "test.step") {
+      const stepStatus = step.error === void 0 ? this.mapPlaywrightStatusToCtrf("passed") : this.mapPlaywrightStatusToCtrf("failed");
+      const currentStep = {
+        name: step.title,
+        status: stepStatus
+      };
+      test2.steps?.push(currentStep);
+    }
+    const childSteps = step.steps;
+    if (childSteps.length > 0) {
+      childSteps.forEach((cStep) => {
+        this.processStep(test2, cStep);
+      });
+    }
+  }
+  /**
+   * Filter attachments to include in CTRF output.
+   *
+   * Excludes:
+   * - Attachments without a file path (body-only attachments)
+   * - CTRF runtime message attachments (internal transport artifacts)
+   *
+   * Runtime messages exist only to transmit data from test → reporter and
+   * are not user-facing attachments.
+   */
+  filterValidAttachments(attachments) {
+    return attachments.filter((attachment) => {
+      if (attachment.path === void 0) {
+        return false;
+      }
+      if (attachment.contentType === CTRF_RUNTIME_MESSAGE_CONTENT_TYPE) {
+        return false;
+      }
+      return true;
+    }).map((attachment) => ({
+      name: attachment.name,
+      contentType: attachment.contentType,
+      path: attachment.path ?? ""
+    }));
+  }
+};
+var generate_report_default = GenerateCtrfReport;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ctrf,
+  extra
+});