Test Tenant Management System (TMS) Integration#

The Test Tenant Management System (TMS) integration allows you to manage test scenarios and user authentication in a centralized way. This page explains how to configure and use TMS with Playwright tests.

Overview#

TMS integration is provided by the @paeng/playwright-tms package and helps you:

  • Define scenarios with specific environments and regions

  • Manage multiple user accounts for testing

  • Handle authentication automatically

  • Access scenario details in your tests

Key Benefits#

  • Secure authentication - No hardcoded credentials

  • Scenario-based testing - Different users for different scenarios

  • Consistent configuration - Standardized across teams

  • Environment management - Easy switching between environments

Configuration#

TMS integration adds a tms section to your config.json file which defines your scenarios:

{
  "tms": [
    {
      "name": "<Name of your scenario, this should be unique>",
      "env": "<The environment of your scenario e.g. test, prod, etc. >",
      "region": "<The region of your scenario e.g. wus, eus >",
      "cluster": "<The cluster number of your scenario as a string e.g. 201>",
      "serviceTreeId": "<Your service tree id>",
      "scenarioId": "<The scenario id>",
      "defaultAlias": "<The default user to authenticate tests with>",
      "userScenarios": [
        {
          "alias": "<An alias for the user associated with the scenario>",
          "scenarioId": "<The scenario id of a scenario that provides a user>"
        }
      ]
    }
  ]
}

For detailed information on configuring TMS scenarios, including best practices and troubleshooting tips, see the TMS Scenarios Configuration page.

Example Configuration#

Here’s a sample configuration for a PowerApps maker scenario:

{
  "tms": [
    {
      "name": "PowerAppsMaker",
      "env": "test",
      "region": "wus",
      "cluster": "201",
      "serviceTreeId": "12345",
      "scenarioId": "67890",
      "defaultAlias": "MakerUser",
      "userScenarios": [
        {
          "alias": "AdminUser",
          "scenarioId": "54321"
        }
      ]
    }
  ]
}

Authentication Flow#

  1. Set the TMS_SCENARIO environment variable to your scenario name

  2. Run npm run login-tms to authenticate with TMS

  3. The TMS fixture provides authentication tokens in tests

export TMS_SCENARIO=PowerAppsMaker
npm run login-tms

TMS Test Fixture#

To use TMS details in your tests, you need to use the test method provided by @paeng/playwright-tms. The fixture gives you access to scenario information and user details during test execution.

Basic Usage#

import { test } from "@paeng/playwright-tms";

test("My TMS test", async ({ page, tms }) => {
  console.log("TMS scenario:", tms.scenario);
  console.log("TMS user:", tms.user);

  // Run your test using TMS information
  // ...
});

Merging with Existing Test Fixtures#

If your tests already use custom fixtures, you’ll need to merge them using the mergeTests method:

import { test as baseTest } from "@playwright/test";
import { test as tmsTest } from "@paeng/playwright-tms";
import { mergeTests } from "@playwright/test";

// Merge your base test with TMS test
const test = mergeTests(baseTest, tmsTest);

test("Test with merged fixtures", async ({ page, tms, myCustomFixture }) => {
  // Use both TMS and your custom fixtures
});

Using with Integration Test Wrapper#

If you are using the integrationTest function provided by @paeng/playwright-solution, you’ll need to switch to the version provided in src/utils/integrationTest.ts as the existing function doesn’t support custom fixtures.

Key Differences#

The new version of integrationTest wraps several tests with the same environment configuration, while the old version wrapped individual tests directly:

// Old approach
integrationTest(config, owner, title1, async ({ page }) => {});
integrationTest(config, owner, title2, async ({ page }) => {});

// New approach with TMS
integrationTest(config, owner, (format) => {
  test(format(title1), async ({ page, tms }) => {});
  test(format(title2), async ({ page, tms }) => {});
});

Note that with the new approach:

  1. You receive a format function to apply to test titles

  2. You need to manually format each test title

  3. You can add multiple test cases with the same configuration

  4. You have access to the tms fixture in each test

Adding Playwright Global for Compatibility#

If your tests depend on the window.__PLAYWRIGHT__ global being defined (which was added by the old wrapper), you can re-add it:

import {
  integrationTest,
  addPlaywrightGlobal,
} from "src/utils/integrationTest";

test.beforeEach("Add __PLAYWRIGHT__ global", async ({ context }) => {
  await addPlaywrightGlobal(context);
});

Running TMS Tests Locally#

To use TMS locally, follow these steps:

  1. Set the TMS_SCENARIO environment variable to your scenario name from config.json:

# Windows
set TMS_SCENARIO=PowerAppsMaker

# Linux/macOS
export TMS_SCENARIO=PowerAppsMaker

# Or add to your .env file
echo "TMS_SCENARIO=PowerAppsMaker" >> .env

  1. Run the login script to authenticate all users specified in the scenario:

npm run login-tms

  1. Run your tests:

npm run int-test

Running TMS Tests in Pipeline#

To run your TMS tests in a pipeline:

  1. Update your pipeline to call run-playwright-tests.yml

  2. Specify your scenario name with the tmsScenario parameter:

parameters:
  - name: tmsScenario
    displayName: TMS Scenario Name
    type: string
    default: PowerAppsMaker

Best Practices#

  1. Separate user roles: Define different users for different roles (admin, regular user, etc.)

  2. Reuse scenarios: Use the same scenario across related tests

  3. Environment variables: Store sensitive values in environment variables, not in the config

  4. Unique scenario names: Use descriptive, unique names for your scenarios

  5. Clear user aliases: Use clear, descriptive aliases that indicate the user’s role

Common Issues and Solutions#

Issue

Solution

Authentication failure

Run npm run login-tms to refresh tokens

Missing scenario

Verify TMS_SCENARIO matches a name in config.json

User not found

Check userScenarios array in your TMS configuration

Next Steps#

See TMS Scenarios Configuration for details on creating and configuring your own TMS scenarios.