@piwitests/reporter 0.4.2

package/dist/stream-manager.js

@@ -0,0 +1,338 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamManager = void 0;
+const fs = __importStar(require("fs"));
+const logger_js_1 = require("./logger.js");
+const helpers_js_1 = require("./helpers.js");
+/**
+ * Manages the streaming protocol: queues events (begin / complete), flushes
+ * them in batches, schedules retries on failure, and handles per-test-case
+ * live file uploads.
+ */
+class StreamManager {
+    /** Whether the streaming session is active */
+    get enabled() {
+        return this._enabled;
+    }
+    /** Server-assigned run ID (`null` until the stream opens) */
+    get runId() {
+        return this._runId;
+    }
+    /** Stream authentication token (`null` until the stream opens) */
+    get token() {
+        return this._token;
+    }
+    /** Resolved auth string (API key or session cookie) used in stream requests */
+    get auth() {
+        return this._auth;
+    }
+    /** Promise that resolves when the stream has been fully initialised */
+    get startPromise() {
+        return this._startPromise;
+    }
+    /**
+     * @param httpClient  HTTP client for server communication.
+     * @param streamBuffer On-disk buffer for crash-safe event persistence.
+     * @param recovery    Crash-recovery handler for uploading stale payloads on startup.
+     * @param uploader    Uploader for per-test-case file uploads.
+     * @param fileHandler File-discovery helper for finding traces and attachments.
+     * @param options     Piwi Dashboard reporter options.
+     * @param logger      Prefixed logger.
+     */
+    constructor(httpClient, streamBuffer, recovery, uploader, fileHandler, options, logger = new logger_js_1.Logger()) {
+        this.httpClient = httpClient;
+        this.streamBuffer = streamBuffer;
+        this.recovery = recovery;
+        this.uploader = uploader;
+        this.fileHandler = fileHandler;
+        this.options = options;
+        this.logger = logger;
+        this.pendingEvents = [];
+        this.pendingBeginEvents = [];
+        this.flushTimer = null;
+        this.flushPromises = [];
+        this.liveUploadPromises = [];
+        this.limitLiveUpload = (0, helpers_js_1.createLimiter)(2);
+        this.retryCount = 0;
+        this.retryTimer = null;
+        this.maxRetryDelay = 30000;
+        /** Tracks cases whose files have already been uploaded live, so `uploadRemaining` can skip them. */
+        this.uploadedCaseFiles = new WeakSet();
+        this._enabled = false;
+        this._runId = null;
+        this._token = null;
+        this._auth = null;
+        this._startPromise = null;
+    }
+    /** Begin the streaming session after `onBegin` fires. Non-blocking — the actual handshake runs asynchronously. */
+    start(startTime, metadata, instanceId, playwrightVersion, shardInfo, isFullRun, filterDetails) {
+        this._startPromise = this._doStart(startTime, metadata, instanceId, playwrightVersion, shardInfo, isFullRun, filterDetails);
+    }
+    async _doStart(startTime, metadata, instanceId, playwrightVersion, shardInfo, isFullRun, filterDetails) {
+        const setupInfo = (0, helpers_js_1.readSetupInfo)(this.options.projectName);
+        try {
+            this._auth = await this.httpClient.resolveAuth(this.options);
+            await this.recovery.tryUpload(this.httpClient, this._auth);
+            let response;
+            const shardIndex = shardInfo?.current;
+            const shardTotal = shardInfo?.total;
+            if (setupInfo) {
+                try {
+                    response = await this.httpClient.postJSON(`/api/test-runs/${setupInfo.runId}/begin`, {
+                        setupToken: setupInfo.setupToken,
+                        totalTests: 0,
+                        metadata,
+                        playwrightVersion,
+                        shardIndex,
+                        shardTotal,
+                        isFullRun,
+                        filterDetails,
+                    }, this._auth);
+                }
+                catch (beginError) {
+                    // Stale setupInfo — the run was cancelled (e.g. by crash recovery submit).
+                    // Fall back to creating a fresh run instead of silently disabling streaming.
+                    if (!beginError.message?.includes('409'))
+                        throw beginError;
+                    this.logger.debug(`Setup info expired, creating fresh run...`);
+                    response = await this.httpClient.postJSON('/api/test-runs/start', {
+                        projectName: this.options.projectName,
+                        projectDescription: this.options.projectDescription,
+                        startTime,
+                        environment: this.options.environment || null,
+                        label: this.options.label || null,
+                        metadata,
+                        instanceId,
+                        playwrightVersion,
+                        shardIndex,
+                        shardTotal,
+                        isFullRun,
+                        filterDetails,
+                    }, this._auth);
+                }
+            }
+            else {
+                response = await this.httpClient.postJSON('/api/test-runs/start', {
+                    projectName: this.options.projectName,
+                    projectDescription: this.options.projectDescription,
+                    startTime,
+                    environment: this.options.environment || null,
+                    label: this.options.label || null,
+                    metadata,
+                    instanceId,
+                    playwrightVersion,
+                    shardIndex,
+                    shardTotal,
+                    isFullRun,
+                    filterDetails,
+                }, this._auth);
+            }
+            if (response?.runId && response?.streamToken) {
+                this._runId = response.runId;
+                this._token = response.streamToken;
+                this._enabled = true;
+                this.logger.info(`Streaming enabled. Run ID: ${response.runId}`);
+                if (this.pendingBeginEvents.length > 0) {
+                    this.pendingEvents = [...this.pendingBeginEvents, ...this.pendingEvents];
+                    this.pendingBeginEvents = [];
+                    this.flush();
+                }
+            }
+        }
+        catch (error) {
+            this.logger.debug(`Streaming not available: ${error.message}. Will use batch mode.`);
+            this._enabled = false;
+        }
+    }
+    // Queues a begin event; held in a pre-start buffer until the stream is open,
+    // then prepended to the main queue so it arrives before the matching complete event.
+    /** Queue a test-case `begin` event. Held in a pre-start buffer if the stream is not yet open, then prepended so it arrives before the matching `complete` event. */
+    queueBeginEvent(event) {
+        if (this._enabled && this._runId) {
+            this.queueEvent(event);
+        }
+        else {
+            this.pendingBeginEvents.push(event);
+        }
+    }
+    /** Queue a test-case event. Triggers an immediate flush when the batch size is reached, otherwise schedules a timer-based flush. */
+    queueEvent(event) {
+        this.pendingEvents.push(event);
+        if (this.pendingEvents.length >= this.options.streamingBatchSize) {
+            this.flush();
+        }
+        else if (!this.flushTimer) {
+            this.flushTimer = setTimeout(() => this.flush(), this.options.streamingBatchDelay);
+        }
+    }
+    /** Flush all pending events to the server. Returns a promise that resolves to `true` on success or `false` on failure (events are re-queued for retry). */
+    flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.pendingEvents.length === 0 || !this._enabled || !this._runId)
+            return null;
+        const events = this.pendingEvents.splice(0);
+        // Never rejects: failed events are re-queued so the retry timer or the
+        // end-of-run drain can resend them (the server deduplicates).
+        const promise = this.httpClient
+            .postJSON(`/api/test-runs/${this._runId}/events`, { streamToken: this._token, testCases: events }, this._auth)
+            .then(() => {
+            this.retryCount = 0;
+            return true;
+        }, () => {
+            this.pendingEvents = events.concat(this.pendingEvents);
+            this.scheduleRetry();
+            return false;
+        });
+        this.flushPromises.push(promise);
+        return promise;
+    }
+    scheduleRetry() {
+        if (this.retryTimer)
+            return;
+        this.retryCount++;
+        const delay = Math.min(1000 * Math.pow(2, this.retryCount - 1), this.maxRetryDelay);
+        this.logger.debug(`Will retry streaming flush in ${delay}ms (attempt ${this.retryCount})`);
+        this.retryTimer = setTimeout(() => {
+            this.retryTimer = null;
+            const buffered = this.streamBuffer.load();
+            if (buffered.length > 0) {
+                this.streamBuffer.clear();
+                this.pendingEvents = buffered.concat(this.pendingEvents);
+            }
+            if (this.pendingEvents.length > 0)
+                this.flush();
+        }, delay);
+    }
+    /** Drain all pending and buffered events before the run finishes. Retries up to 10 times with exponential back-off. */
+    async drain() {
+        if (!this._enabled) {
+            this.pendingEvents = [];
+            this.flushPromises = [];
+            return;
+        }
+        const MAX_ATTEMPTS = 10;
+        for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+            if (this._enabled && this.pendingEvents.length > 0)
+                this.flush();
+            if (this.flushPromises.length > 0) {
+                await Promise.allSettled(this.flushPromises);
+                this.flushPromises = [];
+            }
+            if (this.pendingEvents.length === 0) {
+                const buffered = this.streamBuffer.load();
+                if (buffered.length > 0) {
+                    this.pendingEvents = buffered;
+                    this.streamBuffer.clear();
+                    continue;
+                }
+                return;
+            }
+            this.logger.debugError(`${this.pendingEvents.length} events pending, retrying (attempt ${attempt + 1}/${MAX_ATTEMPTS})...`);
+            await new Promise((resolve) => setTimeout(resolve, Math.min(1000 * Math.pow(2, attempt), 10000)));
+        }
+        if (this.pendingEvents.length > 0) {
+            this.streamBuffer.append(this.pendingEvents);
+            this.pendingEvents = [];
+        }
+    }
+    /** Schedule a live upload of trace and attachment files for a test case. Skips cases with no files. Concurrency is limited to 2 simultaneous uploads. */
+    scheduleLiveUpload(tc) {
+        const hasTrace = !!this.options.uploadTraces && this.fileHandler.findTraceFiles(tc).some((p) => fs.existsSync(p));
+        const hasAttachments = this.fileHandler.findAllAttachments(tc).length > 0;
+        if (!hasTrace && !hasAttachments)
+            return;
+        const promise = (async () => {
+            if (this._startPromise)
+                await this._startPromise;
+            if (!this._enabled || !this._runId || !this._token)
+                return;
+            // The complete event must reach the server before it can link files.
+            // queueEvent may have already triggered a batch-size flush that took all
+            // pending events, making our flush() return null.  Wait for any in-flight
+            // flush promises first, then try to flush remaining events.
+            if (this.flushPromises.length > 0) {
+                await Promise.allSettled(this.flushPromises);
+            }
+            const flush = this.flush();
+            if (flush)
+                await flush;
+            // Retry on 404: the events batch carrying this case may still be in flight
+            const delays = [0, 1000, 3000];
+            for (let attempt = 0; attempt < delays.length; attempt++) {
+                if (delays[attempt])
+                    await new Promise((resolve) => setTimeout(resolve, delays[attempt]));
+                try {
+                    await this.limitLiveUpload(() => this.uploader.uploadCaseFiles(this.options.projectName, this._runId, this._token, tc, this.options.uploadTraces, this._auth));
+                    this.uploadedCaseFiles.add(tc);
+                    return;
+                }
+                catch (error) {
+                    const retryable = error.message?.includes('404');
+                    if (!retryable || attempt === delays.length - 1) {
+                        this.logger.debug(`Live file upload failed for "${tc.title}": ${error.message}`);
+                        return; // The end-of-run pass retries cases that failed here
+                    }
+                }
+            }
+        })();
+        this.liveUploadPromises.push(promise);
+    }
+    /** Wait for all live uploads to settle, then upload files for any test cases that weren't uploaded live */
+    async uploadRemaining(testCases) {
+        if (this.liveUploadPromises.length > 0) {
+            await Promise.allSettled(this.liveUploadPromises);
+            this.liveUploadPromises = [];
+        }
+        if (!this._enabled || !this._runId || !this._token)
+            return;
+        for (const tc of testCases) {
+            if (this.uploadedCaseFiles.has(tc))
+                continue;
+            try {
+                const uploaded = await this.uploader.uploadCaseFiles(this.options.projectName, this._runId, this._token, tc, this.options.uploadTraces, this._auth);
+                if (uploaded)
+                    this.uploadedCaseFiles.add(tc);
+            }
+            catch (error) {
+                this.logger.warn(`Failed to upload files for "${tc.title}": ${error.message}`);
+            }
+        }
+    }
+}
+exports.StreamManager = StreamManager;

