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

package/README.md

@@ -1,246 +1,248 @@
-# TestLens Playwright Reporter
-
-A Playwright reporter for [TestLens](https://testlens.qa-path.com) - real-time test monitoring dashboard.
-
-## Features
-
-- 🚀 **Real-time streaming** - Watch test results as they happen in the dashboard
-- 📸 **Artifact support** - Shows screenshots, videos, and traces
-- 🔄 **Retry tracking** - Monitor test retries and identify flaky tests
-- ⚡ **Cross-platform** - Works on Windows, macOS, and Linux
-
-## Installation
-
-```bash
-npm i @alternative-path/testlens-playwright-reporter
-```
-
-## Configuration
-
-### Quick Start (Recommended)
-
-The simplest config - API key and metadata are passed via environment variables:
-
-**TypeScript (`playwright.config.ts`)**
-```typescript
-import { defineConfig } from '@playwright/test';
-
-export default defineConfig({
-  use: {
-    screenshot: 'on',
-    video: 'on',
-    trace: 'on',
-  },
-  reporter: [
-    ['testlens-playwright-reporter']
-    // API key is auto-detected from TESTLENS_API_KEY env var
-    // Build metadata is auto-detected from testlensBuildName/testlensBuildTag env vars
-  ],
-});
-```
-
-**JavaScript (`playwright.config.js`)**
-```javascript
-const { defineConfig } = require('@playwright/test');
-
-module.exports = defineConfig({
-  use: {
-    screenshot: 'on',
-    video: 'on',
-    trace: 'on',
-  },
-  reporter: [
-    ['testlens-playwright-reporter']
-    // API key is auto-detected from TESTLENS_API_KEY env var
-    // Build metadata is auto-detected from testlensBuildName/testlensBuildTag env vars
-  ],
-});
-```
-
-### Advanced Configuration (Optional)
-
-If you prefer to set API key or metadata explicitly in config:
-
-**TypeScript (`playwright.config.ts`)**
-```typescript
-import { defineConfig } from '@playwright/test';
-
-export default defineConfig({
-  use: {
-    screenshot: 'on',
-    video: 'on',
-    trace: 'on',
-  },
-  reporter: [
-    ['@alternative-path/testlens-playwright-reporter', {
-      apiKey: process.env.TESTLENS_API_KEY || 'your-api-key-here',
-      
-      // Optional: explicitly forward build metadata from env vars
-      customMetadata: {
-        testlensBuildName: process.env.testlensBuildName,
-        testlensBuildTag: process.env.testlensBuildTag,
-      },
-    }]
-  ],
-});
-```
-
-**JavaScript (`playwright.config.js`)**
-```javascript
-const { defineConfig } = require('@playwright/test');
-
-module.exports = defineConfig({
-  use: {
-    screenshot: 'on',
-    video: 'on',
-    trace: 'on',
-  },
-  reporter: [
-    ['@alternative-path/testlens-playwright-reporter', {
-      apiKey: process.env.TESTLENS_API_KEY || 'your-api-key-here',
-      
-      // Optional: explicitly forward build metadata from env vars
-      customMetadata: {
-        testlensBuildName: process.env.testlensBuildName,
-        testlensBuildTag: process.env.testlensBuildTag,
-      },
-    }]
-  ],
-});
-```
-
-## Run With Build Name & Tag (UI Mode)
-
-Use `testlens-cross-env` (bundled with this package) to set API key and metadata cross-platform, including Windows.
-
-### Command
-
-```bash
-npx testlens-cross-env TESTLENS_API_KEY="<your-api-key>" testlensBuildName="Testing Build Local Environment" testlensBuildTag="smoke" playwright test --ui
-```
-
-### What Gets Auto-Detected
-
-The reporter automatically reads these environment variables (no config changes needed):
-
-- **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
-
-- No config changes required - just pass env vars in the command
-- `testlensBuildName` and `testlensBuildTag` are sent to TestLens as run `custom_metadata`
-- Multiple tags: use comma-separated list `testlensBuildTag="smoke,regression"`
-
-> 💡 **Tip:** Keep `screenshot`, `video`, and `trace` set to `'on'` for better debugging experience. TestLens automatically uploads these artifacts for failed tests, making it easier to identify issues.
-
-### Configuration Options
-
-| 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
-
-TestLens automatically captures and uploads:
-
-| Artifact | Description |
-|----------|-------------|
-| **Screenshots** | Visual snapshots of test failures |
-| **Videos** | Full video recording of test execution |
-| **Traces** | Playwright trace files for step-by-step debugging |
-
-These artifacts are viewable directly in the TestLens dashboard for easy debugging.
-
-## Requirements
-
-- Node.js >= 16.0.0
-- Playwright >= 1.40.0
-
-## License
-
-MIT License
+# TestLens Playwright Reporter
+
+A Playwright reporter for [TestLens](https://testlens.qa-path.com) - real-time test monitoring dashboard.
+
+## Features
+
+- 🚀 **Real-time streaming** - Watch test results as they happen in the dashboard
+- 📸 **Artifact support** - Shows screenshots, videos, and traces
+- 🔄 **Retry tracking** - Monitor test retries and identify flaky tests
+- ⚡ **Cross-platform** - Works on Windows, macOS, and Linux
+
+## Installation
+
+```bash
+npm i @alternative-path/testlens-playwright-reporter
+```
+
+## Configuration
+
+### Quick Start (Recommended)
+
+The simplest config - API key and metadata are passed via environment variables:
+
+**TypeScript (`playwright.config.ts`)**
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    screenshot: 'on',
+    video: 'on',
+    trace: 'on',
+  },
+  reporter: [
+    ['testlens-playwright-reporter']
+    // API key is auto-detected from TESTLENS_API_KEY env var
+    // Build metadata is auto-detected from testlensBuildName/testlensBuildTag env vars
+  ],
+});
+```
+
+**JavaScript (`playwright.config.js`)**
+```javascript
+const { defineConfig } = require('@playwright/test');
+
+module.exports = defineConfig({
+  use: {
+    screenshot: 'on',
+    video: 'on',
+    trace: 'on',
+  },
+  reporter: [
+    ['testlens-playwright-reporter']
+    // API key is auto-detected from TESTLENS_API_KEY env var
+    // Build metadata is auto-detected from testlensBuildName/testlensBuildTag env vars
+  ],
+});
+```
+
+### Advanced Configuration (Optional)
+
+If you prefer to set API key or metadata explicitly in config:
+
+**TypeScript (`playwright.config.ts`)**
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    screenshot: 'on',
+    video: 'on',
+    trace: 'on',
+  },
+  reporter: [
+    ['@alternative-path/testlens-playwright-reporter', {
+      apiKey: process.env.TESTLENS_API_KEY || 'your-api-key-here',
+      
+      // Optional: explicitly forward build metadata from env vars
+      customMetadata: {
+        testlensBuildName: process.env.testlensBuildName,
+        testlensBuildTag: process.env.testlensBuildTag,
+      },
+    }]
+  ],
+});
+```
+
+**JavaScript (`playwright.config.js`)**
+```javascript
+const { defineConfig } = require('@playwright/test');
+
+module.exports = defineConfig({
+  use: {
+    screenshot: 'on',
+    video: 'on',
+    trace: 'on',
+  },
+  reporter: [
+    ['@alternative-path/testlens-playwright-reporter', {
+      apiKey: process.env.TESTLENS_API_KEY || 'your-api-key-here',
+      
+      // Optional: explicitly forward build metadata from env vars
+      customMetadata: {
+        testlensBuildName: process.env.testlensBuildName,
+        testlensBuildTag: process.env.testlensBuildTag,
+      },
+    }]
+  ],
+});
+```
+
+## Run With Build Name & Tag (UI Mode)
+
+Use `TESTLENS-REPORTER` (bundled with this package) to set API key and metadata cross-platform, including Windows.
+
+### Command
+
+```bash
+npx TESTLENS-REPORTER TESTLENS_API_KEY="<your-api-key>" testlensBuildName="Testing Build Local Environment" testlensBuildTag="smoke" playwright test --ui
+```
+
+### What Gets Auto-Detected
+
+The reporter automatically reads these environment variables (no config changes needed):
+
+- **API Key**: `TESTLENS_API_KEY` (also checks: `testlens_api_key`, `TESTLENS_KEY`, `testlensApiKey`, `PLAYWRIGHT_API_KEY`, `PW_API_KEY`)
+- **Build Name**: `TL_BUILDNAME` or `testlensBuildName` (also checks: `TESTLENS_BUILD_NAME`, `TESTLENS_BUILDNAME`, `BUILDNAME`, `BUILD_NAME`). Env keys are matched **case-insensitively** (e.g. `tl_buildname` works).
+- **Build Tag**: `TL_BUILDTAG` or `testlensBuildTag` (also checks: `TESTLENS_BUILD_TAG`, `TESTLENS_BUILDTAG`, `BUILDTAG`, `BUILD_TAG`). Env keys are matched **case-insensitively** (e.g. `tl_buildtag` works).
+- **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 |
+|---------|--------------|
+| `TL_EXECUTIONID` | Short alias (matched case-insensitively) |
+| `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
+
+- No config changes required - just pass env vars in the command
+- `testlensBuildName` and `testlensBuildTag` are sent to TestLens as run `custom_metadata`
+- Multiple tags: use comma-separated list `testlensBuildTag="smoke,regression"`
+
+> 💡 **Tip:** Keep `screenshot`, `video`, and `trace` set to `'on'` for better debugging experience. TestLens automatically uploads these artifacts for failed tests, making it easier to identify issues.
+
+### Configuration Options
+
+| 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). |
+| `logLevel` | `'info' \| 'debug'` | `'info'` | Logging level. `'info'` shows test start/completion with status and errors. `'debug'` shows all internal operations. Can also be set via `TESTLENS_LOG_LEVEL` env var. |
+
+## Artifacts
+
+TestLens automatically captures and uploads:
+
+| Artifact | Description |
+|----------|-------------|
+| **Screenshots** | Visual snapshots of test failures |
+| **Videos** | Full video recording of test execution |
+| **Traces** | Playwright trace files for step-by-step debugging |
+
+These artifacts are viewable directly in the TestLens dashboard for easy debugging.
+
+## Requirements
+
+- Node.js >= 16.0.0
+- Playwright >= 1.40.0
+
+## License
+
+MIT License

package/cross-env.js

@@ -12,10 +12,10 @@
  * - Any platform that runs Node.js
  * 
  * Usage:
- *   npx testlens-cross-env VAR1=value1 VAR2=value2 command args...
+ *   npx TESTLENS-REPORTER VAR1=value1 VAR2=value2 command args...
  * 
  * Example:
- *   npx testlens-cross-env testlensApiKey="abc123" playwright test
+ *   npx TESTLENS-REPORTER testlensApiKey="abc123" playwright test
  */
 
 const crossEnv = require('cross-env');

package/index.d.ts

@@ -30,6 +30,12 @@ export interface TestLensReporterConfig {
     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;
+    /**
+     * Log level for the reporter.
+     * - 'info' (default): Shows test start/completion with status, artifact status, and errors
+     * - 'debug': Shows all logs including detailed internal operations
+     */
+    logLevel?: 'info' | 'debug';
 }
 export interface TestLensReporterOptions {
     /** TestLens API endpoint URL */
@@ -62,6 +68,12 @@ export interface TestLensReporterOptions {
     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;
+    /**
+     * Log level for the reporter.
+     * - 'info' (default): Shows test start/completion with status, artifact status, and errors
+     * - 'debug': Shows all logs including detailed internal operations
+     */
+    logLevel?: 'info' | 'debug';
 }
 export interface GitInfo {
     branch: string;
@@ -167,9 +179,13 @@ export declare class TestLensReporter implements Reporter {
     private runCreationFailed;
     private cliArgs;
     private pendingUploads;
-    private traceNetworkRows;
     private artifactStats;
     private artifactsSeen;
+    private logger;
+    /**
+     * Get environment variable value with case-insensitive key match (e.g. TL_BUILDNAME, tl_buildname).
+     */
+    private static getEnvCaseInsensitive;
     /**
      * Parse custom metadata from environment variables
      * Checks for common metadata environment variables