@testpulse.run/playwright-events 0.2.3

package/README.md

@@ -0,0 +1,56 @@
+<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-events
+
+Derived Playwright test events for TestPulse reporters.
+
+This package consumes normalized core events from `@testpulse.run/playwright-core` and emits higher-level events such as test attempts and final test outcomes. It is useful when you are building a custom reporter and do not want to derive retries, flaky outcomes, skipped results, and attempt lifecycle yourself.
+
+Most users should install `@testpulse.run/reporter` instead.
+
+## Installation
+
+```sh
+npm install -D @testpulse.run/playwright-events @testpulse.run/playwright-core @playwright/test
+```
+
+## Basic Usage
+
+```ts
+import { TestPulseReporterCore } from "@testpulse.run/playwright-core";
+import { PlaywrightEvents, type TestPulseDerivedEventsPlugin } from "@testpulse.run/playwright-events";
+
+const derivedPlugin: TestPulseDerivedEventsPlugin = {
+  name: "my-derived-events",
+  TestAttemptFinished: (event) => {
+    recordAttempt(event.test.title, event.status, event.retry);
+  },
+  TestOutcomeResolved: (event) => {
+    recordOutcome(event.test.title, event.outcome);
+  }
+};
+
+const events = new PlaywrightEvents({ plugins: [derivedPlugin] });
+const core = new TestPulseReporterCore({ plugins: [events.asCorePlugin()] });
+events.setErrorSink(core);
+```
+
+## Derived Events
+
+- `TestAttemptStarted`
+- `TestAttemptFinished`
+- `TestOutcomeResolved`
+
+## Related Packages
+
+- `@testpulse.run/reporter`: preconfigured HTTP reporter for TestPulse.
+- `@testpulse.run/playwright-jsonl-reporter`: writes core and derived events to JSONL or HTTP sinks.
+- `@testpulse.run/playwright-core`: normalized Playwright reporter lifecycle events.

package/dist/index.cjs

