@piwitests/reporter 0.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Fabien Ménager
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+# Piwi Dashboard Reporter
+
+A custom Playwright reporter that sends test results to a [Piwi Dashboard](https://piwitests.github.io) server. It handles uploading test results, HTML reports, trace files, and performance metrics — with optional live streaming of results as tests execute.
+
+📖 **[Full documentation](https://piwitests.github.io/reporter)**
+
+## Installation
+
+```bash
+npm install --save-dev @piwitests/reporter
+```
+
+## Quick start
+
+Add the reporter to your `playwright.config.ts`:
+
+```typescript
+import { defineConfig } from '@playwright/test'
+
+export default defineConfig({
+  reporter: [
+    ['list'],
+    ['@piwitests/reporter', {
+      serverUrl: 'http://localhost:3000',
+      projectName: 'my-project',
+    }],
+  ],
+  use: {
+    trace: 'retain-on-failure',
+  },
+})
+```
+
+Run your tests — results are uploaded automatically:
+
+```bash
+npx playwright test
+```
+
+## Configuration Options
+
+| Option                      | Type     | Default                   | Description                                                            |
+|-----------------------------|----------|---------------------------|------------------------------------------------------------------------|
+| `serverUrl`                 | string   | `'http://localhost:3000'` | URL of the Piwi Dashboard server                                       |
+| `projectName`               | string   | `'default-project'`       | Name of the project to report results under                            |
+| `uploadTraces`              | boolean  | `true`                    | Whether to upload trace files to the dashboard                         |
+| `uploadReport`              | boolean  | `true`                    | Whether to upload the HTML report to the dashboard                     |
+| `reports`                   | array    | —                         | Additional report types to upload (html, monocart, blob, or custom)    |
+| `streaming`                 | boolean  | `true`                    | Enable live streaming of results as tests complete                     |
+| `streamingBatchSize`        | number   | `5`                       | Number of test results to batch before sending                         |
+| `streamingBatchDelay`       | number   | `2000`                    | Max delay (ms) before flushing pending events                          |
+| `projectDescription`        | string   | —                         | Description of the project                                             |
+| `environment`               | string   | —                         | Deployment environment for the run, e.g. `production`, `staging`       |
+| `relatedIssue`              | string   | —                         | Related issue reference (e.g., "PROJ-123")                             |
+| `ciInfo`                    | string   | —                         | CI job information                                                     |
+| `tags`                      | string[] | —                         | Tags to categorize the test run                                        |
+| `customData`                | object   | —                         | Additional custom metadata as key-value pairs                          |
+| `collectScmInfo`            | boolean  | `true`                    | Auto-collect git commit, branch, author                                |
+| `collectCiInfo`             | boolean  | `true`                    | Auto-collect CI environment info                                       |
+| `collectPerformanceMetrics` | boolean  | `true`                    | Collect step timings, network requests and web vitals from the fixture |
+| `apiKey`                    | string   | —                         | API key for authentication (preferred for CI)                          |
+| `username`                  | string   | —                         | Username for dashboard login (use `apiKey` instead when possible)      |
+| `password`                  | string   | —                         | Password for dashboard login (used with `username`)                    |
+| `verbose`                   | boolean  | `false`                   | Enable verbose logging for debugging                                   |
+
+## Live streaming
+
+By default, the reporter streams test results to the dashboard in real-time. This allows you to monitor progress live in the dashboard UI while CI is still running.
+
+To disable streaming and send all results at the end:
+
+```typescript
+['@piwitests/reporter', {
+  serverUrl: 'http://localhost:3000',
+  projectName: 'my-project',
+  streaming: false,
+}]
+```
+
+If the server doesn't support streaming (older versions), the reporter automatically falls back to batch mode.
+
+## Multiple reports
+
+Attach multiple report types to a single test run:
+
+```typescript
+export default defineConfig({
+  reporter: [
+    ['list'],
+    ['@playwright/test/reporter-html', { outputFolder: 'playwright-report' }],
+    ['monocart-reporter', { name: 'My Tests', outputFile: 'monocart-report/index.html' }],
+    ['@piwitests/reporter', {
+      serverUrl: 'http://localhost:3000',
+      projectName: 'my-project',
+      reports: [
+        { type: 'html' },
+        { type: 'monocart' },
+        { type: 'blob', dir: 'blob-report', label: 'Blob archive' },
+      ],
+    }],
+  ],
+})
+```
+
+## Performance Metrics & Web Vitals
+
+To capture network request timing and browser Web Vitals, use the provided fixtures:
+
+```typescript
+// tests/fixtures.ts
+import { test as base, expect } from '@playwright/test'
+import { dashboardFixtures } from '@piwitests/reporter/fixtures'
+
+export const test = base.extend(dashboardFixtures)
+export { expect }
+```
+
+Or as a drop-in replacement:
+
+```typescript
+import { test, expect } from '@piwitests/reporter/fixtures'
+```
+
+### What gets captured
+
+- **Network requests** — method, URL, status, duration, resource type. Aggregated on the dashboard into a *Slow API Endpoints* table grouped by `METHOD + normalized route`.
+- **Browser Web Vitals** — TTFB, DOM Interactive, DOMContentLoaded, Load Complete, First Paint, First Contentful Paint — displayed with color-coded thresholds.
+
+Both are only collected when `collectPerformanceMetrics` is `true` (the default).
+
+## Authentication
+
+When the dashboard has authentication enabled, use an API key (recommended for CI):
+
+```typescript
+['@piwitests/reporter', {
+  serverUrl: 'https://your-dashboard.example.com',
+  projectName: 'my-project',
+  apiKey: process.env.PIWI_API_KEY,
+}]
+```
+
+Generate a key in the dashboard UI: **Settings → Users → API keys**. Store it as a CI secret.
+
+Alternatively, use `username`/`password` — the reporter will call `/api/auth/login` automatically.
+
+## Automatic Metadata Collection
+
+### SCM Information (Git)
+
+When `collectScmInfo` is enabled (default), the reporter collects:
+- Commit hash and message
+- Branch name
+- Author name
+- Remote URL
+
+### CI Information
+
+When `collectCiInfo` is enabled (default), the reporter auto-detects:
+- **GitHub Actions** — run ID, workflow, actor, repository, ref, SHA
+- **Jenkins** — build number, build URL, job name
+- **GitLab CI** — pipeline ID/URL, job ID/URL, job name
+- **CircleCI** — build number/URL, job name, workflow
+- **Travis CI** — build number/URL, job number
+- **Azure Pipelines** — build number, build ID/URL, job name
+
+## How It Works
+
+1. When tests start, the reporter creates a run on the server (streaming mode) or collects results locally (batch mode)
+2. As tests complete, results are streamed in batches to the server
+3. After all tests finish, HTML reports are compressed and uploaded
+4. Trace files from test attachments are uploaded
+5. Network request and web vitals data (from fixtures) are included per test case
+6. The server stores everything and makes it available in the dashboard UI
+
+## Requirements
+
+- Node.js 18 or higher
+- Playwright Test 1.40 or higher
+- Running Piwi Dashboard server
+
+## Development
+
+This package is written in TypeScript. Source files live in `src/` and compile to `dist/`.
+
+```bash
+cd reporter
+npm install
+npm run reporter:build   # compile TypeScript src/ → dist/
+npm run reporter:dev     # watch mode — auto-recompile on changes
+```
+
+### Source layout
+
+| File                       | Responsibility                              |
+|----------------------------|---------------------------------------------|
+| `src/reporter.ts`          | Orchestrator — Playwright hooks + fallback  |
+| `src/config.ts`            | Options interface + defaults                |
+| `src/http-client.ts`       | HTTP transport layer                        |
+| `src/uploader.ts`          | Upload strategies (JSON, multipart)         |
+| `src/stream-buffer.ts`     | Persistent JSONL buffer                     |
+| `src/crash-recovery.ts`    | Recovery data management                    |
+| `src/file-handler.ts`      | Report/trace/attachment file operations     |
+| `src/metadata-collector.ts`| CI, SCM, Playwright config metadata         |
+| `src/step-analyzer.ts`     | Step categorization + performance analysis  |
+| `src/helpers.ts`           | Pure utility functions                      |
+| `src/compression.ts`       | Directory gzip archiver                     |
+| `src/fixtures.ts`          | Playwright fixtures                         |
+| `src/index.ts`             | Package entry point                         |
+
+The `package.json` `exports` field maps the main entry and `./fixtures` to their `dist/` counterparts.
+
+## Troubleshooting
+
+### Reporter not uploading files
+
+- Ensure an HTML reporter is configured: `['html', { outputFolder: 'playwright-report' }]`
+- Ensure traces are enabled: `use: { trace: 'retain-on-failure' }`
+- Check the dashboard server is running and accessible at `serverUrl`
+
+### Network/Web Vitals not appearing
+
+- Import `test` from `@piwitests/reporter/fixtures` (or extend with `dashboardFixtures`)
+- Verify `collectPerformanceMetrics` is not set to `false`
+- Ensure tests navigate to at least one page (`await page.goto(...)`)
+
+### Connection errors
+
+- Check that `serverUrl` is correct and the server is running
+- Verify network connectivity and firewall settings
+
+## License
+
+MIT

package/dist/compression.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Recursively read a directory and pack all files into a gzip-compressed
+ * archive (a concatenation of length-prefixed path+content pairs).
+ */
+export declare function compressDirectory(sourceDir: string): Promise<Buffer>;

package/dist/compression.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compressDirectory = compressDirectory;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const zlib_1 = __importDefault(require("zlib"));
+const util_1 = require("util");
+const gzipAsync = (0, util_1.promisify)(zlib_1.default.gzip);
+/**
+ * Recursively read a directory and pack all files into a gzip-compressed
+ * archive (a concatenation of length-prefixed path+content pairs).
+ */
+async function compressDirectory(sourceDir) {
+    const files = [];
+    function collect(dir, baseDir = '') {
+        for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+            const full = path_1.default.join(dir, entry.name);
+            const rel = path_1.default.join(baseDir, entry.name);
+            if (entry.isDirectory())
+                collect(full, rel);
+            else if (entry.isFile())
+                files.push({ path: rel, content: fs_1.default.readFileSync(full) });
+        }
+    }
+    collect(sourceDir);
+    const parts = [];
+    for (const f of files) {
+        const pb = Buffer.from(f.path, 'utf8');
+        const plb = Buffer.allocUnsafe(4);
+        plb.writeUInt32LE(pb.length, 0);
+        const clb = Buffer.allocUnsafe(4);
+        clb.writeUInt32LE(f.content.length, 0);
+        parts.push(plb, pb, clb, f.content);
+    }
+    return await gzipAsync(Buffer.concat(parts), { level: 5 });
+}

package/dist/config-wrapper.d.ts

@@ -0,0 +1,21 @@
+import type { PlaywrightTestConfig } from '@playwright/test';
+import { type PiwiDashboardOptions } from './config.js';
+/**
+ * Wrap a Playwright config to auto-inject the Piwi Dashboard reporter and
+ * chain its global setup module. Returns a new config object (shallow merge)
+ * without mutating the original.
+ *
+ * The `globalSetup` field is set to a `string` (or `string[]` if the user
+ * already has a global setup) referencing the Piwi global setup module,
+ * which registers the run on the server. The original setup path(s) are
+ * preserved and executed first.
+ *
+ * Playwright options required in `globalSetup` are forwarded via `PIWI_*`
+ * environment variables (see `applyOptionsToEnv` in `config.ts` for the
+ * supported set — `serverUrl`, `projectName`, `verbose`, `apiKey`,
+ * `username`, `password`, `environment`, `label`, `runLabel`).
+ *
+ * @param config      The user's Playwright config.
+ * @param piwiOptions Optional Piwi Dashboard options (serverUrl, projectName, …).
+ */
+export declare function wrapConfig<T extends PlaywrightTestConfig>(config: T, piwiOptions?: PiwiDashboardOptions): T;

package/dist/config-wrapper.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapConfig = wrapConfig;
+const config_js_1 = require("./config.js");
+const PIWI_MODULE = '@piwitests/reporter';
+function isPiwiReporterEntry(entry) {
+    if (typeof entry === 'string')
+        return entry.toLowerCase().includes('piwi');
+    if (Array.isArray(entry) && typeof entry[0] === 'string')
+        return entry[0].toLowerCase().includes('piwi');
+    return false;
+}
+function injectReporter(reporter, piwiOptions) {
+    const piwiEntry = piwiOptions ? [PIWI_MODULE, piwiOptions] : [PIWI_MODULE];
+    if (!reporter)
+        return [piwiEntry];
+    if (Array.isArray(reporter)) {
+        if (reporter.some(isPiwiReporterEntry))
+            return reporter;
+        return [...reporter, piwiEntry];
+    }
+    return [[reporter], piwiEntry];
+}
+function resolveSetupModule() {
+    try {
+        return require.resolve('./global-setup-module.js');
+    }
+    catch {
+        return require.resolve('./global-setup-module.ts');
+    }
+}
+/**
+ * Wrap a Playwright config to auto-inject the Piwi Dashboard reporter and
+ * chain its global setup module. Returns a new config object (shallow merge)
+ * without mutating the original.
+ *
+ * The `globalSetup` field is set to a `string` (or `string[]` if the user
+ * already has a global setup) referencing the Piwi global setup module,
+ * which registers the run on the server. The original setup path(s) are
+ * preserved and executed first.
+ *
+ * Playwright options required in `globalSetup` are forwarded via `PIWI_*`
+ * environment variables (see `applyOptionsToEnv` in `config.ts` for the
+ * supported set — `serverUrl`, `projectName`, `verbose`, `apiKey`,
+ * `username`, `password`, `environment`, `label`, `runLabel`).
+ *
+ * @param config      The user's Playwright config.
+ * @param piwiOptions Optional Piwi Dashboard options (serverUrl, projectName, …).
+ */
+function wrapConfig(config, piwiOptions) {
+    if (piwiOptions)
+        (0, config_js_1.applyOptionsToEnv)(piwiOptions);
+    const globalSetupModules = [];
+    if (config.globalSetup) {
+        const orig = Array.isArray(config.globalSetup) ? config.globalSetup : [config.globalSetup];
+        globalSetupModules.push(...orig);
+    }
+    globalSetupModules.push(resolveSetupModule());
+    return {
+        ...config,
+        reporter: injectReporter(config.reporter, piwiOptions),
+        globalSetup: globalSetupModules.length === 1 ? globalSetupModules[0] : globalSetupModules,
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,104 @@
+import type { PlaywrightTestConfig } from '@playwright/test';
+/** Playwright shard info — mirrors `config.shard` shape */
+export interface ShardInfo {
+    current: number;
+    total: number;
+}
+/** Options for configuring the Piwi Dashboard reporter */
+export interface PiwiDashboardOptions extends PlaywrightTestConfig {
+    /** URL of the Piwi Dashboard server */
+    serverUrl?: string;
+    /** Name of the project to report results under. Defaults to `'default-project'`. */
+    projectName?: string;
+    /** Optional description of the project */
+    projectDescription?: string;
+    /** Upload trace files to the dashboard. Defaults to `true`. */
+    uploadTraces?: boolean;
+    /** Upload the Playwright HTML report. Defaults to `true`. */
+    uploadReport?: boolean;
+    /** Upload each test's trace and attachments as soon as the test finishes (streaming mode only). Defaults to `true`. */
+    liveFileUploads?: boolean;
+    /** Auto-collect git commit, branch, author. Defaults to `true`. */
+    collectScmInfo?: boolean;
+    /** Auto-collect CI environment info. Defaults to `true`. */
+    collectCiInfo?: boolean;
+    /** Collect step timings, network requests and web vitals. Defaults to `true`. */
+    collectPerformanceMetrics?: boolean;
+    /** Enable live streaming of results (falls back to batch if unsupported). Defaults to `true`. */
+    streaming?: boolean;
+    /** Number of test results to batch before sending during streaming. Defaults to `5`. */
+    streamingBatchSize?: number;
+    /** Max delay (ms) before flushing pending events during streaming. Defaults to `2000`. */
+    streamingBatchDelay?: number;
+    /** Username for dashboard login (use `apiKey` instead when possible) */
+    username?: string | null;
+    /** Password for dashboard login (used with `username`) */
+    password?: string | null;
+    /** API key for authentication (preferred over `username`/`password` for CI) */
+    apiKey?: string | null;
+    /** Additional report types to upload. Each entry can specify `type`, optional `dir`, and optional `label`. */
+    reports?: Array<{
+        type: string;
+        dir?: string;
+        label?: string;
+    }>;
+    /** Stable label that ties shards together (e.g. CI run ID). Auto-detected from CI env; override if needed. */
+    runLabel?: string;
+    /** Deployment environment for this run, e.g. `"production"`, `"staging"`, `"integration"` */
+    environment?: string;
+    /** Optional display label for the test run (e.g. "v2.3.1 release") */
+    label?: string;
+    /** Related issue reference, e.g. `"JIRA-123"` */
+    relatedIssue?: string;
+    /** CI job information */
+    ciInfo?: string;
+    /** Tags to categorize the test run */
+    tags?: string[];
+    /** Additional custom metadata as key-value pairs */
+    customData?: Record<string, unknown>;
+    /** Enable verbose logging for debugging. Defaults to `false`. */
+    verbose?: boolean;
+}
+/**
+ * Single source of truth for the `PIWI_*` env-var → option mapping. Both
+ * `resolveOptions` (env → option) and `applyOptionsToEnv` (option → env, used
+ * by `wrapConfig` to bridge into the global-setup process) read these names so
+ * the mapping lives in exactly one place.
+ */
+export declare const PIWI_ENV_KEYS: {
+    readonly serverUrl: "PIWI_DASHBOARD_URL";
+    readonly projectName: "PIWI_PROJECT_NAME";
+    readonly verbose: "PIWI_VERBOSE";
+    readonly apiKey: "PIWI_API_KEY";
+    readonly username: "PIWI_USERNAME";
+    readonly password: "PIWI_PASSWORD";
+    readonly environment: "PIWI_ENVIRONMENT";
+    readonly label: "PIWI_LABEL";
+    readonly runLabel: "PIWI_RUN_LABEL";
+    readonly streaming: "PIWI_STREAMING";
+    readonly streamingBatchSize: "PIWI_STREAMING_BATCH_SIZE";
+    readonly streamingBatchDelay: "PIWI_STREAMING_BATCH_DELAY";
+    readonly liveFileUploads: "PIWI_LIVE_FILE_UPLOADS";
+    readonly uploadTraces: "PIWI_UPLOAD_TRACES";
+    readonly uploadReport: "PIWI_UPLOAD_REPORT";
+};
+/**
+ * Merge raw user options with defaults, reading from `PIWI_*` env vars when
+ * options are not provided.
+ *
+ * Env semantics: env vars fill in values the caller didn't provide (fallback).
+ * They're applied to `raw` *before* the `DEFAULTS` merge so a built-in default
+ * never masks an env var (the pre-Phase-4 `PIWI_PROJECT_NAME` was masked by the
+ * `default-project` default — that quirk is now fixed).
+ *
+ * One preserved quirk: `PIWI_VERBOSE` wins over both the default *and* an
+ * explicit user option, matching the pre-Phase-4 behavior.
+ */
+export declare function resolveOptions(raw: Record<string, any>): PiwiDashboardOptions;
+/**
+ * Write the options that the isolated `global-setup-module` process needs into
+ * `PIWI_*` env vars. `wrapConfig` calls this so the global setup (which runs
+ * `resolveOptions({})` in a separate module) picks up the same server/auth
+ * config the reporter instance uses. Only writes values that are actually set.
+ */
+export declare function applyOptionsToEnv(options: PiwiDashboardOptions): void;

package/dist/config.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PIWI_ENV_KEYS = void 0;
+exports.resolveOptions = resolveOptions;
+exports.applyOptionsToEnv = applyOptionsToEnv;
+const DEFAULTS = {
+    projectName: 'default-project',
+    uploadTraces: true,
+    uploadReport: true,
+    liveFileUploads: true,
+    collectScmInfo: true,
+    collectCiInfo: true,
+    collectPerformanceMetrics: true,
+    streaming: true,
+    streamingBatchSize: 5,
+    streamingBatchDelay: 2000,
+    username: null,
+    password: null,
+    apiKey: null,
+    verbose: false,
+};
+/**
+ * Single source of truth for the `PIWI_*` env-var → option mapping. Both
+ * `resolveOptions` (env → option) and `applyOptionsToEnv` (option → env, used
+ * by `wrapConfig` to bridge into the global-setup process) read these names so
+ * the mapping lives in exactly one place.
+ */
+exports.PIWI_ENV_KEYS = {
+    serverUrl: 'PIWI_DASHBOARD_URL',
+    projectName: 'PIWI_PROJECT_NAME',
+    verbose: 'PIWI_VERBOSE',
+    apiKey: 'PIWI_API_KEY',
+    username: 'PIWI_USERNAME',
+    password: 'PIWI_PASSWORD',
+    environment: 'PIWI_ENVIRONMENT',
+    label: 'PIWI_LABEL',
+    runLabel: 'PIWI_RUN_LABEL',
+    streaming: 'PIWI_STREAMING',
+    streamingBatchSize: 'PIWI_STREAMING_BATCH_SIZE',
+    streamingBatchDelay: 'PIWI_STREAMING_BATCH_DELAY',
+    liveFileUploads: 'PIWI_LIVE_FILE_UPLOADS',
+    uploadTraces: 'PIWI_UPLOAD_TRACES',
+    uploadReport: 'PIWI_UPLOAD_REPORT',
+};
+function readBool(val) {
+    if (val === undefined)
+        return undefined;
+    return val === 'true';
+}
+/**
+ * Merge raw user options with defaults, reading from `PIWI_*` env vars when
+ * options are not provided.
+ *
+ * Env semantics: env vars fill in values the caller didn't provide (fallback).
+ * They're applied to `raw` *before* the `DEFAULTS` merge so a built-in default
+ * never masks an env var (the pre-Phase-4 `PIWI_PROJECT_NAME` was masked by the
+ * `default-project` default — that quirk is now fixed).
+ *
+ * One preserved quirk: `PIWI_VERBOSE` wins over both the default *and* an
+ * explicit user option, matching the pre-Phase-4 behavior.
+ */
+function resolveOptions(raw) {
+    const env = process.env;
+    const mergedRaw = { ...raw };
+    // String options: env fills in when the caller didn't provide one.
+    if (mergedRaw.serverUrl === undefined && env[exports.PIWI_ENV_KEYS.serverUrl])
+        mergedRaw.serverUrl = env[exports.PIWI_ENV_KEYS.serverUrl];
+    if (mergedRaw.projectName === undefined && env[exports.PIWI_ENV_KEYS.projectName])
+        mergedRaw.projectName = env[exports.PIWI_ENV_KEYS.projectName];
+    if (mergedRaw.apiKey === undefined && env[exports.PIWI_ENV_KEYS.apiKey])
+        mergedRaw.apiKey = env[exports.PIWI_ENV_KEYS.apiKey];
+    if (mergedRaw.username === undefined && env[exports.PIWI_ENV_KEYS.username])
+        mergedRaw.username = env[exports.PIWI_ENV_KEYS.username];
+    if (mergedRaw.password === undefined && env[exports.PIWI_ENV_KEYS.password])
+        mergedRaw.password = env[exports.PIWI_ENV_KEYS.password];
+    if (mergedRaw.environment === undefined && env[exports.PIWI_ENV_KEYS.environment])
+        mergedRaw.environment = env[exports.PIWI_ENV_KEYS.environment];
+    if (mergedRaw.label === undefined && env[exports.PIWI_ENV_KEYS.label])
+        mergedRaw.label = env[exports.PIWI_ENV_KEYS.label];
+    if (mergedRaw.runLabel === undefined && env[exports.PIWI_ENV_KEYS.runLabel])
+        mergedRaw.runLabel = env[exports.PIWI_ENV_KEYS.runLabel];
+    // Boolean / numeric options: env fills in when the caller didn't provide one.
+    if (mergedRaw.streaming === undefined && env[exports.PIWI_ENV_KEYS.streaming] !== undefined)
+        mergedRaw.streaming = readBool(env[exports.PIWI_ENV_KEYS.streaming]);
+    if (mergedRaw.streamingBatchSize === undefined && env[exports.PIWI_ENV_KEYS.streamingBatchSize])
+        mergedRaw.streamingBatchSize = Number(env[exports.PIWI_ENV_KEYS.streamingBatchSize]);
+    if (mergedRaw.streamingBatchDelay === undefined && env[exports.PIWI_ENV_KEYS.streamingBatchDelay])
+        mergedRaw.streamingBatchDelay = Number(env[exports.PIWI_ENV_KEYS.streamingBatchDelay]);
+    if (mergedRaw.liveFileUploads === undefined && env[exports.PIWI_ENV_KEYS.liveFileUploads] !== undefined)
+        mergedRaw.liveFileUploads = readBool(env[exports.PIWI_ENV_KEYS.liveFileUploads]);
+    if (mergedRaw.uploadTraces === undefined && env[exports.PIWI_ENV_KEYS.uploadTraces] !== undefined)
+        mergedRaw.uploadTraces = readBool(env[exports.PIWI_ENV_KEYS.uploadTraces]);
+    if (mergedRaw.uploadReport === undefined && env[exports.PIWI_ENV_KEYS.uploadReport] !== undefined)
+        mergedRaw.uploadReport = readBool(env[exports.PIWI_ENV_KEYS.uploadReport]);
+    const opts = { ...DEFAULTS, ...mergedRaw };
+    // Preserved quirk: PIWI_VERBOSE wins over both default and user option.
+    if (env[exports.PIWI_ENV_KEYS.verbose] !== undefined)
+        opts.verbose = env[exports.PIWI_ENV_KEYS.verbose] === 'true';
+    return opts;
+}
+/**
+ * Write the options that the isolated `global-setup-module` process needs into
+ * `PIWI_*` env vars. `wrapConfig` calls this so the global setup (which runs
+ * `resolveOptions({})` in a separate module) picks up the same server/auth
+ * config the reporter instance uses. Only writes values that are actually set.
+ */
+function applyOptionsToEnv(options) {
+    const env = process.env;
+    if (options.serverUrl !== undefined)
+        env[exports.PIWI_ENV_KEYS.serverUrl] = options.serverUrl;
+    if (options.projectName !== undefined)
+        env[exports.PIWI_ENV_KEYS.projectName] = options.projectName;
+    if (options.verbose !== undefined)
+        env[exports.PIWI_ENV_KEYS.verbose] = String(options.verbose);
+    if (options.apiKey)
+        env[exports.PIWI_ENV_KEYS.apiKey] = options.apiKey;
+    if (options.username)
+        env[exports.PIWI_ENV_KEYS.username] = options.username;
+    if (options.password)
+        env[exports.PIWI_ENV_KEYS.password] = options.password;
+    if (options.environment)
+        env[exports.PIWI_ENV_KEYS.environment] = options.environment;
+    if (options.label)
+        env[exports.PIWI_ENV_KEYS.label] = options.label;
+    if (options.runLabel)
+        env[exports.PIWI_ENV_KEYS.runLabel] = options.runLabel;
+}

package/dist/crash-recovery.d.ts

@@ -0,0 +1,23 @@
+import { HttpClient } from './http-client.js';
+import { Logger } from './logger.js';
+/**
+ * Persists a test-run payload to disk when all upload strategies fail, so the
+ * data can be retried on the next run.
+ */
+export declare class CrashRecovery {
+    private filePath;
+    private readonly logger;
+    /**
+     * @param projectName Used to derive the temp-file name so recovery data is project-scoped.
+     * @param logger      Prefixed logger.
+     */
+    constructor(projectName: string, logger?: Logger);
+    /** Serialise the payload to a temp file for later retry */
+    save(data: Record<string, any>): void;
+    /** Read the saved payload from disk, or return `null` if none exists */
+    load(): Record<string, any> | null;
+    /** Delete the recovery file from disk */
+    clear(): void;
+    /** Attempt to submit a previously saved payload. Clears the recovery file on success. */
+    tryUpload(httpClient: HttpClient, auth?: string | null): Promise<void>;
+}