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

$3

To install the plugin, use npm:

``bash
npm install sealights-playwright-plugin
`

$3

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_PR_ID - Identifies PR pipeline executions, allowing them to be distinguished from eachother and from other executions of the same test-stage.

$3

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.

$3

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
});
`

$3

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.

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 for further details.

---

$3

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 using npx with the replace-imports command and specify the path to your test folder:

`bash
npx sealights-playwright-plugin replace-imports --test-dir
`

Replace with the relative or absolute path to the directory where your Playwright tests are located.

Example:

`bash
npx sealights-playwright-plugin replace-imports --test-dir ./tests
`

Command Aliases:

The replace-imports command has the following aliases that can be used interchangeably:
- rewrite-imports
- update-imports
- adapt-imports

Example using an alias:

`bash
npx sealights-playwright-plugin rewrite-imports --test-dir ./tests
`

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

---