@@ -0,0 +1,180 @@
+"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, {
+  PlaywrightEvents: () => PlaywrightEvents,
+  TestPulseDerivedEventName: () => TestPulseDerivedEventName
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/events.ts
+var TestPulseDerivedEventName = {
+  TestAttemptStarted: "TestAttemptStarted",
+  TestAttemptFinished: "TestAttemptFinished",
+  TestOutcomeResolved: "TestOutcomeResolved"
+};
+
+// src/playwright-events.ts
+var PlaywrightEvents = class {
+  handlerErrors = [];
+  plugins;
+  errorSink;
+  attemptsByTestId = /* @__PURE__ */ new Map();
+  resolvedTestIds = /* @__PURE__ */ new Set();
+  constructor(options = {}) {
+    this.plugins = options.plugins ?? [];
+    this.errorSink = options.errorSink;
+  }
+  setErrorSink(errorSink) {
+    this.errorSink = errorSink;
+  }
+  asCorePlugin() {
+    return {
+      name: "@testpulse.run/playwright-events",
+      RunStarted: () => this.reset(),
+      TestStarted: (event, context) => this.onTestStarted(event, context),
+      TestFinished: (event, context) => this.onTestFinished(event, context)
+    };
+  }
+  onTestStarted(event, context = {}) {
+    const metadata = createMetadata(event);
+    this.emit({
+      eventName: TestPulseDerivedEventName.TestAttemptStarted,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "synthetic",
+      ...metadata,
+      attemptIndex: event.retry,
+      retry: event.retry,
+      coreEvent: {
+        eventName: event.eventName,
+        timestamp: event.timestamp
+      }
+    }, { coreContext: context });
+  }
+  onTestFinished(event, context = {}) {
+    const metadata = createMetadata(event);
+    if (this.resolvedTestIds.has(metadata.testId)) {
+      return;
+    }
+    const attempt = createAttempt(event);
+    const attempts = [...this.attemptsByTestId.get(metadata.testId) ?? [], attempt];
+    this.attemptsByTestId.set(metadata.testId, attempts);
+    this.emit({
+      eventName: TestPulseDerivedEventName.TestAttemptFinished,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "synthetic",
+      ...metadata,
+      attempt,
+      attemptIndex: attempt.attemptIndex,
+      retry: attempt.retry,
+      status: attempt.status,
+      coreEvent: {
+        eventName: event.eventName,
+        timestamp: event.timestamp
+      }
+    }, { coreContext: context });
+    if (!isFinalAttempt(event)) {
+      return;
+    }
+    this.resolvedTestIds.add(metadata.testId);
+    this.attemptsByTestId.delete(metadata.testId);
+    this.emit({
+      eventName: TestPulseDerivedEventName.TestOutcomeResolved,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "synthetic",
+      ...metadata,
+      outcome: resolveOutcome(event, attempts),
+      attempts,
+      finalAttempt: attempt,
+      coreEvent: {
+        eventName: event.eventName,
+        timestamp: event.timestamp
+      }
+    }, { coreContext: context });
+  }
+  emit(event, context) {
+    for (const plugin of this.plugins) {
+      const handler = plugin[event.eventName];
+      if (!handler) {
+        continue;
+      }
+      try {
+        handler.call(plugin, event, context);
+      } catch (error) {
+        const handlerError = {
+          source: "@testpulse.run/playwright-events",
+          eventName: event.eventName,
+          pluginName: plugin.name,
+          error
+        };
+        this.handlerErrors.push(handlerError);
+        this.errorSink?.recordHandlerError(handlerError);
+      }
+    }
+  }
+  reset() {
+    this.handlerErrors.length = 0;
+    this.attemptsByTestId.clear();
+    this.resolvedTestIds.clear();
+  }
+};
+function createMetadata(event) {
+  return {
+    ...event.test,
+    testId: event.test.testId ?? event.titlePath.join(" \u203A "),
+    test: event.test,
+    titlePath: event.titlePath,
+    worker: event.worker
+  };
+}
+function createAttempt(event) {
+  return {
+    attemptIndex: event.retry,
+    retry: event.retry,
+    status: event.status,
+    durationMs: event.durationMs,
+    errors: event.errors,
+    attachments: event.attachments
+  };
+}
+function isFinalAttempt(event) {
+  return event.status === event.expectedStatus || event.retry >= (event.test.retryCount ?? 0) || event.status === "skipped" || event.status === "interrupted";
+}
+function resolveOutcome(event, attempts) {
+  if (event.status === "skipped") {
+    return "skipped";
+  }
+  if (event.status === "interrupted") {
+    return "interrupted";
+  }
+  if (event.status === "timedOut") {
+    return "timedOut";
+  }
+  if (event.status === "passed") {
+    return attempts.some((attempt) => attempt.status === "failed" || attempt.status === "timedOut" || attempt.status === "interrupted") ? "flaky" : "passed";
+  }
+  return "failed";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PlaywrightEvents,
+  TestPulseDerivedEventName
+});

package/dist/index.d.cts