package/dist/types.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Reporter-local domain model.
+ *
+ * These interfaces describe the data that flows *between* the reporter's
+ * classes (`FileHandler`, `Uploader`, `StreamManager`, `PiwiDashboardReporter`).
+ * They intentionally mirror — but do not import — the wire types in
+ * `application/shared/types.ts`. Importing that module would leak the monorepo
+ * path into the published `.d.ts` files; the constraint forbids the import,
+ * not the types. Keep these structurally compatible with
+ * `TestCasePayload` / `StreamEventPayload` / `TestRunFinishPayload` when
+ * evolving them.
+ */
+export interface SuiteConfigEntry {
+    mode: 'parallel' | 'serial' | 'default';
+    annotations: Array<{
+        type: string;
+        description?: string;
+    }>;
+}
+export interface TestAnnotation {
+    type: string;
+    description?: string;
+}
+/**
+ * Filter that narrowed a run to a subset of tests, recorded when `isFullRun`
+ * is false. Mirrors `FilterDetails` in `application/shared/types.ts`.
+ */
+export interface FilterDetails {
+    /** A non-default `--grep` pattern (Playwright's default `.*` is excluded). */
+    grep?: string;
+    /** A `--grep-invert` pattern. */
+    grepInvert?: string;
+    /** Positional file/path filters from the CLI invocation (e.g. ["tests/login.spec.ts"]). */
+    files?: string[];
+}
+export interface BrowserConfig {
+    projectName?: string;
+    browserName?: string | null;
+    channel?: string | null;
+    viewport?: {
+        width: number;
+        height: number;
+    } | null;
+    deviceScaleFactor?: number | null;
+    isMobile?: boolean | null;
+    hasTouch?: boolean | null;
+    locale?: string | null;
+    timezoneId?: string | null;
+    geolocation?: {
+        longitude: number;
+        latitude: number;
+        accuracy?: number;
+    } | null;
+    colorScheme?: string | null;
+    reducedMotion?: string | null;
+    forcedColors?: string | null;
+    offline?: boolean | null;
+    bypassCSP?: boolean | null;
+    javaScriptEnabled?: boolean | null;
+    serviceWorkers?: string | null;
+    userAgent?: string | null;
+}
+/**
+ * A raw Playwright attachment as exposed on `TestResult.attachments`.
+ * Carried verbatim on `CollectedTestCase.attachments` so `FileHandler` can
+ * resolve trace/attachment paths; never sent to the server.
+ */
+export interface RawAttachment {
+    name: string;
+    path?: string;
+    contentType?: string;
+    body?: Buffer;
+    originalName?: string;
+}
+/** Performance metrics collected from `result.steps` by `step-analyzer`. */
+export interface CollectedPerformanceMetrics {
+    steps: Array<{
+        title: string;
+        duration: number;
+        category: string;
+    }>;
+    totalStepDuration: number;
+    slowestStep: {
+        title: string;
+        duration: number;
+    } | null;
+    navigationCount: number;
+    navigationTotalDuration: number;
+    waitTotalDuration: number;
+    waitCount: number;
+}
+/** A hook/fixture step event with absolute timings (for the workers timeline). */
+export interface TestStepEvent {
+    title: string;
+    category: 'hook' | 'fixture' | 'test.step' | 'expect' | 'wait';
+    startedAt: number;
+    duration: number;
+    status: string;
+    location?: string | null;
+}
+/**
+ * What `onTestEnd` accumulates per test case. Mixes three concerns that the
+ * reporter must keep together during a run:
+ *  - **wire fields** (`title`, `status`, `duration`, …) that `toWireTestCase`
+ *    projects onto `WireTestCase` before sending,
+ *  - **collection-only state** (`attachments`, `performanceMetrics`,
+ *    `stepEvents`) consumed by `FileHandler` and the run-level summary,
+ *  - the `type` discriminant so the same collected object can be queued as a
+ *    stream event.
+ *
+ * Upload bookkeeping (`_filesUploaded`) is deliberately NOT on this object —
+ * `StreamManager` tracks it in a side `Set` so the data model stays clean.
+ */
+export interface CollectedTestCase {
+    /** Stream-event discriminant: `'begin'` or `'complete'`. Omitted for batch-only runs. */
+    type?: 'begin' | 'complete';
+    title: string;
+    location: string;
+    status?: string;
+    duration?: number;
+    error?: string | null;
+    retries?: number;
+    workerIndex?: number | null;
+    shardIndex?: number | null;
+    startedAt?: number | null;
+    /** Raw Playwright attachments — never sent on the wire. */
+    attachments?: RawAttachment[];
+    browser?: BrowserConfig | null;
+    suitePath?: string[] | null;
+    suiteConfig?: SuiteConfigEntry[] | null;
+    testAnnotations?: TestAnnotation[] | null;
+    /** Source snippet around the failing line (failed/timedOut only). */
+    testSource?: string;
+    /** Step metrics from `collectStepMetrics`. Consumed by the run summary + `toWireTestCase`. */
+    performanceMetrics?: CollectedPerformanceMetrics;
+    stepEvents?: TestStepEvent[];
+    /** Parsed from `piwi-dashboard-network` attachments by `FileHandler`. */
+    networkRequests?: unknown;
+    /** Parsed from `piwi-dashboard-web-vitals` attachments. */
+    webVitals?: unknown;
+    /** Parsed from `piwi-dashboard-console` attachments. */
+    consoleLogs?: unknown;
+    /** Parsed from `piwi-dashboard-aria-snapshot` attachment. */
+    ariaSnapshot?: string;
+}
+/**
+ * The per-case wire shape that `toWireTestCase` produces and the server
+ * receives. Structurally compatible with `TestCasePayload` and the per-event
+ * `StreamEventPayload`.
+ */
+export interface WireTestCase {
+    type?: 'begin' | 'complete' | 'step-begin' | 'step-end';
+    title: string;
+    location: string;
+    status?: string;
+    duration?: number;
+    error?: string | null;
+    retries?: number;
+    workerIndex?: number | null;
+    shardIndex?: number | null;
+    startedAt?: number | null;
+    steps?: unknown;
+    stepEvents?: TestStepEvent[] | null;
+    slowestStep?: string | null;
+    slowestStepDuration?: number | null;
+    wastedTimeMs?: number | null;
+    networkRequests?: unknown;
+    webVitals?: unknown;
+    consoleLogs?: unknown;
+    ariaSnapshot?: unknown;
+    testSource?: string | null;
+    browser?: BrowserConfig | null;
+    suitePath?: string[] | null;
+    suiteConfig?: SuiteConfigEntry[] | null;
+    testAnnotations?: TestAnnotation[] | null;
+    /** Step-event discriminant (only for `step-begin`/`step-end` events). */
+    stepCategory?: string | null;
+    parentTitle?: string | null;
+}
+export interface BeginStreamEvent {
+    type: 'begin';
+    title: string;
+    location: string;
+    workerIndex: number | null;
+    shardIndex: number | null;
+    browser?: BrowserConfig | null;
+    suitePath?: string[] | null;
+    suiteConfig?: SuiteConfigEntry[] | null;
+}
+export interface CompleteStreamEvent {
+    type: 'complete';
+    title: string;
+    location: string;
+    status: string;
+    duration: number;
+    error: string | null;
+    retries: number;
+    workerIndex: number | null;
+    shardIndex: number | null;
+    startedAt: number | null;
+    browser?: BrowserConfig | null;
+    suitePath?: string[] | null;
+    suiteConfig?: SuiteConfigEntry[] | null;
+    testAnnotations?: TestAnnotation[] | null;
+    steps?: unknown;
+    stepEvents?: TestStepEvent[] | null;
+    slowestStep?: string | null;
+    slowestStepDuration?: number | null;
+    networkRequests?: unknown;
+    webVitals?: unknown;
+    consoleLogs?: unknown;
+    ariaSnapshot?: unknown;
+    testSource?: string | null;
+}
+export interface StepBeginStreamEvent {
+    type: 'step-begin';
+    title: string;
+    location: string;
+    stepCategory: 'hook' | 'fixture';
+    parentTitle: string | null;
+    workerIndex: number | null;
+    startedAt: number | null;
+}
+export interface StepEndStreamEvent {
+    type: 'step-end';
+    title: string;
+    location: string;
+    status: string;
+    duration: number;
+    stepCategory: 'hook' | 'fixture';
+    parentTitle: string | null;
+    workerIndex: number | null;
+    startedAt: number | null;
+}
+/** Discriminated union of events queued to `StreamManager` and persisted by `StreamBuffer`. */
+export type StreamEvent = BeginStreamEvent | CompleteStreamEvent | StepBeginStreamEvent | StepEndStreamEvent;
+export interface SetupStep {
+    title: string;
+    category: string;
+    startedAt: number;
+    duration: number;
+    status: string;
+    location?: string | null;
+    workerIndex?: number | null;
+}
+/** Hash + size of a single trace file, used for dedup against the server. */
+export interface TraceHashInfo {
+    tracePath: string;
+    hash: string;
+    size: number;
+}

