@testpulse.run/playwright-jsonl-reporter 0.2.3

package/README.md

@@ -0,0 +1,72 @@
+<p align="center">
+  <a href="https://testpulse.run">
+    <img src="https://testpulse.run/images/logo-testpulse.svg" alt="TestPulse.run" height="48">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://testpulse.run">testpulse.run</a>
+</p>
+
+# @testpulse.run/playwright-jsonl-reporter
+
+Append-only JSONL reporter for Playwright TestPulse events.
+
+Use this package when you want Playwright run events as newline-delimited JSON for local files, custom ingestion pipelines, debugging, or tests around reporter behavior.
+
+Most TestPulse users should install `@testpulse.run/reporter`, which uses this package with an HTTP sink preconfigured for the TestPulse API.
+
+## Installation
+
+```sh
+npm install -D @testpulse.run/playwright-jsonl-reporter @playwright/test
+```
+
+## Playwright Configuration
+
+```ts
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  reporter: [
+    ["@testpulse.run/playwright-jsonl-reporter", { outputDir: "testpulse-events" }]
+  ]
+});
+```
+
+By default the reporter writes JSONL files to `testpulse-events`.
+
+## Options
+
+- `outputDir`: directory for filesystem JSONL output.
+- `runId`: explicit run identifier. A process/time based id is generated by default.
+- `includeCoreEvents`: include normalized Playwright lifecycle events; defaults to `true`.
+- `includeDerivedEvents`: include derived attempt and outcome events; defaults to `true`.
+- `failOnHandlerError`: cause Playwright to fail when reporter handlers throw.
+- `sink`: custom event sink for filesystem, HTTP, or in-memory integrations.
+
+## Custom Sink
+
+```ts
+import { JsonlReporter, type EventSink, type JsonlEvent } from "@testpulse.run/playwright-jsonl-reporter";
+
+class MemorySink implements EventSink {
+  readonly metadata = { writerId: "memory", sinkType: "memory" };
+  readonly events: JsonlEvent[] = [];
+
+  write(event: JsonlEvent) {
+    this.events.push(event);
+  }
+
+  async flush() {}
+  async close() {}
+}
+
+export default new JsonlReporter({ sink: new MemorySink() });
+```
+
+## Related Packages
+
+- `@testpulse.run/reporter`: preconfigured HTTP reporter for TestPulse.
+- `@testpulse.run/playwright-events`: derived test attempt and outcome events.
+- `@testpulse.run/playwright-core`: normalized Playwright reporter lifecycle events.

package/dist/index.cjs