@@ -0,0 +1,86 @@
+import { TestPulseHandlerError, TestPulseTestInfo, WorkerIdentity, TestStartedEvent, NormalizedTestStatus, TestPulseErrorInfo, AttachmentInfo, TestFinishedEvent, PlaywrightCoreEventContext, TestPulseEventSource, TestPulseHandlerErrorSink, TestPulseReporterPlugin } from '@testpulse.run/playwright-core';
+
+declare const TestPulseDerivedEventName: {
+    readonly TestAttemptStarted: "TestAttemptStarted";
+    readonly TestAttemptFinished: "TestAttemptFinished";
+    readonly TestOutcomeResolved: "TestOutcomeResolved";
+};
+type TestPulseDerivedEventName = (typeof TestPulseDerivedEventName)[keyof typeof TestPulseDerivedEventName];
+type TestOutcome = "passed" | "failed" | "flaky" | "skipped" | "interrupted" | "timedOut";
+interface TestAttempt {
+    attemptIndex: number;
+    retry: number;
+    status: NormalizedTestStatus;
+    durationMs: number;
+    errors: TestPulseErrorInfo[];
+    attachments: AttachmentInfo[];
+}
+interface TestMetadata extends TestPulseTestInfo {
+    testId: string;
+    test: TestPulseTestInfo;
+    worker: WorkerIdentity;
+}
+interface TestAttemptStartedEvent extends TestMetadata {
+    eventName: "TestAttemptStarted";
+    timestamp: string;
+    source: "synthetic";
+    attemptIndex: number;
+    retry: number;
+    coreEvent: Pick<TestStartedEvent, "eventName" | "timestamp">;
+}
+interface TestAttemptFinishedEvent extends TestMetadata {
+    eventName: "TestAttemptFinished";
+    timestamp: string;
+    source: "synthetic";
+    attempt: TestAttempt;
+    attemptIndex: number;
+    retry: number;
+    status: NormalizedTestStatus;
+    coreEvent: Pick<TestFinishedEvent, "eventName" | "timestamp">;
+}
+interface TestOutcomeResolvedEvent extends TestMetadata {
+    eventName: "TestOutcomeResolved";
+    timestamp: string;
+    source: "synthetic";
+    outcome: TestOutcome;
+    attempts: TestAttempt[];
+    finalAttempt: TestAttempt;
+    coreEvent: Pick<TestFinishedEvent, "eventName" | "timestamp">;
+}
+type TestPulseDerivedEvent = TestAttemptStartedEvent | TestAttemptFinishedEvent | TestOutcomeResolvedEvent;
+type TestPulseDerivedEventMap = {
+    [Event in TestPulseDerivedEvent as Event["eventName"]]: Event;
+};
+interface PlaywrightDerivedEventContext {
+    coreContext?: PlaywrightCoreEventContext;
+}
+type TestPulseDerivedHandler<Name extends TestPulseDerivedEventName> = (event: TestPulseDerivedEventMap[Name], context: PlaywrightDerivedEventContext) => void;
+type TestPulseDerivedHandlerMap = Partial<{
+    [Name in TestPulseDerivedEventName]: TestPulseDerivedHandler<Name>;
+}>;
+interface TestPulseDerivedEventsPlugin extends TestPulseDerivedHandlerMap {
+    name?: string;
+}
+type TestPulseDerivedHandlerError = TestPulseHandlerError;
+type TestPulseDerivedEventSource = TestPulseEventSource;
+
+interface PlaywrightEventsOptions {
+    plugins?: TestPulseDerivedEventsPlugin[];
+    errorSink?: TestPulseHandlerErrorSink;
+}
+declare class PlaywrightEvents {
+    readonly handlerErrors: TestPulseDerivedHandlerError[];
+    private readonly plugins;
+    private errorSink?;
+    private readonly attemptsByTestId;
+    private readonly resolvedTestIds;
+    constructor(options?: PlaywrightEventsOptions);
+    setErrorSink(errorSink: TestPulseHandlerErrorSink | undefined): void;
+    asCorePlugin(): TestPulseReporterPlugin;
+    onTestStarted(event: TestStartedEvent, context?: PlaywrightCoreEventContext): void;
+    onTestFinished(event: TestFinishedEvent, context?: PlaywrightCoreEventContext): void;
+    private emit;
+    private reset;
+}
+
+export { PlaywrightEvents, type PlaywrightEventsOptions, type TestAttempt, type TestAttemptFinishedEvent, type TestAttemptStartedEvent, type TestMetadata, type TestOutcome, type TestOutcomeResolvedEvent, type TestPulseDerivedEvent, type TestPulseDerivedEventMap, TestPulseDerivedEventName, type TestPulseDerivedEventSource, type TestPulseDerivedEventsPlugin, type TestPulseDerivedHandler, type TestPulseDerivedHandlerError, type TestPulseDerivedHandlerMap };

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import { TestPulseHandlerError, TestPulseTestInfo, WorkerIdentity, TestStartedEvent, NormalizedTestStatus, TestPulseErrorInfo, AttachmentInfo, TestFinishedEvent, PlaywrightCoreEventContext, TestPulseEventSource, TestPulseHandlerErrorSink, TestPulseReporterPlugin } from '@testpulse.run/playwright-core';
+
+declare const TestPulseDerivedEventName: {
+    readonly TestAttemptStarted: "TestAttemptStarted";
+    readonly TestAttemptFinished: "TestAttemptFinished";
+    readonly TestOutcomeResolved: "TestOutcomeResolved";
+};
+type TestPulseDerivedEventName = (typeof TestPulseDerivedEventName)[keyof typeof TestPulseDerivedEventName];
+type TestOutcome = "passed" | "failed" | "flaky" | "skipped" | "interrupted" | "timedOut";
+interface TestAttempt {
+    attemptIndex: number;
+    retry: number;
+    status: NormalizedTestStatus;
+    durationMs: number;
+    errors: TestPulseErrorInfo[];
+    attachments: AttachmentInfo[];
+}
+interface TestMetadata extends TestPulseTestInfo {
+    testId: string;
+    test: TestPulseTestInfo;
+    worker: WorkerIdentity;
+}
+interface TestAttemptStartedEvent extends TestMetadata {
+    eventName: "TestAttemptStarted";
+    timestamp: string;
+    source: "synthetic";
+    attemptIndex: number;
+    retry: number;
+    coreEvent: Pick<TestStartedEvent, "eventName" | "timestamp">;
+}
+interface TestAttemptFinishedEvent extends TestMetadata {
+    eventName: "TestAttemptFinished";
+    timestamp: string;
+    source: "synthetic";
+    attempt: TestAttempt;
+    attemptIndex: number;
+    retry: number;
+    status: NormalizedTestStatus;
+    coreEvent: Pick<TestFinishedEvent, "eventName" | "timestamp">;
+}
+interface TestOutcomeResolvedEvent extends TestMetadata {
+    eventName: "TestOutcomeResolved";
+    timestamp: string;
+    source: "synthetic";
+    outcome: TestOutcome;
+    attempts: TestAttempt[];
+    finalAttempt: TestAttempt;
+    coreEvent: Pick<TestFinishedEvent, "eventName" | "timestamp">;
+}
+type TestPulseDerivedEvent = TestAttemptStartedEvent | TestAttemptFinishedEvent | TestOutcomeResolvedEvent;
+type TestPulseDerivedEventMap = {
+    [Event in TestPulseDerivedEvent as Event["eventName"]]: Event;
+};
+interface PlaywrightDerivedEventContext {
+    coreContext?: PlaywrightCoreEventContext;
+}
+type TestPulseDerivedHandler<Name extends TestPulseDerivedEventName> = (event: TestPulseDerivedEventMap[Name], context: PlaywrightDerivedEventContext) => void;
+type TestPulseDerivedHandlerMap = Partial<{
+    [Name in TestPulseDerivedEventName]: TestPulseDerivedHandler<Name>;
+}>;
+interface TestPulseDerivedEventsPlugin extends TestPulseDerivedHandlerMap {
+    name?: string;
+}
+type TestPulseDerivedHandlerError = TestPulseHandlerError;
+type TestPulseDerivedEventSource = TestPulseEventSource;
+
+interface PlaywrightEventsOptions {
+    plugins?: TestPulseDerivedEventsPlugin[];
+    errorSink?: TestPulseHandlerErrorSink;
+}
+declare class PlaywrightEvents {
+    readonly handlerErrors: TestPulseDerivedHandlerError[];
+    private readonly plugins;
+    private errorSink?;
+    private readonly attemptsByTestId;
+    private readonly resolvedTestIds;
+    constructor(options?: PlaywrightEventsOptions);
+    setErrorSink(errorSink: TestPulseHandlerErrorSink | undefined): void;
+    asCorePlugin(): TestPulseReporterPlugin;
+    onTestStarted(event: TestStartedEvent, context?: PlaywrightCoreEventContext): void;
+    onTestFinished(event: TestFinishedEvent, context?: PlaywrightCoreEventContext): void;
+    private emit;
+    private reset;
+}
+
+export { PlaywrightEvents, type PlaywrightEventsOptions, type TestAttempt, type TestAttemptFinishedEvent, type TestAttemptStartedEvent, type TestMetadata, type TestOutcome, type TestOutcomeResolvedEvent, type TestPulseDerivedEvent, type TestPulseDerivedEventMap, TestPulseDerivedEventName, type TestPulseDerivedEventSource, type TestPulseDerivedEventsPlugin, type TestPulseDerivedHandler, type TestPulseDerivedHandlerError, type TestPulseDerivedHandlerMap };