package/dist/types.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Reporter-local domain model.
+ *
+ * These interfaces describe the data that flows *between* the reporter's
+ * classes (`FileHandler`, `Uploader`, `StreamManager`, `PiwiDashboardReporter`).
+ * They intentionally mirror — but do not import — the wire types in
+ * `application/shared/types.ts`. Importing that module would leak the monorepo
+ * path into the published `.d.ts` files; the constraint forbids the import,
+ * not the types. Keep these structurally compatible with
+ * `TestCasePayload` / `StreamEventPayload` / `TestRunFinishPayload` when
+ * evolving them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/uploader.d.ts

@@ -0,0 +1,86 @@
+import { HttpClient } from './http-client.js';
+import { FileHandler } from './file-handler.js';
+import { Logger } from './logger.js';
+import type { CollectedTestCase, FilterDetails } from './types.js';
+/** Payload for a batch test-run submission */
+export interface RunPayload {
+    /** Name of the project the run belongs to */
+    projectName: string;
+    /** Optional project description */
+    projectDescription?: string;
+    /** Overall run status: `"passed"` or `"failed"` */
+    status: string;
+    /** ISO-8601 timestamp when the run started */
+    startTime: string | null;
+    /** Total wall-clock duration of the run in ms */
+    duration: number;
+    totalTests: number;
+    passedTests: number;
+    failedTests: number;
+    skippedTests: number;
+    /** Tests that never executed (cut short by `maxFailures` or a serial-group failure) */
+    didNotRunTests?: number;
+    /** Deployment environment label (e.g. `"staging"`, `"production"`) */
+    environment?: string;
+    /** Optional display label for the test run (e.g. "v2.3.1 release") */
+    label?: string | null;
+    /** Arbitrary metadata collected from the environment, CI, and Playwright config */
+    metadata: Record<string, any>;
+    /** Unique instance identifier for deduplication */
+    instanceId: string;
+    /** Test case results in their collected form (with attachments). Projected to the wire shape by `serializeRun`/`toWireTestCase` at the JSON boundary. */
+    testCases: CollectedTestCase[];
+    /** Playwright framework version used for this run */
+    playwrightVersion?: string;
+    /** 1-based shard index (e.g. 1, 2, 3) */
+    shardIndex?: number;
+    /** Total number of shards (e.g. 3) */
+    shardTotal?: number;
+    /** Whether this run represents the full test suite (true) or a filtered subset (false) */
+    isFullRun?: boolean;
+    /** Filter details when isFullRun is false */
+    filterDetails?: FilterDetails | null;
+}
+/** Options controlling which report files and traces to upload */
+export interface ReportOptions {
+    /** Upload trace files. Defaults to `true`. */
+    uploadTraces?: boolean;
+    /** Upload the Playwright HTML report. Defaults to `true`. */
+    uploadReport?: boolean;
+    /** Additional report types to discover and upload */
+    reports?: Array<{
+        type: string;
+        dir?: string;
+        label?: string;
+    }>;
+}
+/**
+ * Handles all upload strategies: plain JSON, multipart (with reports and
+ * traces), per-test-case file uploads for streaming runs, and report-only
+ * uploads for already-submitted streaming runs.
+ */
+export declare class Uploader {
+    private httpClient;
+    private fileHandler;
+    private logger;
+    /**
+     * @param httpClient  HTTP client for server communication.
+     * @param fileHandler File discovery and compression helper.
+     * @param logger      Prefixed logger.
+     */
+    constructor(httpClient: HttpClient, fileHandler: FileHandler, logger: Logger);
+    /** Submit test results as a plain JSON payload (no file attachments) */
+    uploadJSON(payload: RunPayload, auth: string | null): Promise<any>;
+    /** Submit test results as a multipart form with trace files and compressed report directories */
+    uploadWithFiles(payload: RunPayload, reportOptions: ReportOptions, auth: string | null): Promise<any>;
+    /** Upload report files for an already-submitted streaming run */
+    uploadReportsForStreamingRun(projectName: string, runId: number, reportOptions: ReportOptions, startTime: string | null, auth: string | null): Promise<void>;
+    /**
+     * Upload one test case's trace and attachments for a streaming run.
+     * The matching `complete` event must have been flushed to the server first.
+     * Returns `false` when the case has no files to upload.
+     */
+    uploadCaseFiles(projectName: string, runId: number, streamToken: string, testCase: CollectedTestCase, uploadTraces: boolean | undefined, auth: string | null): Promise<boolean>;
+    private appendReportsToForm;
+    private appendFilesToForm;
+}