@piwitests/reporter 0.4.2

package/dist/run-submitter.d.ts

@@ -0,0 +1,66 @@
+import type { FullResult } from '@playwright/test/reporter';
+import type { PiwiDashboardOptions, ShardInfo } from './config.js';
+import { HttpClient } from './http-client.js';
+import { Uploader } from './uploader.js';
+import { CrashRecovery } from './crash-recovery.js';
+import { StreamManager } from './stream-manager.js';
+import { Logger } from './logger.js';
+import type { CollectedTestCase, SetupStep, FilterDetails } from './types.js';
+/**
+ * Snapshot of everything the reporter has collected by `onEnd`, handed off to
+ * the `RunSubmitter` so the reporter itself stays a thin collect-and-hand-off
+ * shell.
+ */
+export interface CollectedRun {
+    options: PiwiDashboardOptions;
+    testCases: CollectedTestCase[];
+    startTime: string | null;
+    playwrightVersion: string | null;
+    totalTests: number;
+    passedTests: number;
+    failedTests: number;
+    skippedTests: number;
+    timedOutTests: number;
+    didNotRunTests: number;
+    metadata: Record<string, any>;
+    instanceId: string;
+    shardInfo: ShardInfo | null;
+    setupSteps: SetupStep[];
+    isFullRun: boolean;
+    filterDetails: FilterDetails | null;
+}
+/**
+ * Owns the three-tier submit/fallback ladder:
+ *
+ *   1. finalize the streaming run (`/finish`) when streaming is active,
+ *   2. fall back to multipart upload (`/upload`) when there are reports or
+ *      traces to attach,
+ *   3. fall back to plain JSON (`/submit`) as the last resort, persisting a
+ *      recovery payload on total failure.
+ *
+ * The order and logging are identical to the pre-extraction reporter — this is
+ * a move, not a redesign.
+ */
+export declare class RunSubmitter {
+    private readonly httpClient;
+    private readonly uploader;
+    private readonly recovery;
+    private readonly streamManager;
+    private readonly logger;
+    /**
+     * @param httpClient    HTTP client for auth resolution and the finish call.
+     * @param uploader      Upload strategies (multipart + JSON).
+     * @param recovery      Crash-recovery persistence.
+     * @param streamManager Streaming session (may be `null` when streaming is disabled).
+     * @param logger        Prefixed logger.
+     */
+    constructor(httpClient: HttpClient, uploader: Uploader, recovery: CrashRecovery, streamManager: StreamManager | null, logger?: Logger);
+    /** Run the fallback ladder for a completed test run. */
+    submit(run: CollectedRun, result: FullResult): Promise<void>;
+    private hasReports;
+    private reportOptions;
+    private buildRunPayload;
+    private tryFinishStreaming;
+    private tryUploadWithFiles;
+    private tryUploadJSON;
+}

