Skip to main content

Playwright Integration

Run your Playwright tests as usual and have results, screenshots, and traces automatically reported to TMS.

Install​

The SDK is published only on the ProvaLab registry. It is not on npmjs.com, so a plain npm install tms-node-sdk would resolve against the public registry, where the name is unclaimed. Install it from the tarball:

npm install https://plugins.provalab.io/packages/tms-node-sdk-2.1.0.tgz

Or from the ProvaLab npm registry (the SDK has no runtime dependencies, so scoping the registry to this command is safe):

npm install tms-node-sdk --registry https://plugins.provalab.io/npm/

Check the plugin catalogue for the latest version.

Requirements: Node.js >= 18.0.0, Playwright >= 1.30.0

Configure​

1. Set environment variables​

export TMS_API_KEY=your-api-key
export TMS_API_URL=https://tms.yourcompany.com
export TMS_ORGANIZATION_ID=1
export TMS_PROJECT_ID=12

Or create a .env file in your project root:

.env
TMS_API_KEY=your-api-key
TMS_API_URL=https://tms.yourcompany.com
TMS_ORGANIZATION_ID=1
TMS_PROJECT_ID=12
TMS_ENVIRONMENT=staging

2. Add the TMS reporter to your Playwright config​

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  reporter: [
    ['list'],                                // Keep the default console output
    ['tms-node-sdk/playwright/reporter'],    // Add TMS reporting
  ],
  use: {
    screenshot: 'only-on-failure',           // TMS auto-uploads failure screenshots
    trace: 'on-first-retry',
  },
});

That's it. Every time you run tests, results go to TMS automatically.

Run​

npx playwright test

You'll see TMS output alongside Playwright's normal output:

========================================
  TMS Playwright Integration
========================================
  Test Run ID: 847
  Project ID: 12
  Organization ID: 1
  Tests discovered: 15
========================================

    [PASS] should display homepage (1.24s)
    [PASS] should navigate to login (0.89s)
    [FAIL] should submit contact form (2.31s)

========================================
  TMS Test Run Summary
========================================
  Test Run ID: 847
  Total:   3
  Passed:  2
  Failed:  1
  Skipped: 0
  Status:  FAILED
========================================

View Results in TMS​

  1. Open TMS and go to your project
  2. Click Test Runs in the sidebar
  3. Find the run named "Playwright: 2026-02-20 14:30:00" (or your custom name)
  4. Click into it to see individual test results, screenshots, and logs

Option 1: Include the ID in the test title​

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

test('[TMS-101] should display login page', async ({ page }) => {
  await page.goto('/login');
  await expect(page.locator('h1')).toHaveText('Login');
});

test('[TMS-102] should login with valid credentials', async ({ page }) => {
  await page.goto('/login');
  await page.fill('#email', '[email protected]');
  await page.fill('#password', 'password123');
  await page.click('button[type="submit"]');
  await expect(page).toHaveURL('/dashboard');
});

Option 2: Use a mapping file​

Create test-case-mapping.json in your project root:

test-case-mapping.json
{
  "should display login page": { "id": 101, "priority": "high", "type": "smoke" },
  "should login with valid credentials": { "id": 102, "priority": "critical", "type": "e2e" }
}

Then set the environment variable:

export TMS_MAPPING_FILE=test-case-mapping.json

Advanced Configuration​

Custom test run name​

export TMS_TEST_RUN_NAME="Nightly E2E - Chrome"

Screenshot on failure​

Playwright's built-in screenshot capture works seamlessly with TMS. When a test fails and has a screenshot attachment, TMS uploads it automatically.

playwright.config.ts
export default defineConfig({
  use: {
    screenshot: 'only-on-failure',  // TMS will upload these automatically
    video: 'retain-on-failure',
    trace: 'on-first-retry',
  },
  reporter: [
    ['list'],
    ['tms-node-sdk/playwright/reporter'],
  ],
});

Disable TMS for local development​

export TMS_DISABLED=true
npx playwright test

The reporter gracefully skips all TMS operations when disabled.

Retry and timeout settings​

export TMS_REQUEST_TIMEOUT_MS=30000   # HTTP request timeout (default: 30s)
export TMS_MAX_RETRIES=3              # Retry failed API calls (default: 3)
Circuit breaker protection

The SDK includes a circuit breaker that temporarily stops sending requests to TMS if the API is unreachable. Your tests keep running normally -- TMS reporting resumes automatically when the API recovers. After 5 consecutive failures, the circuit opens for 30 seconds before retrying.

QA Infrastructure (Remote Browsers)​

If your organization uses TMS QA Infrastructure for remote browser sessions, the Playwright reporter can automatically provision browsers:

export QA_INFRA_URL=https://qa-infra.yourcompany.com
export QA_INFRA_API_KEY=your-infra-key

When configured, each test gets a dedicated remote browser session with video recording and VNC streaming.

Verify It Works​

  1. Set your environment variables
  2. Create a simple test:
tests/tms-verify.spec.ts
import { test, expect } from '@playwright/test';

test('[TMS-1] verify TMS integration', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveTitle(/Example/);
});
  1. Run it:
npx playwright test tests/tms-verify.spec.ts
  1. Check the console output for the TMS banner with a Test Run ID
  2. Open TMS and confirm the test run appears under your project
Common issues
  • "Not configured" message: Make sure TMS_API_KEY, TMS_ORGANIZATION_ID, and TMS_PROJECT_ID are all set
  • "Failed to create test run": Verify your API key is valid and has write access to the project
  • Results not appearing: Check that TMS_API_URL points to your TMS instance (not localhost unless running locally)