@piwitests/reporter 0.5.0 → 0.7.0

package/dist/{locator-healing.js → internal/capture/locator-healing.js}

@@ -34,15 +34,42 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CAPTURED_ATTRIBUTES = exports.LOCATOR_CREATING_CHAINS = exports.ACTION_METHODS = exports.CHAIN_METHODS = exports.LOCATOR_METHODS = void 0;
+exports.dedupeSnapshotsByLocation = dedupeSnapshotsByLocation;
 exports.resolveAriaRole = resolveAriaRole;
 exports.generateAlternatives = generateAlternatives;
 exports.classifyCssStability = classifyCssStability;
 exports.isAutoGenerated = isAutoGenerated;
 exports.extractAccessibleName = extractAccessibleName;
 exports.approximateAccessibleName = approximateAccessibleName;
+exports.parseAriaRoleName = parseAriaRoleName;
+exports.nameSimilarity = nameSimilarity;
 exports.suggestLocatorsFromAria = suggestLocatorsFromAria;
 exports.captureCallerLocation = captureCallerLocation;
-const path = __importStar(require("path"));
+const path = __importStar(require("node:path"));
+/**
+ * Drop repeated captures of the same call site before attaching: a loop (or a
+ * page-object method called repeatedly) produces one snapshot per action, but
+ * the server keeps only the latest per location anyway. Keeps the last
+ * element-bearing snapshot per location — falling back to the last placeholder
+ * when no capture resolved, so the location still counts as "seen this run"
+ * for the server's stale-location purge. Entries with no location pass through.
+ */
+function dedupeSnapshotsByLocation(snaps) {
+    const lastWithElement = new Map();
+    const lastAny = new Map();
+    snaps.forEach((s, i) => {
+        if (!s.location)
+            return;
+        lastAny.set(s.location, i);
+        if (s.element)
+            lastWithElement.set(s.location, i);
+    });
+    return snaps.filter((s, i) => {
+        if (!s.location)
+            return true;
+        return (lastWithElement.get(s.location) ?? lastAny.get(s.location)) === i;
+    });
+}
 // ── Playwright method surface (shared with the fixture proxy) ────────────────
 /**
  * Page-level locator-building methods wrapped by the capture proxy. Imported by
@@ -92,12 +119,18 @@ exports.ACTION_METHODS = [
     'hover',
     'press',
     'type',
+    'pressSequentially',
     'clear',
     'setInputFiles',
     'dragTo',
     'focus',
     'blur',
     'scrollIntoViewIfNeeded',
+    'dispatchEvent',
+    'selectText',
+    // Not an action, but a successful waitFor proves the element resolved — the
+    // closest capture hook available for assertion-style usage of a locator.
+    'waitFor',
 ];
 /** Chain methods that create a new locator scope (origin tracks the chain call). */
 exports.LOCATOR_CREATING_CHAINS = new Set(exports.LOCATOR_METHODS);
@@ -118,7 +151,11 @@ exports.CAPTURED_ATTRIBUTES = [
     'role',
     'type',
     'href',
-    'value',
+    // `multiple` distinguishes listbox vs combobox for <select>. `value` is
+    // deliberately NOT captured: no alternative generator uses it, and reading
+    // the live value after fill() would leak user-typed secrets (passwords,
+    // tokens) into the snapshot payload and server storage.
+    'multiple',
 ];
 // ── ARIA role resolution ─────────────────────────────────────────────────────
 /** Implicit ARIA role for an HTML tag (when no explicit `role` is set). */