package/dist/run-submitter.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunSubmitter = void 0;
+const logger_js_1 = require("./logger.js");
+const step_analyzer_js_1 = require("./step-analyzer.js");
+const serializer_js_1 = require("./serializer.js");
+/**
+ * Owns the three-tier submit/fallback ladder:
+ *
+ *   1. finalize the streaming run (`/finish`) when streaming is active,
+ *   2. fall back to multipart upload (`/upload`) when there are reports or
+ *      traces to attach,
+ *   3. fall back to plain JSON (`/submit`) as the last resort, persisting a
+ *      recovery payload on total failure.
+ *
+ * The order and logging are identical to the pre-extraction reporter — this is
+ * a move, not a redesign.
+ */
+class RunSubmitter {
+    /**
+     * @param httpClient    HTTP client for auth resolution and the finish call.
+     * @param uploader      Upload strategies (multipart + JSON).
+     * @param recovery      Crash-recovery persistence.
+     * @param streamManager Streaming session (may be `null` when streaming is disabled).
+     * @param logger        Prefixed logger.
+     */
+    constructor(httpClient, uploader, recovery, streamManager, logger = new logger_js_1.Logger()) {
+        this.httpClient = httpClient;
+        this.uploader = uploader;
+        this.recovery = recovery;
+        this.streamManager = streamManager;
+        this.logger = logger;
+    }
+    /** Run the fallback ladder for a completed test run. */
+    async submit(run, result) {
+        const endTime = new Date().toISOString();
+        const duration = new Date(endTime).getTime() - new Date(run.startTime).getTime();
+        const overallStatus = (0, serializer_js_1.resolveOverallStatus)(result, {
+            failedTests: run.failedTests,
+            timedOutTests: run.timedOutTests,
+            totalTests: run.totalTests,
+        });
+        this.logger.info(`Test run completed. Status: ${overallStatus} (Playwright result.status: ${result?.status || 'undefined'})`);
+        this.logger.info(`Total: ${run.totalTests}, Passed: ${run.passedTests}, Failed: ${run.failedTests}, Skipped: ${run.skippedTests}, TimedOut: ${run.timedOutTests}, DidNotRun: ${run.didNotRunTests}`);
+        if (run.options.collectPerformanceMetrics) {
+            run.metadata.performance = (0, step_analyzer_js_1.computePerformanceSummary)(run.testCases);
+        }
+        const sm = this.streamManager;
+        if (sm?.startPromise)
+            await sm.startPromise;
+        await sm?.drain();
+        let auth;
+        try {
+            auth = sm?.auth ?? (await this.httpClient.resolveAuth(run.options));
+        }
+        catch (error) {
+            this.logger.error(`Authentication failed: ${error.message}`);
+            throw error;
+        }
+        if (sm?.enabled && sm?.runId != null) {
+            if (await this.tryFinishStreaming(run, overallStatus, duration, auth))
+                return;
+        }
+        if (this.hasReports(run) || run.options.uploadTraces) {
+            if (await this.tryUploadWithFiles(run, overallStatus, duration, auth))
+                return;
+        }
+        await this.tryUploadJSON(run, overallStatus, duration, auth);
+    }
+    hasReports(run) {
+        return !!run.options.uploadReport || (run.options.reports?.length ?? 0) > 0;
+    }
+    reportOptions(run) {
+        return {
+            uploadTraces: run.options.uploadTraces,
+            uploadReport: run.options.uploadReport,
+            reports: run.options.reports,
+        };
+    }
+    buildRunPayload(run, status, duration) {
+        return {
+            projectName: run.options.projectName,
+            projectDescription: run.options.projectDescription,
+            status,
+            startTime: run.startTime,
+            duration,
+            totalTests: run.totalTests,
+            passedTests: run.passedTests,
+            failedTests: run.failedTests,
+            skippedTests: run.skippedTests,
+            didNotRunTests: run.didNotRunTests,
+            environment: run.options.environment,
+            label: run.options.label || null,
+            metadata: run.metadata,
+            instanceId: run.instanceId,
+            playwrightVersion: run.playwrightVersion ?? undefined,
+            testCases: run.testCases,
+            shardIndex: run.shardInfo?.current,
+            shardTotal: run.shardInfo?.total,
+            isFullRun: run.isFullRun,
+            filterDetails: run.filterDetails,
+        };
+    }
+    async tryFinishStreaming(run, overallStatus, duration, auth) {
+        const sm = this.streamManager;
+        try {
+            const flakyTests = run.testCases.filter((tc) => tc.status === 'passed' && (tc.retries || 0) > 0).length;
+            const durations = run.testCases.filter((tc) => tc.duration != null).map((tc) => tc.duration);
+            await sm.uploadRemaining(run.testCases);
+            const finishBody = {
+                streamToken: sm.token,
+                status: overallStatus,
+                duration,
+                totalTests: run.totalTests,
+                passedTests: run.passedTests,
+                failedTests: run.failedTests,
+                skippedTests: run.skippedTests,
+                didNotRunTests: run.didNotRunTests,
+                flakyTests,
+                durations,
+                label: run.options.label || null,
+                metadata: run.metadata,
+                hasPendingUploads: this.hasReports(run),
+                playwrightVersion: run.playwrightVersion ?? undefined,
+                setupSteps: run.setupSteps.length > 0 ? run.setupSteps : undefined,
+                isFullRun: run.isFullRun,
+                filterDetails: run.filterDetails ?? null,
+            };
+            if (run.shardInfo) {
+                finishBody.shardIndex = run.shardInfo.current;
+                finishBody.shardTotal = run.shardInfo.total;
+            }
+            await this.httpClient.postJSON(`/api/test-runs/${sm.runId}/finish`, finishBody, auth);
+            this.logger.info(`Successfully finalized streaming run #${sm.runId}`);
+            this.recovery.clear();
+            if (this.hasReports(run)) {
+                try {
+                    await this.uploader.uploadReportsForStreamingRun(run.options.projectName, sm.runId, this.reportOptions(run), run.startTime, auth);
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to upload reports for streaming run: ${error.message}`);
+                }
+            }
+            return true;
+        }
+        catch (error) {
+            this.logger.warn(`Failed to finalize streaming run: ${error.message}`);
+            this.logger.info('Falling back to batch upload...');
+            return false;
+        }
+    }
+    async tryUploadWithFiles(run, overallStatus, duration, auth) {
+        try {
+            await this.uploader.uploadWithFiles(this.buildRunPayload(run, overallStatus, duration), this.reportOptions(run), auth);
+            this.recovery.clear();
+            return true;
+        }
+        catch (error) {
+            if (error.message?.includes('401') && !auth)
+                throw error;
+            this.logger.warn(`Failed to upload with files: ${error.message}`);
+            this.logger.info('Falling back to JSON upload...');
+            return false;
+        }
+    }
+    async tryUploadJSON(run, overallStatus, duration, auth) {
+        const payload = this.buildRunPayload(run, overallStatus, duration);
+        try {
+            await this.uploader.uploadJSON(payload, auth);
+            this.recovery.clear();
+        }
+        catch (error) {
+            // If the server returned 401 and no auth was configured, this is a
+            // configuration error — throw so the caller knows it's fatal.
+            if (error.message?.includes('401') && !auth)
+                throw error;
+            this.logger.error(`All upload methods failed: ${error.message}`);
+            // Save the wire-serialized form so the recovery file matches the
+            // original submit payload (no raw attachments / internal fields).
+            this.recovery.save((0, serializer_js_1.serializeRun)(payload, { includeTestCases: true }));
+        }
+    }
+}
+exports.RunSubmitter = RunSubmitter;

package/dist/serializer.d.ts

@@ -0,0 +1,45 @@
+import type { FullResult } from '@playwright/test/reporter';
+import type { CollectedTestCase, WireTestCase } from './types.js';
+import type { RunPayload } from './uploader.js';
+/**
+ * Resolve the overall Piwi run status from Playwright's `FullResult.status`
+ * and the accumulated per-case counters.
+ *
+ * `passed`/`failed`/`timedout`/`interrupted` map directly; when Playwright
+ * doesn't report a status, the run is `passed` only when no test failed or
+ * timed out (and at least one test ran).
+ */
+export declare function resolveOverallStatus(result: FullResult, counters: {
+    failedTests: number;
+    timedOutTests: number;
+    totalTests: number;
+}): string;
+/**
+ * Project an internally-collected test-case object into the wire shape sent to
+ * the server. Carries the `type` discriminant through so the same mapper works
+ * for `begin` and `complete` stream events as well as batch submissions.
+ *
+ * Quirks preserved from the original in-reporter implementation:
+ * - `status`/`duration`/`error`/`retries` pass through unchanged (no `null`
+ *   default), so a `begin` event yields `undefined` for those fields.
+ * - Numeric/array fields use `|| null` (so `0` and `''` collapse to `null`),
+ *   while `workerIndex`/`shardIndex`/`startedAt`/`suitePath`/`suiteConfig`/
+ *   `testAnnotations` use `?? null` (so `0` survives). Note: an empty array
+ *   is truthy, so `steps: []` is preserved as `[]`, not `null`.
+ */
+export declare function toWireTestCase(tc: CollectedTestCase): WireTestCase;
+/** Options for `serializeRun`. */
+export interface SerializeRunOptions {
+    /** Include `testCases` (projected to wire shape) in the serialized body. */
+    includeTestCases: boolean;
+}
+/**
+ * Serialize a `RunPayload` into the JSON body sent to `/api/test-runs/submit`
+ * (with `includeTestCases: true`) or the `testRun` form field of
+ * `/api/test-runs/upload` (with `includeTestCases: false`, since the multipart
+ * path appends `testCases` as a separate form field).
+ *
+ * This is the single source of truth for the run-level field list — adding a
+ * field touches this helper plus the `RunPayload` type, not three files.
+ */
+export declare function serializeRun(payload: RunPayload, opts: SerializeRunOptions): Record<string, unknown>;

package/dist/serializer.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOverallStatus = resolveOverallStatus;
+exports.toWireTestCase = toWireTestCase;
+exports.serializeRun = serializeRun;
+/**
+ * Resolve the overall Piwi run status from Playwright's `FullResult.status`
+ * and the accumulated per-case counters.
+ *
+ * `passed`/`failed`/`timedout`/`interrupted` map directly; when Playwright
+ * doesn't report a status, the run is `passed` only when no test failed or
+ * timed out (and at least one test ran).
+ */
+function resolveOverallStatus(result, counters) {
+    const STATUS_MAP = {
+        passed: 'passed',
+        failed: 'failed',
+        timedout: 'failed',
+        interrupted: 'failed',
+    };
+    if (result?.status)
+        return STATUS_MAP[result.status] ?? 'failed';
+    if (counters.failedTests === 0 && counters.timedOutTests === 0 && counters.totalTests > 0)
+        return 'passed';
+    return 'failed';
+}
+/**
+ * Project an internally-collected test-case object into the wire shape sent to
+ * the server. Carries the `type` discriminant through so the same mapper works
+ * for `begin` and `complete` stream events as well as batch submissions.
+ *
+ * Quirks preserved from the original in-reporter implementation:
+ * - `status`/`duration`/`error`/`retries` pass through unchanged (no `null`
+ *   default), so a `begin` event yields `undefined` for those fields.
+ * - Numeric/array fields use `|| null` (so `0` and `''` collapse to `null`),
+ *   while `workerIndex`/`shardIndex`/`startedAt`/`suitePath`/`suiteConfig`/
+ *   `testAnnotations` use `?? null` (so `0` survives). Note: an empty array
+ *   is truthy, so `steps: []` is preserved as `[]`, not `null`.
+ */
+function toWireTestCase(tc) {
+    const { type, ...rest } = tc;
+    return {
+        type,
+        title: rest.title,
+        location: rest.location,
+        status: rest.status,
+        duration: rest.duration,
+        error: rest.error,
+        retries: rest.retries,
+        workerIndex: rest.workerIndex ?? null,
+        shardIndex: rest.shardIndex ?? null,
+        startedAt: rest.startedAt ?? null,
+        steps: rest.performanceMetrics?.steps || null,
+        stepEvents: rest.stepEvents || null,
+        slowestStep: rest.performanceMetrics?.slowestStep?.title || null,
+        slowestStepDuration: rest.performanceMetrics?.slowestStep?.duration || null,
+        wastedTimeMs: rest.performanceMetrics?.waitTotalDuration ?? null,
+        networkRequests: rest.networkRequests || null,
+        webVitals: rest.webVitals || null,
+        consoleLogs: rest.consoleLogs || null,
+        ariaSnapshot: rest.ariaSnapshot || null,
+        testSource: rest.testSource || null,
+        browser: rest.browser || null,
+        suitePath: rest.suitePath ?? null,
+        suiteConfig: rest.suiteConfig ?? null,
+        testAnnotations: rest.testAnnotations ?? null,
+    };
+}
+/**
+ * Serialize a `RunPayload` into the JSON body sent to `/api/test-runs/submit`
+ * (with `includeTestCases: true`) or the `testRun` form field of
+ * `/api/test-runs/upload` (with `includeTestCases: false`, since the multipart
+ * path appends `testCases` as a separate form field).
+ *
+ * This is the single source of truth for the run-level field list — adding a
+ * field touches this helper plus the `RunPayload` type, not three files.
+ */
+function serializeRun(payload, opts) {
+    const body = {
+        projectName: payload.projectName,
+        projectDescription: payload.projectDescription,
+        status: payload.status,
+        startTime: payload.startTime,
+        duration: payload.duration,
+        totalTests: payload.totalTests,
+        passedTests: payload.passedTests,
+        failedTests: payload.failedTests,
+        skippedTests: payload.skippedTests,
+        didNotRunTests: payload.didNotRunTests ?? 0,
+        environment: payload.environment ?? null,
+        label: payload.label ?? null,
+        metadata: payload.metadata,
+        instanceId: payload.instanceId,
+        playwrightVersion: payload.playwrightVersion,
+        shardIndex: payload.shardIndex,
+        shardTotal: payload.shardTotal,
+        isFullRun: payload.isFullRun ?? true,
+        filterDetails: payload.filterDetails ?? null,
+    };
+    if (opts.includeTestCases) {
+        body.testCases = payload.testCases.map((tc) => toWireTestCase(tc));
+    }
+    return body;
+}

package/dist/skip-classify.d.ts

@@ -0,0 +1,27 @@
+import type { TestAnnotation } from './types.js';
+/** Minimal structural shape for the annotation carriers (avoids importing Playwright types). */
+interface AnnotationCarrier {
+    annotations?: ReadonlyArray<{
+        type: string;
+        description?: string;
+    }>;
+}
+/**
+ * Merge a test's declared annotations (`test.annotations`) with its result-level
+ * annotations (`result.annotations`), deduped by `type + description`. Runtime
+ * `test.skip('reason')` calls can surface on either side depending on the
+ * Playwright version, so both are considered.
+ */
+export declare function mergeAnnotations(test: AnnotationCarrier, result: AnnotationCarrier): TestAnnotation[];
+/**
+ * Distinguish an intentional skip from a test that could not run.
+ *
+ * Playwright reports both as `result.status === 'skipped'`, but an intentional
+ * `test.skip()` / `test.fixme()` (static, conditional, or runtime) always
+ * carries a `skip`/`fixme` annotation, while a test skipped as a side effect of
+ * an earlier failure in a `describe.serial` group carries none. The latter is
+ * reclassified to `didnotrun` so the dashboard can tell "deliberately skipped"
+ * from "never actually executed". Non-skipped statuses pass through unchanged.
+ */
+export declare function classifyStatus(rawStatus: string, annotations: TestAnnotation[]): string;
+export {};

package/dist/skip-classify.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeAnnotations = mergeAnnotations;
+exports.classifyStatus = classifyStatus;
+/**
+ * Merge a test's declared annotations (`test.annotations`) with its result-level
+ * annotations (`result.annotations`), deduped by `type + description`. Runtime
+ * `test.skip('reason')` calls can surface on either side depending on the
+ * Playwright version, so both are considered.
+ */
+function mergeAnnotations(test, result) {
+    const out = [];
+    const seen = new Set();
+    for (const list of [test.annotations, result.annotations]) {
+        for (const a of list ?? []) {
+            const key = `${a.type}\x00${a.description ?? ''}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(a.description === undefined ? { type: a.type } : { type: a.type, description: a.description });
+        }
+    }
+    return out;
+}
+/**
+ * Distinguish an intentional skip from a test that could not run.
+ *
+ * Playwright reports both as `result.status === 'skipped'`, but an intentional
+ * `test.skip()` / `test.fixme()` (static, conditional, or runtime) always
+ * carries a `skip`/`fixme` annotation, while a test skipped as a side effect of
+ * an earlier failure in a `describe.serial` group carries none. The latter is
+ * reclassified to `didnotrun` so the dashboard can tell "deliberately skipped"
+ * from "never actually executed". Non-skipped statuses pass through unchanged.
+ */
+function classifyStatus(rawStatus, annotations) {
+    if (rawStatus !== 'skipped')
+        return rawStatus;
+    const intentional = annotations.some((a) => a.type === 'skip' || a.type === 'fixme');
+    return intentional ? 'skipped' : 'didnotrun';
+}

package/dist/step-analyzer.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Categorise a Playwright step into `navigation`, `action`, `input`,
+ * `assertion`, `wait`, `api`, `hook`, or `other`.
+ *
+ * Supports two title formats:
+ *  - Legacy api-path titles ("page.goto", "locator.click", "page.waitForTimeout")
+ *  - Modern human-readable titles introduced in newer Playwright versions
+ *    ("Navigate to \"{url}\"", "Click", "Wait for timeout", "Wait for load state").
+ * Hook/fixture/expect steps are detected via Playwright's own `category`.
+ */
+export declare function categorizeStep(title: string, pwCategory?: string): string;
+/** A single step flattened from the Playwright step tree with its derived category */
+export interface FlatStep {
+    title: string;
+    duration: number;
+    category: string;
+}
+/** Step-event category restricted to the values `extractTestStepEvents` emits. */
+export type StepEventCategory = 'hook' | 'fixture' | 'test.step' | 'expect' | 'wait';
+/** Recursively flatten a nested step tree into a flat list. Uses Playwright's built-in category when available. */
+export declare function flattenSteps(steps: any[]): FlatStep[];
+/** Aggregated step performance data for a single test case */
+export interface StepMetrics {
+    /** Flattened step list with categories */
+    steps: FlatStep[];
+    /** Sum of top-level step durations */
+    totalStepDuration: number;
+    /** The single slowest step (by duration) */
+    slowestStep: {
+        title: string;
+        duration: number;
+    } | null;
+    /** How many navigation steps were executed */
+    navigationCount: number;
+    /** Total wall-clock time spent in navigation steps */
+    navigationTotalDuration: number;
+    /** Total wall-clock time spent in wait steps (wasted time) */
+    waitTotalDuration: number;
+    /** Count of wait steps */
+    waitCount: number;
+}
+/** Collect step metrics (flat steps, slowest step, navigation stats) from a Playwright step array */
+export declare function collectStepMetrics(steps: any[]): StepMetrics;
+/** Calculate the p-th percentile from a sorted array of numbers */
+export declare function percentile(sortedArr: number[], p: number): number;
+/** Summary performance statistics for a complete test run */
+export interface PerformanceSummary {
+    /** Average test-case duration in ms */
+    avgTestDuration?: number;
+    /** Median (P50) test-case duration in ms */
+    p50TestDuration?: number;
+    /** P90 test-case duration in ms */
+    p90TestDuration?: number;
+    /** P95 test-case duration in ms */
+    p95TestDuration?: number;
+    /** Up to 5 slowest test cases */
+    slowestTests?: Array<{
+        title: string;
+        duration: number;
+    }>;
+    /** Total time spent in navigation steps across all cases */
+    totalNavigationDuration?: number;
+    /** Average time per navigation step */
+    avgNavigationDuration?: number;
+    /** Total time spent in wait steps across all cases */
+    totalWastedTimeMs?: number;
+}
+/** Compute run-level performance summary (averages, percentiles, slowest tests) from all test cases */
+export declare function computePerformanceSummary(testCases: any[]): PerformanceSummary;
+/**
+ * Extract hook and fixture step events with absolute timings from a Playwright
+ * step tree. These are used by the WorkersTimeline to render hook segments.
+ *
+ * Returns only top-level hook/fixture steps (beforeEach, afterEach, fixture
+ * setup/teardown) — their sub-steps are included implicitly in their duration.
+ */
+export declare function extractTestStepEvents(steps: any[], _testStartTime: Date): Array<{
+    title: string;
+    category: StepEventCategory;
+    startedAt: number;
+    duration: number;
+    status: string;
+    location?: string | null;
+}>;
+/**
+ * Recursively extract wait-category steps from the Playwright step tree
+ * with absolute timings. These are rendered as semi-transparent amber bars
+ * on WorkersTimeline to visualize wasted time.
+ */
+export declare function extractWaitEvents(steps: any[], insideWait?: boolean): Array<{
+    title: string;
+    category: StepEventCategory;
+    startedAt: number;
+    duration: number;
+    status: string;
+    location?: string | null;
+}>;