{"id":18069,"library":"testit-adapter-playwright","title":"Test IT Playwright Adapter","description":"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.","status":"active","version":"4.0.2-TMS-5.7","language":"javascript","source_language":"en","source_url":"https://github.com/testit-tms/adapters-js","tags":["javascript","typescript"],"install":[{"cmd":"npm install testit-adapter-playwright","lang":"bash","label":"npm"},{"cmd":"yarn add testit-adapter-playwright","lang":"bash","label":"yarn"},{"cmd":"pnpm add testit-adapter-playwright","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is an adapter for the Playwright test automation framework and requires Playwright to be installed as a peer dependency.","package":"playwright","optional":false},{"reason":"The adapter re-exports decorators (like externalId, attachment, link) from this package, which are crucial for enhancing test metadata within Playwright.","package":"@testit/decorators","optional":false}],"imports":[{"note":"Used in `playwright.config.ts` to register the Test IT reporter. Incorrect CommonJS `require` syntax is a common mistake in ESM-first Playwright projects.","wrong":"const { TestITReporter } = require('testit-adapter-playwright/reporter');","symbol":"TestITReporter","correct":"import { TestITReporter } from 'testit-adapter-playwright/reporter';"},{"note":"Re-exported directly from `testit-adapter-playwright` for convenience. Used as a test decorator to map Playwright tests to specific Test IT work items.","wrong":"import { externalId } from '@testit/decorators';","symbol":"externalId","correct":"import { test, externalId } from 'testit-adapter-playwright';"},{"note":"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).","wrong":"import { addAttachments } from 'testit-adapter-playwright';","symbol":"attachment","correct":"import { test, attachment } from 'testit-adapter-playwright';"},{"note":"Re-exported enum from `@testit/decorators` for specifying link types (e.g., related, blocked-by) when using the `link` decorator or `addLinks` function.","symbol":"LinkType","correct":"import { LinkType } from 'testit-adapter-playwright';"}],"quickstart":{"code":"import { defineConfig, devices } from '@playwright/test';\nimport { TestITReporter } from 'testit-adapter-playwright/reporter';\n\nexport default defineConfig({\n  testDir: './tests',\n  fullyParallel: true,\n  forbidOnly: !!process.env.CI,\n  retries: process.env.CI ? 2 : 0,\n  workers: process.env.CI ? 1 : undefined,\n  reporter: [[TestITReporter, {\n    url: process.env.TMS_URL ?? '',\n    privateToken: process.env.TMS_PRIVATE_TOKEN ?? '',\n    projectId: process.env.TMS_PROJECT_ID ?? '',\n    configurationId: process.env.TMS_CONFIGURATION_ID ?? '',\n    testRunName: process.env.TMS_TEST_RUN_NAME ?? 'Playwright Test Run ' + new Date().toISOString(),\n    adapterMode: 1 // 1: Use existing test run ID, create if not provided; 2: Create new test run\n  }], 'html'],\n\n  use: {\n    trace: 'on-first-retry',\n  },\n\n  projects: [\n    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },\n  ],\n});\n\n// tests/example.spec.ts\nimport { test, expect, externalId, attachment } from 'testit-adapter-playwright';\nimport path from 'path';\nimport fs from 'fs';\n\ntest.describe('Example Test IT Integration', () => {\n  externalId('TMS-1234', 'Verify basic page load');\n  test('should navigate to example.com and take a screenshot', async ({ page }) => {\n    await page.goto('https://www.example.com');\n    await expect(page).toHaveTitle(/Example Domain/);\n\n    const screenshotPath = path.join(__dirname, 'screenshot.png');\n    await page.screenshot({ path: screenshotPath });\n    attachment('Page Load Screenshot', screenshotPath);\n    \n    // Clean up created file\n    fs.unlinkSync(screenshotPath);\n  });\n\n  externalId('TMS-5678', 'Check heading text');\n  test('should verify heading text', async ({ page }) => {\n    await page.goto('https://www.example.com');\n    await expect(page.locator('h1')).toHaveText('Example Domain');\n  });\n});\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.7.1-TMS-5.6"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Set the `TMS_URL` environment variable or provide `url` in the `TestITReporter` options in `playwright.config.ts`.","cause":"The adapter was initialized without the necessary Test IT instance URL.","error":"Error: Missing required configuration: TMS_URL. Please provide it via config file or environment variable TMS_URL."},{"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.","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.","error":"TypeError: TestITReporter is not a constructor"},{"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).","cause":"If `adapterMode` is 1 and `testRunId` is provided, but no existing test run matches that ID in Test IT.","error":"Error: Test run with ID '...' not found in 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.","cause":"Problems with network connectivity, incorrect API token, insufficient permissions, or an invalid file path preventing attachment upload to Test IT.","error":"Error: Failed to upload attachment '...' - [Network Error / API Error]"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}