Playwright JS framework

The SeaLights Playwright Plugin (sealights-playwright-plugin) integrates Playwright tests with the SeaLights Quality Platform to provide test analytics, code coverage visibility, and test optimization across your pipelines.

It’s a non-intrusive setup — no persistent changes to your Playwright configuration files and tests are required. Simply install the plugin, export your environment variables, execute the plugin utility, and run your Playwright tests as usual.

Configuration

1

Install the Plugin

To install the Sealights Playwright plugin, use npm:

npm install sealights-playwright-plugin

For more details, you can also refer to https://www.npmjs.com/package/sealights-playwright-plugin

2

Set Environment Variables

Define your SeaLights configuration via environment variables — this is the preferred approach for CI/CD systems like GitHub Actions, Jenkins, Tekton, Azure Pipelines, or Kubernetes Pods.

Unix/Linux

export SL_TOKEN=<your_token>             # from CI secret or vault
export SL_LAB_ID=<your_labid>            # Identifier for the lab environment.
export SL_TEST_STAGE="E2E Tests"

PowerShell

$env:SL_TOKEN = "<your_token>"             # from CI secret or vault
$env:SL_LAB_ID = "<your_labid>"            # Identifier for the lab environment.
$env:SL_TEST_STAGE = "E2E Tests"

The build session id is resolved automatically by the backend at runtime using the SL_LAB_ID.

3

Run the Import Replacement Utility

To simplify the integration process, Sealights provides an enhanced utility script that automatically replaces existing imports from @playwright/test with imports from sealights-playwright-plugin.

Execute the update-imports utility command from the root directory of your project, where the node_modules folder is located, using the following command:

npx sealights-playwright-plugin update-imports --test-dir <path-to-your-test-folder>

Replace <path-to-your-test-folder> with the relative or absolute path to the directory containing your Playwright test files.

4

Run Your Tests As Usual

Run Your Tests as usual. The plugin will automatically track coverage and provide insights during the test execution.

When the Playwright tests complete successfully, a new test stage (with the name you specified) will appear in the Sealights dashboard under the corresponding build. This stage will include the associated test results and coverage data. If Test Optimization is enabled, irrelevant tests will automatically be skipped.

Minimal Prerequisites

The Sealights Playwright Plugin requires the following system configuration to run effectively:

• Node.js: Version 18 or higher.
• Playwright: Version 1.20 or higher.

Logging and Debugging

Extra logs can be enabled using the following environment variable:

export NODE_DEBUG=sl

The default log level with this var on is info. To obtain the debug logs, you can set another variable:

export SL_LOG_LEVEL=debug

Troubleshooting & Best Practices

• If required environment variables are missing (e.g., SL_TOKEN, SL_TEST_STAGE, or neither SL_BUILD_SESSION_ID nor SL_LAB_ID is provided), the plugin will throw an error, preventing the tests from running with Sealights but not stopping them from executing on their own. Ensure all required variables are set correctly.
• The utility will process the files in the specified directory and replace the imports from @playwright/test with imports from sealights-playwright-plugin according to the supported styles.

  • After running the script, verify the changes in your test files.
  • Review the modified files to ensure the imports have been replaced correctly.
  • It’s recommended not to store these changes in your version control (e.g., Git) and revert if necessary.

Sample Scripts

Unix/Linux (Bash)

# 1. Install SeaLights Playwright plugin
npm install sealights-playwright-plugin

# 2. Set environment variables 
export SL_TOKEN=123456               # From CI/CD Credentials/Secrets
export SL_LAB_ID=integ_e2e1          # Testing environment identifier
export SL_TESTSTAGE="E2E"
#export NODE_DEBUG=sl
#export SL_LOG_LEVEL=debug

# 3. Use the Import Update command
npx sealights-playwright-plugin update-imports --test-dir ./tests/e2e

# 4. Run tests as usual
npx playwright:e2e

GitHub Actions

name: Playwright E2E
on: [push, workflow_dispatch]
jobs:
  e2e:
    runs-on: ubuntu-latest
    env:
      SEALIGHTS_ENABLED: true            # set false to skip Sealights
      SL_LAB_ID: integ_e2e1
      SL_TESTS_PATH: ./tests/e2e
      SL_TEST_STAGE: "Playwright E2E"
      SL_TOKEN: ${{ secrets.SL_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      # Sealights setup (conditional)
      - name: Setup SeaLights
        if: ${{ env.SEALIGHTS_ENABLED == 'true' }}
        run: |
          npm install --no-audit sealights-playwright-plugin
          echo "SL_TOKEN=$SL_TOKEN" >> $GITHUB_ENV
          echo "SL_LAB_ID=$SL_LAB_ID" >> $GITHUB_ENV
          echo "SL_TESTSTAGE=$SL_TEST_STAGE" >> $GITHUB_ENV
          npx sealights-playwright-plugin update-imports --test-dir $SL_TESTS_PATH
      # Run Playwright E2E
      - name: Run Playwright
        run: npx playwright:e2e

✅ Coverage data and test results are uploaded automatically to your SeaLights dashboard.

Advanced Options

For advanced use cases, refer to 👉 Advanced Options on npm, including:

• Manual integration
• Supported and Unsupported styles
• Error handling
• Implementation details

Common Plugin Parameters

Environment Variable	Required	Description
SL_TEST_STAGE	✅	Name of the test stage (“Unit”, “Integration”, etc.)
SL_TOKEN or SL_TOKENFILE	✅	Authentication token or Path to file containing the token (by default sltoken.txt)
SL_BUILD_SESSION_ID or SL_BUILD_SESSION_ID_FILE	✅	Build Session ID or Path to file containing the Build Session ID (by default buildSessionId). (Optional if SL_LABID is provided)
SL_LAB_ID	Optional	Lab ID used to group results
SL_PROXY	Optional	Proxy configuration (host:port or URL)
SL_TEST_PROJECT_ID	Optional	Identifier for the current test project
SL_TARGET_TEST_PROJECT_ID	Optional	Target test-project ID (for PR builds / TGA model)
SL_COLLECTOR_URL	Optional	URL for the Sealights HTTP Collector
SL_TIA_DISABLED	Optional	Boolean flag to disable TIA recommendations and test skipping (defaults to false).
SL_DISABLE	Optional	Boolean to disable the plugin entirely to keep the fixtures in place, but do not receive errors from the plugin due to missing configuration. (Default: false).