sealights-playwright-plugin/README.md

Playwright plugin for Sealights integration.

# Sealights Playwright Plugin

## Overview

The Sealights Playwright Plugin integrates Sealights' test intelligence into Playwright tests, providing developers with insights about the tests and coverage tracking, as well as tests skipping using Sealights' TIA. This document guides developers through installation, configuration, and usage to enhance test quality and efficiency.

## Getting Started

### Installation

To install the plugin, use npm:

```bash
npm install sealights-playwright-plugin
```

### Environment Variables Setup

The plugin requires several environment variables for configuration. Here’s a breakdown of each variable:

#### Required Variables

- **SL_TOKEN**: Agent token for Sealights.
- **SL_TEST_STAGE**: Current testing stage (e.g., e2e, development, prod).
- **Either SL_BUILD_SESSION_ID or SL_LAB_ID**:
  - **SL_BUILD_SESSION_ID**: Unique identifier for the build session.
  - **SL_LAB_ID**: Identifier for the lab environment. If only `SL_LAB_ID` is provided, the build session id will be resolved automatically by the backend at runtime.

#### Optional Variables

- **SL_PROXY**: Proxy settings (optional).
- **SL_COLLECTOR_URL**: URL for the data collector (optional).
- **SL_TIA_DISABLED**: Boolean flag to disable TIA recommendations and test skipping (optional; defaults to `false`).
- **SL_DISABLE**: Disable the plugin entirely to keep the fixtures in place but not receive errors from the plugin due to missing configuration (optional).
- **SL_TEST_PROJECT_ID** - Test project ID differentiates between different test stages with the same test stage name of different teams/products/etc.
- **SL_TARGET_TEST_PROJECT_ID** - Test project ID to set for PR builds. The target test-project-id will be used to the statistical-model used for recommendations.

### Plugin Usage

To use the Sealights Playwright Plugin, follow these steps:

1. **Import the Plugin** in your test files:

   ```javascript
   const { test } = require('sealights-playwright-plugin');
   ```

   or

   ```javascript
   import { test } from 'sealights-playwright-plugin';
   ```

   Replace your existing test fixture with this import in all your test files where you want Sealights integration.

2. **Configure the Plugin** using the environment variables. You can do this in your test setup or CI/CD environment.

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

### Example Test File

Here’s a basic example of how to structure a test file using the Sealights Playwright Plugin:

```javascript
const { test } = require('sealights-playwright-plugin');

test('my test', async ({ page }) => {
  // Your test logic here
});
```

### Error Handling

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.

---

## Implementation

The Sealights Playwright Plugin is implemented using **Playwright fixtures**, which are the recommended way to register global hooks for each worker and test. This approach ensures that setup and teardown logic is run consistently across tests, and it integrates with Playwright’s built-in hooks like `beforeEach` and `afterEach`.

Using fixtures allows us to efficiently integrate Sealights' test intelligence features while maintaining test stability and execution speed. For more details on how Playwright fixtures work, you can refer to the official Playwright documentation on [adding global `beforeEach`/`afterEach` hooks](https://playwright.dev/docs/test-fixtures#adding-global-beforeeachaftereach-hooks).

## Minimal System Requirements

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

- **Node.js**: Version 18 or higher.
- **Playwright**: Version 1.20 or higher.

Please make sure your system meets these requirements before using the plugin. You can refer to the [Playwright system requirements](https://playwright.dev/docs/intro#system-requirements) for further details.

---

### Optional: Using the Import Replacement Utility

To simplify the integration process, you can use our utility script to automatically replace your existing imports from `@playwright/test` with imports from `sealights-playwright-plugin`. This utility script can handle the following import/require styles:

#### Supported Styles:

- **Single Destructured Require Statement with Test Import**:

  ```javascript
  const { test, expect } = require('@playwright/test');
  ```

- **Single Require Statement without Test Import**:

  ```javascript
  const { expect } = require('@playwright/test');
  ```

- **Single Import Statement with Test Import**:

  ```javascript
  import { test } from '@playwright/test';
  ```

- **Single Import Statement without Test Import**:

  ```javascript
  import { expect } from '@playwright/test';
  ```

- **Named Imports with Destructuring in Require**:

  ```javascript
  const { test, chromium } = require('@playwright/test');
  ```

- **Named Imports with Destructuring in Import**:

  ```javascript
  import { test, chromium } from '@playwright/test';
  ```

- **Mixed Imports and Requires**:

  ```javascript
  const { test, expect } = require('@playwright/test');
  import { chromium } from '@playwright/test';
  ```

- **Complex Destructuring in Require with Non-Test Imports**:

  ```javascript
  const { test, expect, firefox } = require('@playwright/test');
  ```

- **Complex Destructuring in Import with Non-Test Imports**:

  ```javascript
  import { test, expect, firefox } from '@playwright/test';
  ```

- **Require with Renamed Import**:

  ```javascript
  const { test: renamedTest } = require('@playwright/test');
  ```

- **Import with Renamed Import**:

  ```javascript
  import { test as renamedTest } from '@playwright/test';
  ```

- **Multiple Requires and Imports**:

  ```javascript
  const { test, expect } = require('@playwright/test');
  const { firefox, chromium } = require('@playwright/test');
  import { test as renamedTest } from '@playwright/test';
  import { expect } from '@playwright/test';
  ```

- **Using Sealights Playwright Plugin**:
  ```javascript
  const { test } = require('sealights-playwright-plugin');
  import { test as renamedTest } from 'sealights-playwright-plugin';
  ```

#### Unsupported Styles:

- **Default Imports**:

  ```javascript
  import test from '@playwright/test'; // Not supported
  ```

- **Unsupported Mixed Imports**:
  - Be cautious with any combination of imports that do not conform to the supported styles.

---

#### How to Use the Import Replacement Utility

To use the Import Replacement Utility for replacing imports in your project, follow these steps:

1. **Navigate to Your Project Root**: Open your terminal and navigate to the root of your project where the `node_modules` directory is located.

2. **Run the Utility**: Execute the utility script with the path to the folder containing your test files as the argument. The command should look like this:

   ```bash
   node node_modules/sealights-playwright-plugin/importReplaceUtility.js <path-to-your-test-folder>
   ```

   Replace `<path-to-your-test-folder>` with the relative or absolute path to the directory where your Playwright tests are located.

3. **Check the Output**: 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.

4. **Proceed with Caution**: Review the modified files to ensure the imports have been replaced correctly. It’s recommended to use version control (e.g., Git) to track changes and revert if necessary.

---

# Logging

Extra logs can be enabled using the following environment variable:

```shell
export NODE_DEBUG=sl
```

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

```shell
export SL_LOG_LEVEL=debug
```

---