Test IT Playwright Adapter

4.0.2-TMS-5.7 verified Sat Apr 25 auth: no javascript

The `testit-adapter-playwright` package provides a robust integration layer between the Playwright test automation framework and the Test IT Test Management System (TMS). It automates the process of publishing test results, logs, and attachments from Playwright test runs directly into a Test IT instance. The current stable version is `4.0.2-TMS-5.7`, with parallel releases like `4.0.2` for different TMS versions, indicating an active development and maintenance cadence. Key differentiators include seamless mapping of Playwright tests to TMS work items using decorators like `externalId`, automatic reporting of test statuses (passed, failed, skipped), and the ability to attach rich media (screenshots, videos, logs) directly from Playwright's capabilities. It allows for flexible configuration via environment variables or a Playwright configuration file, supporting various adapter modes for managing test runs within TMS.

Common errors

error Error: Missing required configuration: TMS_URL. Please provide it via config file or environment variable TMS_URL. ↓

cause The adapter was initialized without the necessary Test IT instance URL.

fix

Set the TMS_URL environment variable or provide url in the TestITReporter options in playwright.config.ts.

error TypeError: TestITReporter is not a constructor ↓

cause This error typically occurs when attempting to use CommonJS `require()` syntax with an ESM-only or ESM-preferred package, or if the import path is incorrect in a TypeScript/ESM context.

fix

Ensure you are using import { TestITReporter } from 'testit-adapter-playwright/reporter'; in a TypeScript or ESM file (e.g., playwright.config.ts), and that your project is configured for ESM.

error Error: Test run with ID '...' not found in Test IT. ↓

cause If `adapterMode` is 1 and `testRunId` is provided, but no existing test run matches that ID in Test IT.

fix

Verify the TMS_TEST_RUN_ID environment variable or the testRunId option in TestITReporter is correct and corresponds to an active test run in your Test IT instance. Alternatively, omit testRunId to allow the adapter to create a new one (if adapterMode 1 is configured to do so).

error Error: Failed to upload attachment '...' - [Network Error / API Error] ↓

cause Problems with network connectivity, incorrect API token, insufficient permissions, or an invalid file path preventing attachment upload to Test IT.

fix

Check network connection to the Test IT instance. Verify TMS_PRIVATE_TOKEN is correct and has necessary permissions. Ensure the file path provided to attachment decorator/function is valid and accessible by the test runner process.

Warnings

breaking Version 4.0.0 introduced significant changes, including 'sync-storage' and adapter hardening features. While no explicit breaking API changes were detailed, it may alter behavior related to how test run data is synchronized and managed, potentially requiring updates to existing automation setups. ↓

fix Review the official changelog for specific behavioral changes. Test existing workflows thoroughly after upgrading to identify any regressions or altered synchronization logic. Pay close attention to `adapterMode` configuration.

gotcha Sensitive configuration values like `privateToken` should always be handled securely, preferably via environment variables (`TMS_PRIVATE_TOKEN`) rather than hardcoding them directly in `playwright.config.ts`. Exposing these in source control can lead to security vulnerabilities. ↓

fix Utilize environment variables (e.g., `process.env.TMS_PRIVATE_TOKEN`) and ensure they are properly set in your CI/CD pipelines and local development environments. Refer to the 'Configuration' section in the README for available environment variables.

gotcha The package versioning often includes a `-TMS-X.Y` suffix (e.g., `4.0.2-TMS-5.7`), indicating compatibility with a specific Test IT TMS version. Using an adapter version incompatible with your TMS instance can lead to reporting errors or unexpected behavior. ↓

fix Always check the release notes and ensure the `testit-adapter-playwright` version you install is compatible with your Test IT TMS instance version. Refer to the Test IT documentation for compatibility matrices.

gotcha Incorrect or missing Playwright configuration for the reporter, especially the `reporter` array format, can lead to the adapter not being initialized or reporting failures. Ensure `TestITReporter` is correctly passed with its options. ↓

fix Verify that `reporter: [[TestITReporter, {...options}], 'html']` or similar is correctly configured in your `playwright.config.ts` file, and that all required options (url, privateToken, projectId, configurationId) are provided and valid.

Install

npm install testit-adapter-playwright

yarn add testit-adapter-playwright

pnpm add testit-adapter-playwright

Imports

TestITReporter
wrong
```
const { TestITReporter } = require('testit-adapter-playwright/reporter');
```
correct
```
import { TestITReporter } from 'testit-adapter-playwright/reporter';
```
Used in `playwright.config.ts` to register the Test IT reporter. Incorrect CommonJS `require` syntax is a common mistake in ESM-first Playwright projects.
externalId
wrong
```
import { externalId } from '@testit/decorators';
```
correct
```
import { test, externalId } from 'testit-adapter-playwright';
```
Re-exported directly from `testit-adapter-playwright` for convenience. Used as a test decorator to map Playwright tests to specific Test IT work items.
attachment
wrong
```
import { addAttachments } from 'testit-adapter-playwright';
```
correct
```
import { test, attachment } from 'testit-adapter-playwright';
```
Re-exported from `@testit/decorators`. The `attachment` decorator is preferred for associating files with tests, rather than the `addAttachments` function (which is also available but less idiomatic for direct test context).
LinkType
```
import { LinkType } from 'testit-adapter-playwright';
```
Re-exported enum from `@testit/decorators` for specifying link types (e.g., related, blocked-by) when using the `link` decorator or `addLinks` function.

Quickstart

This quickstart demonstrates configuring the `testit-adapter-playwright` in `playwright.config.ts` using environment variables for TMS credentials, and a basic Playwright test file showcasing `externalId` and `attachment` decorators for reporting results and artifacts to Test IT.

import { defineConfig, devices } from '@playwright/test';
import { TestITReporter } from 'testit-adapter-playwright/reporter';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [[TestITReporter, {
    url: process.env.TMS_URL ?? '',
    privateToken: process.env.TMS_PRIVATE_TOKEN ?? '',
    projectId: process.env.TMS_PROJECT_ID ?? '',
    configurationId: process.env.TMS_CONFIGURATION_ID ?? '',
    testRunName: process.env.TMS_TEST_RUN_NAME ?? 'Playwright Test Run ' + new Date().toISOString(),
    adapterMode: 1 // 1: Use existing test run ID, create if not provided; 2: Create new test run
  }], 'html'],

  use: {
    trace: 'on-first-retry',
  },

  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],
});

// tests/example.spec.ts
import { test, expect, externalId, attachment } from 'testit-adapter-playwright';
import path from 'path';
import fs from 'fs';

test.describe('Example Test IT Integration', () => {
  externalId('TMS-1234', 'Verify basic page load');
  test('should navigate to example.com and take a screenshot', async ({ page }) => {
    await page.goto('https://www.example.com');
    await expect(page).toHaveTitle(/Example Domain/);

    const screenshotPath = path.join(__dirname, 'screenshot.png');
    await page.screenshot({ path: screenshotPath });
    attachment('Page Load Screenshot', screenshotPath);
    
    // Clean up created file
    fs.unlinkSync(screenshotPath);
  });

  externalId('TMS-5678', 'Check heading text');
  test('should verify heading text', async ({ page }) => {
    await page.goto('https://www.example.com');
    await expect(page.locator('h1')).toHaveText('Example Domain');
  });
});