@alternative-path/testlens-playwright-reporter 0.4.8 → 0.4.9

package/README.md

@@ -126,6 +126,88 @@ The reporter automatically reads these environment variables (no config changes
 - **API Key**: `TESTLENS_API_KEY` (also checks: `testlens_api_key`, `TESTLENS_KEY`, `testlensApiKey`, `PLAYWRIGHT_API_KEY`, `PW_API_KEY`)
 - **Build Name**: `testlensBuildName` (also checks: `TESTLENS_BUILD_NAME`, `BUILDNAME`, `BUILD_NAME`)
 - **Build Tag**: `testlensBuildTag` (also checks: `TESTLENS_BUILD_TAG`, `BUILDTAG`, `BUILD_TAG`)
+- **Execution ID** (one run per pipeline): see [One test run per pipeline execution](#one-test-run-per-pipeline-execution) below.
+
+### One test run per pipeline execution
+
+If your pipeline runs `npx playwright test` in **multiple steps**, you get one TestLens run per step. To group all steps into **one** run, set **`TESTLENS_EXECUTION_ID`** to your pipeline’s run identifier (e.g. build number or run ID) in every step. Use one of the three methods below. For per-CI examples (Bitbucket, GitHub, GitLab, Azure DevOps, Jenkins), see **[PIPELINE_EXECUTION_ID.md](./PIPELINE_EXECUTION_ID.md)**.
+
+#### 1. Environment variable (recommended in CI)
+
+Set one of these env vars **before** each Playwright step. The reporter uses the **first one it finds** (in this order):
+
+| Env var | When to use |
+|---------|--------------|
+| `TESTLENS_EXECUTION_ID` | Any pipeline; set this to your build/run ID |
+| `TestlensExecutionId`, `TestLensExecutionId`, `testlensexecutionid` | Alternative spellings |
+| `BITBUCKET_BUILD_UUID` | Bitbucket Pipelines (auto-set; no config needed) |
+| `GITHUB_RUN_ID` | GitHub Actions (auto-set) |
+| `CI_PIPELINE_ID`, `CI_JOB_ID` | GitLab CI |
+| `BUILD_BUILDID`, `SYSTEM_JOBID` | Azure DevOps |
+| `BUILD_ID`, `BUILD_NUMBER` | Jenkins |
+| `CIRCLE_WORKFLOW_ID`, `CIRCLE_BUILD_NUM` | CircleCI |
+
+**Command examples:**
+
+```bash
+# Linux / macOS
+export TESTLENS_EXECUTION_ID="${BITBUCKET_BUILD_UUID}"
+npx playwright test
+
+# Or inline
+TESTLENS_EXECUTION_ID="my-build-123" npx playwright test
+```
+
+```powershell
+# Windows PowerShell
+$env:TESTLENS_EXECUTION_ID = $env:BITBUCKET_BUILD_UUID
+npx playwright test
+
+# Or inline
+$env:TESTLENS_EXECUTION_ID="my-build-123"; npx playwright test
+```
+
+```cmd
+REM Windows CMD
+set TESTLENS_EXECUTION_ID=my-build-123 && npx playwright test
+```
+
+#### 2. Config option `executionId`
+
+In your Playwright config, set the top-level reporter option:
+
+```typescript
+// playwright.config.ts
+reporter: [
+  ['@alternative-path/testlens-playwright-reporter', {
+    apiKey: process.env.TESTLENS_API_KEY,
+    executionId: process.env.BITBUCKET_BUILD_UUID,  // or any string
+  }]
+],
+```
+
+#### 3. Config option `customMetadata`
+
+You can pass the execution ID inside `customMetadata` (as `executionId` or `TESTLENS_EXECUTION_ID`):
+
+```typescript
+// playwright.config.ts
+reporter: [
+  ['@alternative-path/testlens-playwright-reporter', {
+    apiKey: process.env.TESTLENS_API_KEY,
+    customMetadata: {
+      executionId: process.env.BITBUCKET_BUILD_UUID,
+      // or: TESTLENS_EXECUTION_ID: process.env.BITBUCKET_BUILD_UUID,
+      testlensBuildName: 'Build123',
+      testlensBuildTag: 'smoke',
+    },
+  }]
+],
+```
+
+#### Recommendation
+
+Prefer a **UUID or globally unique ID** (e.g. `BITBUCKET_BUILD_UUID`, `GITHUB_RUN_ID`) so different repos or pipelines never share the same run. Build numbers like `BUILD_NUMBER` reset per repo and can collide. See **[PIPELINE_EXECUTION_ID.md](./PIPELINE_EXECUTION_ID.md)** for per-CI examples.
 
 ### Notes
 
@@ -140,6 +222,7 @@ The reporter automatically reads these environment variables (no config changes
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `apiKey` | `string` | **Required** | Your TestLens API key |
+| `executionId` | `string` | — | Optional. When set (or use env `TESTLENS_EXECUTION_ID`, any auto-detected CI run ID, or `customMetadata.executionId` / `customMetadata.TESTLENS_EXECUTION_ID`), used as run ID so multiple pipeline steps share one run. See [PIPELINE_EXECUTION_ID.md](./PIPELINE_EXECUTION_ID.md). |
 
 ## Artifacts
 

package/index.d.ts

@@ -28,6 +28,8 @@ export interface TestLensReporterConfig {
     ignoreSslErrors?: boolean;
     /** Custom metadata from CLI arguments (automatically parsed from --key=value arguments) */
     customMetadata?: Record<string, string | string[]>;
+    /** Execution ID for one run per pipeline (e.g. from TESTLENS_EXECUTION_ID or CI build UUID). When set, used as runId so multiple steps share one run. */
+    executionId?: string;
 }
 export interface TestLensReporterOptions {
     /** TestLens API endpoint URL */
@@ -58,6 +60,8 @@ export interface TestLensReporterOptions {
     ignoreSslErrors?: boolean;
     /** Custom metadata from CLI arguments (automatically parsed from --key=value arguments) */
     customMetadata?: Record<string, string | string[]>;
+    /** Execution ID for one run per pipeline (e.g. from TESTLENS_EXECUTION_ID or CI build UUID). When set, used as runId so multiple steps share one run. */
+    executionId?: string;
 }
 export interface GitInfo {
     branch: string;
@@ -157,6 +161,7 @@ export declare class TestLensReporter implements Reporter {
     private axiosInstance;
     private runId;
     private runMetadata;
+    private usedExecutionId;
     private specMap;
     private testMap;
     private runCreationFailed;

package/index.js

@@ -91,6 +91,23 @@ class TestLensReporter {
             // Support both TestLens-specific names (recommended) and common CI names
             'testlensBuildTag': ['testlensBuildTag', 'TESTLENS_BUILD_TAG', 'TESTLENS_BUILDTAG', 'BUILDTAG', 'BUILD_TAG', 'TestlensBuildTag', 'TestLensBuildTag'],
             'testlensBuildName': ['testlensBuildName', 'TESTLENS_BUILD_NAME', 'TESTLENS_BUILDNAME', 'BUILDNAME', 'BUILD_NAME', 'TestlensBuildName', 'TestLensBuildName'],
+            // Execution ID for one run per pipeline (checked in order; prefer TESTLENS_EXECUTION_ID, then CI-specific UUIDs)
+            'executionId': [
+                'TESTLENS_EXECUTION_ID',
+                'TestlensExecutionId',
+                'TestLensExecutionId',
+                'testlensexecutionid',
+                'BITBUCKET_BUILD_UUID',
+                'GITHUB_RUN_ID',
+                'CI_PIPELINE_ID',
+                'CI_JOB_ID',
+                'BUILD_BUILDID',
+                'SYSTEM_JOBID',
+                'BUILD_ID',
+                'BUILD_NUMBER',
+                'CIRCLE_WORKFLOW_ID',
+                'CIRCLE_BUILD_NUM'
+            ],
             'environment': ['ENVIRONMENT', 'ENV', 'NODE_ENV', 'DEPLOYMENT_ENV'],
             'branch': ['BRANCH', 'GIT_BRANCH', 'CI_COMMIT_BRANCH', 'GITHUB_REF_NAME'],
             'team': ['TEAM', 'TEAM_NAME'],
@@ -118,6 +135,7 @@ class TestLensReporter {
         return customArgs;
     }
     constructor(options) {
+        this.usedExecutionId = false; // True when runId came from executionId (multi-step); backend should aggregate runEnd
         this.runCreationFailed = false; // Track if run creation failed due to limits
         this.cliArgs = {}; // Store CLI args separately
         this.pendingUploads = new Set(); // Track pending artifact uploads
@@ -157,7 +175,8 @@ class TestLensReporter {
             timeout: options.timeout || 60000,
             rejectUnauthorized: options.rejectUnauthorized,
             ignoreSslErrors: options.ignoreSslErrors,
-            customMetadata: { ...options.customMetadata, ...customArgs } // Config metadata first, then CLI args override
+            customMetadata: { ...options.customMetadata, ...customArgs }, // Config metadata first, then CLI args override
+            executionId: options.executionId
         };
         if (!this.config.apiKey) {
             throw new Error('API_KEY is required for TestLensReporter. Pass it as apiKey option in your playwright config or set one of these environment variables: TESTLENS_API_KEY, TESTLENS_KEY, PLAYWRIGHT_API_KEY, PW_API_KEY, API_KEY, or APIKEY.');
@@ -223,7 +242,17 @@ class TestLensReporter {
             }
             return Promise.reject(error);
         });
-        this.runId = (0, crypto_1.randomUUID)();
+        const executionIdFromCustomMetadata = this.config.customMetadata?.executionId ?? this.config.customMetadata?.TESTLENS_EXECUTION_ID;
+        const executionIdFromCustomMetadataStr = Array.isArray(executionIdFromCustomMetadata)
+            ? executionIdFromCustomMetadata[0]
+            : executionIdFromCustomMetadata;
+        const executionIdRaw = options.executionId ??
+            process.env.TESTLENS_EXECUTION_ID ??
+            customArgs.executionId ??
+            executionIdFromCustomMetadataStr;
+        const executionId = typeof executionIdRaw === 'string' && executionIdRaw.trim() ? String(executionIdRaw).trim() : undefined;
+        this.runId = executionId || (0, crypto_1.randomUUID)();
+        this.usedExecutionId = !!executionId;
         this.runMetadata = this.initializeRunMetadata();
         this.specMap = new Map();
         this.testMap = new Map();
@@ -713,7 +742,8 @@ class TestLensReporter {
                 failedTests, // Already includes timedOut tests (normalized to 'failed')
                 skippedTests,
                 timedOutTests, // For informational purposes
-                status: normalizedRunStatus
+                status: normalizedRunStatus,
+                aggregationMode: this.usedExecutionId ? 'append' : 'replace'
             }
         });
         // Show Build Name if provided, otherwise show Run ID