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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-testing-plugins/playwright-js-framework.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.