@@ -0,0 +1,568 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FileSystemEventSink: () => FileSystemEventSink,
+  HttpEventSink: () => HttpEventSink,
+  JsonlReporter: () => JsonlReporter,
+  default: () => reporter_default
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/reporter.ts
+var import_playwright_core = require("@testpulse.run/playwright-core");
+var import_playwright_events = require("@testpulse.run/playwright-events");
+
+// src/serialize.ts
+function serializeCoreEvent(event, context) {
+  return serializeEvent(event, context, "core");
+}
+function serializeDerivedEvent(event, context) {
+  return serializeEvent(event, context, "derived");
+}
+function serializeEvent(event, context, stream) {
+  const payload = createPayload(event);
+  const worker = readWorker(event);
+  const test = readTest(event);
+  const step = readStep(event);
+  const terminal = readTerminalFacts(event);
+  const run = readRunFacts(event);
+  const eventName = event.eventName;
+  return omitUndefined({
+    schemaVersion: 1,
+    eventId: context.eventId,
+    sequence: context.sequence,
+    type: eventName,
+    stream,
+    eventName,
+    timestamp: event.timestamp,
+    source: event.source,
+    runId: context.runId,
+    writerId: context.writerId,
+    shardId: context.shard?.shardId,
+    shardIndex: context.shard?.shardIndex,
+    shardCount: context.shard?.shardCount,
+    workerId: worker ? `worker-${worker.workerIndex}` : void 0,
+    workerIndex: worker?.workerIndex,
+    parallelIndex: worker?.parallelIndex,
+    testId: test?.testId,
+    testTitle: test?.title,
+    file: test?.location?.file,
+    line: test?.location?.line,
+    column: test?.location?.column,
+    projectName: test?.projectName,
+    retry: readRetry(event),
+    repeatEachIndex: test?.repeatEachIndex,
+    expectedStatus: readExpectedStatus(event, test),
+    stepId: step?.stepId,
+    parentStepId: step?.parentStepId,
+    stepTitle: step?.title,
+    stepCategory: step?.category,
+    stepFile: step?.location?.file,
+    stepLine: step?.location?.line,
+    stepColumn: step?.location?.column,
+    status: terminal.status ?? run.status,
+    durationMs: terminal.durationMs ?? run.durationMs,
+    startTime: run.startTime,
+    totalTests: run.totalTests,
+    configuredWorkers: run.configuredWorkers,
+    errors: normalizeErrors(terminal.errors),
+    attachments: terminal.attachments,
+    outcome: "outcome" in event ? event.outcome : void 0,
+    payload: Object.keys(payload).length > 0 ? payload : void 0
+  });
+}
+function createPayload(event) {
+  const payload = {};
+  for (const [key, value] of Object.entries(event)) {
+    if (value === void 0 || TOP_LEVEL_OR_STRUCTURAL_KEYS.has(key)) {
+      continue;
+    }
+    payload[key] = value;
+  }
+  return payload;
+}
+function readWorker(event) {
+  return "worker" in event ? event.worker : void 0;
+}
+function readTest(event) {
+  return "test" in event ? event.test : void 0;
+}
+function readStep(event) {
+  return "step" in event ? event.step : void 0;
+}
+function readRetry(event) {
+  if ("retry" in event) {
+    return event.retry;
+  }
+  if ("attempt" in event) {
+    return event.attempt.retry;
+  }
+  if ("finalAttempt" in event) {
+    return event.finalAttempt.retry;
+  }
+  return void 0;
+}
+function readExpectedStatus(event, test) {
+  return "expectedStatus" in event ? event.expectedStatus : test?.expectedStatus;
+}
+function readTerminalFacts(event) {
+  if ("attempt" in event) {
+    return readAttemptFacts(event.attempt);
+  }
+  if ("finalAttempt" in event) {
+    return readAttemptFacts(event.finalAttempt);
+  }
+  return {
+    status: "status" in event ? event.status : void 0,
+    durationMs: "durationMs" in event ? event.durationMs : void 0,
+    errors: readErrors(event),
+    attachments: "attachments" in event ? event.attachments : void 0
+  };
+}
+function readAttemptFacts(attempt) {
+  return {
+    status: attempt.status,
+    durationMs: attempt.durationMs,
+    errors: attempt.errors,
+    attachments: attempt.attachments
+  };
+}
+function normalizeErrors(errors) {
+  return errors?.map((error) => ({
+    message: error.message,
+    stack: error.stack,
+    value: error.value,
+    file: error.location?.file,
+    line: error.location?.line,
+    column: error.location?.column
+  }));
+}
+function readRunFacts(event) {
+  const result = "result" in event ? event.result : void 0;
+  return {
+    startTime: result?.startTime,
+    status: result?.status,
+    durationMs: result?.durationMs,
+    totalTests: "totalTests" in event ? event.totalTests : "suite" in event ? event.suite.totalTests : void 0,
+    configuredWorkers: "configuredWorkers" in event ? event.configuredWorkers : "config" in event ? event.config.configuredWorkers : void 0
+  };
+}
+function readErrors(event) {
+  if ("errors" in event) {
+    return event.errors;
+  }
+  if ("error" in event) {
+    return event.error ? [event.error] : void 0;
+  }
+  return void 0;
+}
+var TOP_LEVEL_OR_STRUCTURAL_KEYS = /* @__PURE__ */ new Set([
+  "eventName",
+  "timestamp",
+  "source",
+  "test",
+  "step",
+  "result",
+  "config",
+  "suite",
+  "shard",
+  "worker",
+  "testId",
+  "title",
+  "titlePath",
+  "totalTests",
+  "configuredWorkers",
+  "location",
+  "projectName",
+  "retryCount",
+  "repeatEachIndex",
+  "retry",
+  "attempt",
+  "attemptIndex",
+  "status",
+  "durationMs",
+  "expectedStatus",
+  "errors",
+  "error",
+  "attachments",
+  "outcome",
+  "finalAttempt",
+  "attempts",
+  "coreEvent"
+]);
+function omitUndefined(event) {
+  return Object.fromEntries(Object.entries(event).filter(([, value]) => value !== void 0));
+}
+
+// src/sink.ts
+var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var FileSystemEventSink = class {
+  filePath;
+  metadata;
+  stream;
+  closed = false;
+  streamError;
+  constructor(options = {}) {
+    const outputDir = (0, import_node_path.resolve)(options.outputDir ?? "testpulse-events");
+    (0, import_node_fs.mkdirSync)(outputDir, { recursive: true });
+    this.metadata = {
+      writerId: options.writerId ?? createWriterId(),
+      sinkType: "filesystem"
+    };
+    this.filePath = (0, import_node_path.resolve)(outputDir, options.fileName ?? createDefaultFileName());
+    this.stream = (0, import_node_fs.createWriteStream)(this.filePath, { flags: "a" });
+    this.stream.on("error", (error) => {
+      this.streamError = error;
+    });
+  }
+  write(event) {
+    if (this.closed) {
+      throw new Error("Cannot write to a closed FileSystemEventSink.");
+    }
+    if (this.streamError) {
+      throw this.streamError;
+    }
+    this.stream.write(`${JSON.stringify(event)}
+`, (error) => {
+      if (error) {
+        this.streamError = error;
+      }
+    });
+  }
+  async flush() {
+    if (this.closed) {
+      return;
+    }
+    if (this.streamError) {
+      throw this.streamError;
+    }
+    await new Promise((resolvePromise, reject) => {
+      this.stream.write("", (error) => {
+        if (error) {
+          this.streamError = error;
+          reject(error);
+          return;
+        }
+        if (this.streamError) {
+          reject(this.streamError);
+          return;
+        }
+        resolvePromise();
+      });
+    });
+  }
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    await new Promise((resolvePromise, reject) => {
+      this.stream.end((error) => {
+        if (error) {
+          this.streamError = error;
+          reject(error);
+          return;
+        }
+        if (this.streamError) {
+          reject(this.streamError);
+          return;
+        }
+        resolvePromise();
+      });
+    });
+  }
+};
+function createDefaultFileName() {
+  return `events-pid-${process.pid}-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.jsonl`;
+}
+function createWriterId() {
+  return `filesystem-${process.pid}-${(0, import_node_crypto.randomUUID)()}`;
+}
+
+// src/reporter.ts
+var JsonlReporter = class {
+  core;
+  events;
+  sink;
+  configuredRunId;
+  nextEventId = 1;
+  runId = createRunId();
+  shard;
+  constructor(options = {}) {
+    this.sink = options.sink ?? new FileSystemEventSink({ outputDir: options.outputDir });
+    this.configuredRunId = options.runId;
+    const includeCoreEvents = options.includeCoreEvents ?? true;
+    const includeDerivedEvents = options.includeDerivedEvents ?? true;
+    const corePlugins = [];
+    const derivedPlugins = [];
+    if (includeDerivedEvents) {
+      derivedPlugins.push(this.createDerivedPlugin());
+    }
+    this.events = new import_playwright_events.PlaywrightEvents({ plugins: derivedPlugins });
+    if (includeCoreEvents) {
+      corePlugins.push(this.createCorePlugin());
+    }
+    corePlugins.push(this.events.asCorePlugin());
+    if (!includeCoreEvents) {
+      corePlugins.push(this.createSinkFinalizerPlugin());
+    }
+    this.core = new import_playwright_core.TestPulseReporterCore({
+      plugins: corePlugins,
+      failOnHandlerError: options.failOnHandlerError
+    });
+    this.events.setErrorSink(this.core);
+  }
+  onBegin(config, suite) {
+    this.nextEventId = 1;
+    this.runId = this.configuredRunId ?? createRunId();
+    this.shard = void 0;
+    this.core.onBegin(config, suite);
+  }
+  onEnd(result) {
+    return this.core.onEnd(result);
+  }
+  onError(...args) {
+    this.core.onError(...args);
+  }
+  onTestBegin(...args) {
+    this.core.onTestBegin(...args);
+  }
+  onTestEnd(...args) {
+    this.core.onTestEnd(...args);
+  }
+  onStepBegin(...args) {
+    this.core.onStepBegin(...args);
+  }
+  onStepEnd(...args) {
+    this.core.onStepEnd(...args);
+  }
+  onStdOut(...args) {
+    this.core.onStdOut(...args);
+  }
+  onStdErr(...args) {
+    this.core.onStdErr(...args);
+  }
+  createCorePlugin() {
+    const plugin = { name: "@testpulse.run/playwright-jsonl-reporter/core" };
+    for (const eventName of Object.values(import_playwright_core.TestPulseReporterEventName)) {
+      plugin[eventName] = ((event) => {
+        this.writeCoreEvent(event);
+        if (event.eventName === "RunFinished") {
+          return this.sink.close();
+        }
+      });
+    }
+    return plugin;
+  }
+  createDerivedPlugin() {
+    const plugin = { name: "@testpulse.run/playwright-jsonl-reporter/derived" };
+    for (const eventName of Object.values(import_playwright_events.TestPulseDerivedEventName)) {
+      plugin[eventName] = ((event) => {
+        this.writeDerivedEvent(event);
+      });
+    }
+    return plugin;
+  }
+  createSinkFinalizerPlugin() {
+    return {
+      name: "@testpulse.run/playwright-jsonl-reporter/finalizer",
+      RunFinished: () => this.sink.close()
+    };
+  }
+  writeCoreEvent(event) {
+    if (event.eventName === "ShardStarted") {
+      this.shard = event.shard;
+    }
+    this.sink.write(serializeCoreEvent(event, this.createSerializationContext()));
+  }
+  writeDerivedEvent(event) {
+    this.sink.write(serializeDerivedEvent(event, this.createSerializationContext()));
+  }
+  createSerializationContext() {
+    const sequence = this.nextEventId;
+    this.nextEventId += 1;
+    return {
+      eventId: `${this.runId}:${this.sink.metadata.writerId}:${sequence}`,
+      sequence,
+      runId: this.runId,
+      writerId: this.sink.metadata.writerId,
+      shard: this.shard ? {
+        shardId: `${this.runId}:${this.sink.metadata.writerId}:shard-${this.shard.current}-of-${this.shard.total}`,
+        shardIndex: this.shard.current,
+        shardCount: this.shard.total
+      } : void 0
+    };
+  }
+};
+function createRunId() {
+  return `run-${process.pid}-${Date.now()}`;
+}
+var reporter_default = JsonlReporter;
+
+// src/http-sink.ts
+var import_node_crypto2 = require("crypto");
+var HttpEventSink = class {
+  metadata;
+  baseUrl;
+  apiKey;
+  storageStreamId;
+  flushIntervalMs;
+  batchSize;
+  fetchImpl;
+  pending = [];
+  closed = false;
+  inFlight;
+  flushTimer;
+  lastBackgroundError;
+  constructor(options) {
+    if (!options.baseUrl) {
+      throw new Error("HttpEventSink requires a baseUrl.");
+    }
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.storageStreamId = options.storageStreamId ?? "events";
+    this.flushIntervalMs = readPositiveNumber(options.flushIntervalMs, 250, "flushIntervalMs");
+    this.batchSize = readPositiveNumber(options.batchSize, 100, "batchSize");
+    this.fetchImpl = options.fetch ?? fetch;
+    this.metadata = {
+      writerId: options.writerId ?? createWriterId2(),
+      sinkType: "http"
+    };
+  }
+  write(event) {
+    if (this.closed) {
+      throw new Error("Cannot write to a closed HttpEventSink.");
+    }
+    this.pending.push(event);
+    this.ensureFlushTimer();
+    if (this.pending.length >= this.batchSize) {
+      this.triggerBackgroundFlush();
+    }
+  }
+  async flush() {
+    if (this.inFlight) {
+      try {
+        await this.inFlight;
+      } catch (error) {
+        this.lastBackgroundError = error;
+      }
+    }
+    if (this.pending.length === 0) {
+      return;
+    }
+    const events = this.pending.slice();
+    this.inFlight = this.sendEvents(events);
+    try {
+      await this.inFlight;
+      this.pending.splice(0, events.length);
+      this.lastBackgroundError = void 0;
+    } finally {
+      this.inFlight = void 0;
+    }
+  }
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.clearFlushTimer();
+    await this.flush();
+    this.closed = true;
+  }
+  ensureFlushTimer() {
+    if (this.flushTimer) {
+      return;
+    }
+    this.flushTimer = setInterval(() => this.triggerBackgroundFlush(), this.flushIntervalMs);
+    this.flushTimer.unref?.();
+  }
+  clearFlushTimer() {
+    if (!this.flushTimer) {
+      return;
+    }
+    clearInterval(this.flushTimer);
+    this.flushTimer = void 0;
+  }
+  triggerBackgroundFlush() {
+    if (this.inFlight) {
+      return;
+    }
+    void this.flush().catch((error) => {
+      this.lastBackgroundError = error;
+    });
+  }
+  async sendEvents(events) {
+    for (const group of groupByRun(events)) {
+      const response = await this.fetchImpl(this.createEndpoint(group.runId), {
+        method: "POST",
+        headers: this.createHeaders(),
+        body: JSON.stringify({ events: group.events })
+      });
+      if (!response.ok) {
+        throw new Error(`TestPulse HTTP ingest failed with ${response.status} ${response.statusText}: ${await response.text()}`);
+      }
+    }
+  }
+  createEndpoint(runId) {
+    return `${this.baseUrl}/api/v1/runs/${encodeURIComponent(runId)}/streams/${encodeURIComponent(this.storageStreamId)}/events`;
+  }
+  createHeaders() {
+    const headers = {
+      "content-type": "application/json"
+    };
+    if (this.apiKey) {
+      headers["x-api-key"] = this.apiKey;
+    }
+    return headers;
+  }
+};
+function groupByRun(events) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const group = groups.get(event.runId);
+    if (group) {
+      group.events.push(event);
+      continue;
+    }
+    groups.set(event.runId, { runId: event.runId, events: [event] });
+  }
+  return [...groups.values()];
+}
+function createWriterId2() {
+  return `http-${process.pid}-${(0, import_node_crypto2.randomUUID)()}`;
+}
+function readPositiveNumber(value, defaultValue, optionName) {
+  if (value === void 0) {
+    return defaultValue;
+  }
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`HttpEventSink ${optionName} must be a positive number.`);
+  }
+  return value;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FileSystemEventSink,
+  HttpEventSink,
+  JsonlReporter
+});