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:

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_BUILD_SESSION_ID: Unique identifier for the build session.
• SL_TOKEN: Authentication token for Sealights.
• SL_TEST_STAGE: Current testing stage (e.g., e2e, development, prod).

Optional Variables

• SL_LAB_ID: Identifier for the lab environment (optional).
• 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).

Plugin Usage

To use the Sealights Playwright Plugin, follow these steps:

1. Import the Plugin in your test files:

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

   or

   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:

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

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

Error Handling

If any required environment variable is missing, 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.

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:

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

• Single Require Statement without Test Import:

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

• Single Import Statement with Test Import:

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

• Single Import Statement without Test Import:

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

• Named Imports with Destructuring in Require:

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

• Named Imports with Destructuring in Import:

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

• Mixed Imports and Requires:

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

• Complex Destructuring in Require with Non-Test Imports:

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

• Complex Destructuring in Import with Non-Test Imports:

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

• Require with Renamed Import:

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

• Import with Renamed Import:

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

• Multiple Requires and Imports:

  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:

  const { test } = require('sealights-playwright-plugin');
  import { test as renamedTest } from 'sealights-playwright-plugin';

Unsupported Styles:

• Default Imports:

  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:

   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.