TestLens Playwright Reporter

A Playwright reporter for TestLens - 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

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)

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)

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)

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)

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

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 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.

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:

# Linux / macOS
export TESTLENS_EXECUTION_ID="${BITBUCKET_BUILD_UUID}"
npx playwright test

# Or inline
TESTLENS_EXECUTION_ID="my-build-123" npx playwright test

# 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

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:

// 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):

// 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 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. | | 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