@@ -142,7 +179,6 @@ const TAG_TO_ROLE = {
     output: 'status',
     progress: 'progressbar',
     meter: 'meter',
-    select: 'listbox',
     textarea: 'textbox',
     h1: 'heading',
     h2: 'heading',
@@ -189,6 +225,11 @@ function resolveAriaRole(attrs) {
         const type = (attrs.attributes['type'] ?? 'text').toLowerCase();
         return INPUT_TYPE_TO_ROLE[type] ?? 'textbox';
     }
+    // A plain <select> is a combobox; only with `multiple` (or size > 1, not
+    // captured) does it become a listbox. Matches the server's implicitRoleForTag.
+    if (tag === 'select') {
+        return attrs.attributes['multiple'] != null ? 'listbox' : 'combobox';
+    }
     if (tag === 'a') {
         return attrs.attributes['href'] != null ? 'link' : null;
     }
@@ -197,6 +238,10 @@ function resolveAriaRole(attrs) {
 // ── Alternative generation ───────────────────────────────────────────────────
 const attr = (a, key) => a.attributes[key] || null;
 const esc = (s) => s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+/** Escape a value for use inside a double-quoted CSS attribute selector. */
+const escCssAttrValue = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+/** An id usable as a bare `#id` CSS selector without escaping (framework ids like `:r3:` are not). */
+const isCssSafeId = (id) => /^[A-Za-z][A-Za-z0-9_-]*$/.test(id);
 /**
  * Build a ranked list of alternative locators from the captured element
  * attributes. The list is sorted descending by stability score.
@@ -216,9 +261,17 @@ function generateAlternatives(attrs) {
     const { accessibleName } = attrs;
     const tag = attrs.tagName;
     const role = resolveAriaRole(attrs);
+    // A probed count > 1 means the selector matches several elements on the
+    // captured page — a strict-mode violation, so the alternative is suppressed.
+    // Unknown counts (probe absent/failed) keep the alternative.
+    const counts = attrs.selectorCounts;
+    const isUnique = (n) => n == null || n <= 1;
+    // Collapse whitespace: multi-line/indented textContent would otherwise
+    // produce a getByText with literal newlines — invalid when pasted as code.
+    const text = attrs.textContent ? attrs.textContent.replace(/\s+/g, ' ').trim() : null;
     // 1. data-testid — highest stability (100)
     const testId = attr(attrs, 'data-testid');
-    if (testId) {
+    if (testId && isUnique(counts?.testId)) {
         add({
             locator: `getByTestId('${esc(testId)}')`,
             method: 'getByTestId',
@@ -245,14 +298,22 @@ function generateAlternatives(attrs) {
             score: 85,
         });
     }
-    // 4. getByLabel — for form fields with associated <label> (85)
+    // 4. getByLabel — for form fields (85). getByLabel only matches a real
+    // <label> association or aria-label — but the accessible name may have been
+    // computed (or approximated) from placeholder/title, where getByLabel would
+    // match nothing. Only emit when a label/aria-label actually backs the name;
+    // legacy payloads without the hasLabel probe keep the old permissive behavior.
     if (accessibleName && ['input', 'select', 'textarea'].includes(tag)) {
-        add({
-            locator: `getByLabel('${esc(accessibleName)}')`,
-            method: 'getByLabel',
-            args: { label: accessibleName },
-            score: 85,
-        });
+        const label = attr(attrs, 'aria-label');
+        const labelBacked = attrs.hasLabel === undefined ? true : attrs.hasLabel === true || label === accessibleName;
+        if (labelBacked) {
+            add({
+                locator: `getByLabel('${esc(accessibleName)}')`,
+                method: 'getByLabel',
+                args: { label: accessibleName },
+                score: 85,
+            });
+        }
     }
     // 5. getByPlaceholder — for inputs (80)
     const placeholder = attr(attrs, 'placeholder');
@@ -265,31 +326,35 @@ function generateAlternatives(attrs) {
         });
     }
     // 6. getByText — from visible text content (70-80)
-    if (attrs.textContent && attrs.textContent.length < 80) {
+    if (text && text.length < 80) {
         add({
-            locator: `getByText('${esc(attrs.textContent)}')`,
+            locator: `getByText('${esc(text)}')`,
             method: 'getByText',
-            args: { text: attrs.textContent },
+            args: { text },
             score: 75,
         });
     }
-    // 7. locator('#id') — if id exists and doesn't look auto-generated (50-70)
+    // 7. locator('#id') — if id exists and doesn't look auto-generated (50-70).
+    // Framework ids that aren't valid bare CSS identifiers (React useId's
+    // `:r3:`, ids with dots) fall back to an attribute selector.
     const id = attr(attrs, 'id');
-    if (id && !isAutoGenerated(id)) {
+    if (id && !isAutoGenerated(id) && isUnique(counts?.id)) {
+        const selector = isCssSafeId(id) ? `#${id}` : `[id="${escCssAttrValue(id)}"]`;
         add({
-            locator: `locator('#${esc(id)}')`,
+            locator: `locator('${esc(selector)}')`,
             method: 'locator',
-            args: { selector: `#${id}` },
+            args: { selector },
             score: 65,
         });
     }
     // 8. locator('[name="..."]') — for form elements (60)
     const name = attr(attrs, 'name');
-    if (name) {
+    if (name && isUnique(counts?.name)) {
+        const selector = `[name="${escCssAttrValue(name)}"]`;
         add({
-            locator: `locator('[name="${esc(name)}"]')`,
+            locator: `locator('${esc(selector)}')`,
             method: 'locator',
-            args: { selector: `[name="${name}"]` },
+            args: { selector },
             score: 60,
         });
     }
@@ -313,12 +378,15 @@ function generateAlternatives(attrs) {
             score: 50,
         });
     }
-    // 11. CSS class-based locators — capped at 3 most stable classes
+    // 11. CSS class-based locators — capped at 3 most stable classes; classes
+    // the uniqueness probe saw on more than one element are dropped outright.
     const clsStr = attr(attrs, 'class');
     if (clsStr) {
         const classes = clsStr
             .split(/\s+/)
-            .filter((c) => c.length > 1)
+            // Only classes valid as a bare `.cls` selector — Tailwind variants
+            // (`hover:bg-red-500`) and arbitrary values (`w-[10px]`) are not.
+            .filter((c) => c.length > 1 && /^[A-Za-z_-][A-Za-z0-9_-]*$/.test(c) && isUnique(counts?.classes?.[c]))
             .map((cls) => ({
             cls,
             score: classifyCssStability(cls),
@@ -393,7 +461,13 @@ function isAutoGenerated(value) {
     if (/^(emotion-|styled-|css-|sc-)/.test(value))
         return true;
     // Angular-style generated IDs (ng-xxx-N)
-    if (/^ng-/.test(value))
+    if (value.startsWith('ng-'))
+        return true;
+    // Component-library generated ids (Radix, Headless UI, MUI, Mantine, Chakra)
+    if (/^(radix-|headlessui-|mui-|mantine-|chakra-)/i.test(value))
+        return true;
+    // React useId format — `:r1:` (18) / `«r1»` (19)
+    if (/^:r[0-9a-z]+:$/i.test(value) || /^«r[0-9a-z]+»$/i.test(value))
         return true;
     return false;
 }
@@ -447,23 +521,33 @@ const NAME_BASED_METHODS = new Set([
     'getByTitle',
     'getByAltText',
 ]);
-const escAttr = (s) => s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
-/** Parse `ariaSnapshot()` lines into role/name pairs (mirrors the server-side matcher). */
+const escAttr = (s) => s.replaceAll('\\', '\\\\').replaceAll("'", "\\'");
+/**
+ * Parse `ariaSnapshot()` lines into role/name pairs (mirrors the server-side
+ * `parseAriaCandidates` in application/shared/locator-fingerprint.ts).
+ * Exported so the dashboard's drift-guard unit test can compare the two.
+ */
 function parseAriaRoleName(ariaSnapshot) {
     const out = [];
     for (const line of ariaSnapshot.split('\n')) {
-        const m = line.match(/^\s*-\s+([a-z]+)(?:\s+"((?:[^"\\]|\\.)*)")?/i);
+        const m = /^\s*-\s+([a-z]+)(?:\s+"((?:[^"\\]|\\.)*)")?/i.exec(line);
         if (!m)
             continue;
         const role = m[1];
-        const name = m[2] != null ? m[2].replace(/\\(.)/g, '$1') : null;
+        const name = m[2] == null ? null : m[2].replace(/\\(.)/g, '$1');
         if (!name && (role === 'generic' || role === 'group' || role === 'list' || role === 'paragraph'))
             continue;
         out.push({ role, name });
     }
     return out;
 }