package/dist/index.js

@@ -0,0 +1,152 @@
+// src/events.ts
+var TestPulseDerivedEventName = {
+  TestAttemptStarted: "TestAttemptStarted",
+  TestAttemptFinished: "TestAttemptFinished",
+  TestOutcomeResolved: "TestOutcomeResolved"
+};
+
+// src/playwright-events.ts
+var PlaywrightEvents = class {
+  handlerErrors = [];
+  plugins;
+  errorSink;
+  attemptsByTestId = /* @__PURE__ */ new Map();
+  resolvedTestIds = /* @__PURE__ */ new Set();
+  constructor(options = {}) {
+    this.plugins = options.plugins ?? [];
+    this.errorSink = options.errorSink;
+  }
+  setErrorSink(errorSink) {
+    this.errorSink = errorSink;
+  }
+  asCorePlugin() {
+    return {
+      name: "@testpulse.run/playwright-events",
+      RunStarted: () => this.reset(),
+      TestStarted: (event, context) => this.onTestStarted(event, context),
+      TestFinished: (event, context) => this.onTestFinished(event, context)
+    };
+  }
+  onTestStarted(event, context = {}) {
+    const metadata = createMetadata(event);
+    this.emit({
+      eventName: TestPulseDerivedEventName.TestAttemptStarted,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "synthetic",
+      ...metadata,
+      attemptIndex: event.retry,
+      retry: event.retry,
+      coreEvent: {
+        eventName: event.eventName,
+        timestamp: event.timestamp
+      }
+    }, { coreContext: context });
+  }
+  onTestFinished(event, context = {}) {
+    const metadata = createMetadata(event);
+    if (this.resolvedTestIds.has(metadata.testId)) {
+      return;
+    }
+    const attempt = createAttempt(event);
+    const attempts = [...this.attemptsByTestId.get(metadata.testId) ?? [], attempt];
+    this.attemptsByTestId.set(metadata.testId, attempts);
+    this.emit({
+      eventName: TestPulseDerivedEventName.TestAttemptFinished,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "synthetic",
+      ...metadata,
+      attempt,
+      attemptIndex: attempt.attemptIndex,
+      retry: attempt.retry,
+      status: attempt.status,
+      coreEvent: {
+        eventName: event.eventName,
+        timestamp: event.timestamp
+      }
+    }, { coreContext: context });
+    if (!isFinalAttempt(event)) {
+      return;
+    }
+    this.resolvedTestIds.add(metadata.testId);
+    this.attemptsByTestId.delete(metadata.testId);
+    this.emit({
+      eventName: TestPulseDerivedEventName.TestOutcomeResolved,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      source: "synthetic",
+      ...metadata,
+      outcome: resolveOutcome(event, attempts),
+      attempts,
+      finalAttempt: attempt,
+      coreEvent: {
+        eventName: event.eventName,
+        timestamp: event.timestamp
+      }
+    }, { coreContext: context });
+  }
+  emit(event, context) {
+    for (const plugin of this.plugins) {
+      const handler = plugin[event.eventName];
+      if (!handler) {
+        continue;
+      }
+      try {
+        handler.call(plugin, event, context);
+      } catch (error) {
+        const handlerError = {
+          source: "@testpulse.run/playwright-events",
+          eventName: event.eventName,
+          pluginName: plugin.name,
+          error
+        };
+        this.handlerErrors.push(handlerError);
+        this.errorSink?.recordHandlerError(handlerError);
+      }
+    }
+  }
+  reset() {
+    this.handlerErrors.length = 0;
+    this.attemptsByTestId.clear();
+    this.resolvedTestIds.clear();
+  }
+};
+function createMetadata(event) {
+  return {
+    ...event.test,
+    testId: event.test.testId ?? event.titlePath.join(" \u203A "),
+    test: event.test,
+    titlePath: event.titlePath,
+    worker: event.worker
+  };
+}
+function createAttempt(event) {
+  return {
+    attemptIndex: event.retry,
+    retry: event.retry,
+    status: event.status,
+    durationMs: event.durationMs,
+    errors: event.errors,
+    attachments: event.attachments
+  };
+}
+function isFinalAttempt(event) {
+  return event.status === event.expectedStatus || event.retry >= (event.test.retryCount ?? 0) || event.status === "skipped" || event.status === "interrupted";
+}
+function resolveOutcome(event, attempts) {
+  if (event.status === "skipped") {
+    return "skipped";
+  }
+  if (event.status === "interrupted") {
+    return "interrupted";
+  }
+  if (event.status === "timedOut") {
+    return "timedOut";
+  }
+  if (event.status === "passed") {
+    return attempts.some((attempt) => attempt.status === "failed" || attempt.status === "timedOut" || attempt.status === "interrupted") ? "flaky" : "passed";
+  }
+  return "failed";
+}
+export {
+  PlaywrightEvents,
+  TestPulseDerivedEventName
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@testpulse.run/playwright-events",
+  "version": "0.2.3",
+  "description": "Derived Playwright test events for TestPulse reporters.",
+  "homepage": "https://testpulse.run",
+  "keywords": [
+    "testpulse",
+    "playwright",
+    "playwright-reporter",
+    "test-events",
+    "test-automation",
+    "testing",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@testpulse.run/playwright-core": "0.2.3"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0"
+  }
+}