# 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

{% stepper %}
{% step %}

#### Install the Plugin <a href="#install-the-plugin" id="install-the-plugin"></a>

To install the Sealights Playwright plugin, use npm:

```sh
npm install sealights-playwright-plugin
```

For more details, you can also refer to [https://www.npmjs.com/package/sealights-playwright-plugin](https://www.npmjs.com/package/sealights-playwright-plugin?activeTab=readme)
{% endstep %}

{% step %}

#### Set Environment Variables <a href="#set-environment-variables" id="set-environment-variables"></a>

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.

{% tabs %}
{% tab title="Unix/Linux" %}
{% code overflow="wrap" %}

```sh
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"
```

{% endcode %}
{% endtab %}

{% tab title="PowerShell" %}

```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"
```

{% endtab %}
{% endtabs %}

The build session id is resolved automatically by the backend at runtime using the `SL_LAB_ID`.
{% endstep %}

{% step %}

#### 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:

{% code overflow="wrap" %}

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

{% endcode %}

Replace `<path-to-your-test-folder>` with the relative or absolute path to the directory containing your Playwright test files.
{% endstep %}

{% step %}

#### **Run Your Tests As Usual**

Run Your Tests **as usual**. The plugin will automatically track coverage and provide insights during the test execution.
{% endstep %}
{% endstepper %}

{% hint style="success" %}
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.
{% endhint %}

## 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 <a href="#logging-and-debugging" id="logging-and-debugging"></a>

Extra logs can be enabled using the following environment variable:

```sh
export NODE_DEBUG=sl
```

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

```sh
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

{% tabs %}
{% tab title="Unix/Linux (Bash)" %}

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

{% endtab %}

{% tab title="GitHub Actions" %}

```yaml
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
```

{% endtab %}
{% endtabs %}

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

## Advanced Options

{% hint style="warning" %}
For advanced use cases, refer to 👉 [**Advanced Options on npm**](https://www.npmjs.com/package/sealights-playwright-plugin)**, including:**

* Manual integration
* Supported and Unsupported styles
* Error handling
* Implementation details
  {% endhint %}

## Common Plugin Parameters

<table><thead><tr><th width="240">Environment Variable</th><th width="99.3333740234375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>SL_TEST_STAGE</code></td><td>✅</td><td>Name of the test stage (“Unit”, “Integration”, etc.)</td></tr><tr><td><code>SL_TOKEN</code> or <code>SL_TOKENFILE</code></td><td>✅</td><td>Authentication token or Path to file containing the token (by default <code>sltoken.txt</code>)</td></tr><tr><td><code>SL_BUILD_SESSION_ID</code> or <code>SL_BUILD_SESSION_ID_FILE</code></td><td>✅</td><td>Build Session ID or Path to file containing the Build Session ID (by default <code>buildSessionId</code>). (Optional if <code>SL_LABID</code> is provided)</td></tr><tr><td><code>SL_LAB_ID</code></td><td>Optional</td><td>Lab ID used to group results</td></tr><tr><td><code>SL_PROXY</code></td><td>Optional</td><td>Proxy configuration (host:port or URL)</td></tr><tr><td><code>SL_TEST_PROJECT_ID</code></td><td>Optional</td><td>Identifier for the current test project</td></tr><tr><td><code>SL_TARGET_TEST_PROJECT_ID</code></td><td>Optional</td><td>Target test-project ID (for PR builds / TGA model)</td></tr><tr><td><code>SL_COLLECTOR_URL</code></td><td>Optional</td><td>URL for the Sealights HTTP Collector</td></tr><tr><td><code>SL_TIA_DISABLED</code></td><td>Optional</td><td>Boolean flag to disable TIA recommendations and test skipping (defaults to <code>false</code>).</td></tr><tr><td><code>SL_DISABLE</code></td><td>Optional</td><td>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).</td></tr></tbody></table>