-/** Token-set (Dice) similarity, 0-1, case- and punctuation-insensitive. */
+/**
+ * Token-set (Dice) similarity, 0-1, case- and punctuation-insensitive.
+ * Duplicated from `textSimilarity` in application/shared/locator-fingerprint.ts —
+ * this package publishes standalone to npm and can't import monorepo-relative
+ * shared/ code, so keep the two implementations in sync by hand. Exported so
+ * the dashboard's drift-guard unit test can compare the two.
+ */
 function nameSimilarity(a, b) {
     const tok = (s) => new Set((s ?? '')
         .toLowerCase()

package/dist/internal/collect/error-text.d.ts

@@ -0,0 +1,18 @@
+import type { TestResult } from '@playwright/test/reporter';
+/**
+ * Build the stored error text for a test result.
+ *
+ * Playwright's `result.error` carries the primary failure but for a **timeout**
+ * it is only the bare `Test timeout of 30000ms exceeded.` — the interrupted
+ * action's actual error (with its call log — the single most diagnostic fact)
+ * lives in `result.errors[1..]`. Concatenating all errors (deduped by message)
+ * ensures the server sees the call log so it can extract the locator, fingerprint
+ * correctly, and feed the model the right facts.
+ *
+ * A synthetic `at file:line:col` frame from `error.location` is appended when
+ * no stack frame is present, enabling locator-healing to find the pre-captured
+ * snapshot for that call site. The frame sits after the message, where
+ * `extractMessageHead` trims it before fingerprinting — so clustering is
+ * unaffected.
+ */
+export declare function buildErrorText(result: TestResult): string | null;

package/dist/internal/collect/error-text.js

@@ -0,0 +1,79 @@
+"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.buildErrorText = buildErrorText;
+const path = __importStar(require("node:path"));
+/**
+ * Build the stored error text for a test result.
+ *
+ * Playwright's `result.error` carries the primary failure but for a **timeout**
+ * it is only the bare `Test timeout of 30000ms exceeded.` — the interrupted
+ * action's actual error (with its call log — the single most diagnostic fact)
+ * lives in `result.errors[1..]`. Concatenating all errors (deduped by message)
+ * ensures the server sees the call log so it can extract the locator, fingerprint
+ * correctly, and feed the model the right facts.
+ *
+ * A synthetic `at file:line:col` frame from `error.location` is appended when
+ * no stack frame is present, enabling locator-healing to find the pre-captured
+ * snapshot for that call site. The frame sits after the message, where
+ * `extractMessageHead` trims it before fingerprinting — so clustering is
+ * unaffected.
+ */
+function buildErrorText(result) {
+    if (!result.errors || result.errors.length === 0)
+        return null;
+    const seen = new Set();
+    const parts = [];
+    for (const err of result.errors) {
+        const msg = err.message ?? '';
+        if (!msg)
+            continue;
+        const dedupeKey = msg.trim().slice(0, 200);
+        if (seen.has(dedupeKey))
+            continue;
+        seen.add(dedupeKey);
+        parts.push(msg);
+    }
+    let text = parts.join('\n---\n');
+    if (!text)
+        return null;
+    const primary = result.error;
+    const loc = primary?.location;
+    if (loc?.file && !/\n\s+at\s/.test(text)) {
+        const rel = path.relative(process.cwd(), loc.file).split(path.sep).join('/');
+        text += `\n    at ${rel}:${loc.line}:${loc.column}`;
+    }
+    return text;
+}

package/dist/{metadata-collector.d.ts → internal/collect/metadata-collector.d.ts}

@@ -1,6 +1,6 @@
 import type { FullConfig, Suite, TestCase } from '@playwright/test/reporter';
-import { Logger } from './logger.js';
-import type { SuiteConfigEntry } from './types.js';
+import { Logger } from '../support/logger.js';
+import type { SuiteConfigEntry } from '../../types.js';
 /**
  * Collects CI/CD environment metadata, SCM (git) information, and Playwright
  * config metadata to attach to each test run submission.

package/dist/{metadata-collector.js → internal/collect/metadata-collector.js}

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MetadataCollector = void 0;
-const child_process_1 = require("child_process");
-const logger_js_1 = require("./logger.js");
+const node_child_process_1 = require("node:child_process");
+const errors_js_1 = require("../support/errors.js");
+const logger_js_1 = require("../support/logger.js");
 /**
  * Collects CI/CD environment metadata, SCM (git) information, and Playwright
  * config metadata to attach to each test run submission.
@@ -47,7 +48,7 @@ class MetadataCollector {
             const all = suite.allTests();
             if (all.length > 0) {
                 const first = all[0];
-                if (first?.parent?.project) {
+                if (first?.parent) {
                     const proj = first.parent.project();
                     if (proj?.metadata)
                         metadata.playwrightProject = proj.metadata;
@@ -146,23 +147,25 @@ class MetadataCollector {
         const scm = {};
         try {
             const execOpts = { encoding: 'utf8', timeout: 5000, maxBuffer: 1024 * 1024 };
-            scm.commit = (0, child_process_1.execSync)('git rev-parse HEAD', execOpts).trim();
-            scm.branch = (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD', execOpts).trim();
-            scm.author = (0, child_process_1.execSync)('git log -1 --pretty=format:"%an"', execOpts).trim();
-            scm.commitMessage = (0, child_process_1.execSync)('git log -1 --pretty=format:"%s"', execOpts).trim();
+            scm.commit = (0, node_child_process_1.execSync)('git rev-parse HEAD', execOpts).trim();
+            scm.branch = (0, node_child_process_1.execSync)('git rev-parse --abbrev-ref HEAD', execOpts).trim();
+            scm.author = (0, node_child_process_1.execSync)('git log -1 --pretty=format:"%an"', execOpts).trim();
+            scm.commitMessage = (0, node_child_process_1.execSync)('git log -1 --pretty=format:"%s"', execOpts).trim();
             try {
-                scm.remoteUrl = (0, child_process_1.execSync)('git config --get remote.origin.url', execOpts).trim();
+                scm.remoteUrl = (0, node_child_process_1.execSync)('git config --get remote.origin.url', execOpts).trim();
             }
             catch {
                 /* optional */
             }
         }
         catch (error) {
-            this.logger.debug(`Git info not available: ${error.message}`);
+            this.logger.debug(`Git info not available: ${(0, errors_js_1.errorMessage)(error)}`);
         }
         return Object.keys(scm).length > 0 ? scm : undefined;
     }
     collectCiInfo() {
+        // Env vars are `string | undefined`; undefined values are dropped on JSON
+        // serialization, so collecting them directly preserves the prior behavior.
         const ci = {};
         const env = process.env;
         if (env.JENKINS_URL) {

package/dist/{skip-classify.d.ts → internal/collect/skip-classify.d.ts}

@@ -1,4 +1,4 @@
-import type { TestAnnotation } from './types.js';
+import type { TestAnnotation } from '../../types.js';
 /** Minimal structural shape for the annotation carriers (avoids importing Playwright types). */
 interface AnnotationCarrier {
     annotations?: ReadonlyArray<{

package/dist/{step-analyzer.d.ts → internal/collect/step-analyzer.d.ts}

@@ -14,6 +14,12 @@ export interface FlatStep {
     title: string;
     duration: number;
     category: string;
+    /** Error message when the step failed (undefined when the step passed). */
+    error?: {
+        message: string;
+    };
+    /** True when the step carried an error — the signal the server needs for inline failure markers. */
+    failed?: boolean;
 }
 /** Step-event category restricted to the values `extractTestStepEvents` emits. */
 export type StepEventCategory = 'hook' | 'fixture' | 'test.step' | 'expect' | 'wait';

package/dist/{step-analyzer.js → internal/collect/step-analyzer.js}

@@ -84,11 +84,16 @@ function categorizeStep(title, pwCategory) {
 function flattenSteps(steps) {
     const result = [];
     for (const step of steps) {
-        result.push({
+        const flat = {
             title: step.title,
             duration: step.duration,
             category: categorizeStep(step.title, step.category),
-        });
+        };
+        if (step.error?.message) {
+            flat.error = { message: step.error.message };
+            flat.failed = true;
+        }
+        result.push(flat);
         if (step.steps?.length > 0)
             result.push(...flattenSteps(step.steps));
     }

package/dist/internal/config/env.d.ts

@@ -0,0 +1,45 @@
+import type { PiwiDashboardOptions } from '../../public/options.js';
+/**
+ * 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";
+    readonly captureLocators: "PIWI_CAPTURE_LOCATORS";
+};
+/**
+ * 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 (`PIWI_PROJECT_NAME` would otherwise be masked by the
+ * `default-project` default).
+ *
+ * One preserved quirk: `PIWI_VERBOSE` wins over both the default *and* an
+ * explicit user option.
+ */
+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 → internal/config/env.js}

@@ -3,6 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PIWI_ENV_KEYS = void 0;
 exports.resolveOptions = resolveOptions;
 exports.applyOptionsToEnv = applyOptionsToEnv;
+/**
+ * Built-in option defaults, merged *under* any user-provided or env-derived
+ * value (see `resolveOptions`).
+ */
 const DEFAULTS = {
     projectName: 'default-project',
     uploadTraces: true,
@@ -49,53 +53,64 @@ function readBool(val) {
         return undefined;
     return val === 'true';
 }
+/**
+ * Declarative env → option fallback table. `resolveOptions` walks this instead
+ * of repeating ~15 near-identical merge lines, so adding an env-backed option
+ * means adding one row.
+ *
+ * Guard semantics (preserved from the original hand-written merges):
+ *  - `string` / `number`: a *truthy* env value fills the option, so an empty
+ *    string is ignored.
+ *  - `bool`: any *defined* env value fills it (via `readBool`), so
+ *    `PIWI_STREAMING=false` actually disables streaming.
+ *
+ * `verbose` is intentionally absent — it *overrides* rather than falls back, and
+ * is applied after the `DEFAULTS` merge in `resolveOptions`.
+ */
+const ENV_FALLBACK_SPECS = [
+    { option: 'serverUrl', env: exports.PIWI_ENV_KEYS.serverUrl, kind: 'string' },
+    { option: 'projectName', env: exports.PIWI_ENV_KEYS.projectName, kind: 'string' },
+    { option: 'apiKey', env: exports.PIWI_ENV_KEYS.apiKey, kind: 'string' },
+    { option: 'username', env: exports.PIWI_ENV_KEYS.username, kind: 'string' },
+    { option: 'password', env: exports.PIWI_ENV_KEYS.password, kind: 'string' },
+    { option: 'environment', env: exports.PIWI_ENV_KEYS.environment, kind: 'string' },
+    { option: 'label', env: exports.PIWI_ENV_KEYS.label, kind: 'string' },
+    { option: 'runLabel', env: exports.PIWI_ENV_KEYS.runLabel, kind: 'string' },
+    { option: 'streaming', env: exports.PIWI_ENV_KEYS.streaming, kind: 'bool' },
+    { option: 'streamingBatchSize', env: exports.PIWI_ENV_KEYS.streamingBatchSize, kind: 'number' },
+    { option: 'streamingBatchDelay', env: exports.PIWI_ENV_KEYS.streamingBatchDelay, kind: 'number' },
+    { option: 'liveFileUploads', env: exports.PIWI_ENV_KEYS.liveFileUploads, kind: 'bool' },
+    { option: 'uploadTraces', env: exports.PIWI_ENV_KEYS.uploadTraces, kind: 'bool' },
+    { option: 'uploadReport', env: exports.PIWI_ENV_KEYS.uploadReport, kind: 'bool' },
+    { option: 'captureLocators', env: exports.PIWI_ENV_KEYS.captureLocators, kind: 'bool' },
+];
 /**
  * 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).
+ * never masks an env var (`PIWI_PROJECT_NAME` would otherwise be masked by the
+ * `default-project` default).
  *
  * One preserved quirk: `PIWI_VERBOSE` wins over both the default *and* an
- * explicit user option, matching the pre-Phase-4 behavior.
+ * explicit user option.
  */
 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]);
-    if (mergedRaw.captureLocators === undefined && env[exports.PIWI_ENV_KEYS.captureLocators] !== undefined)
-        mergedRaw.captureLocators = readBool(env[exports.PIWI_ENV_KEYS.captureLocators]);
+    for (const spec of ENV_FALLBACK_SPECS) {
+        if (mergedRaw[spec.option] !== undefined)
+            continue;
+        const value = env[spec.env];
+        if (spec.kind === 'bool') {
+            if (value !== undefined)
+                mergedRaw[spec.option] = readBool(value);
+        }
+        else if (value) {
+            mergedRaw[spec.option] = spec.kind === 'number' ? Number(value) : value;
+        }
+    }
     const opts = { ...DEFAULTS, ...mergedRaw };
     // Preserved quirk: PIWI_VERBOSE wins over both default and user option.
     if (env[exports.PIWI_ENV_KEYS.verbose] !== undefined)