Configuring TMS Scenarios#

Test Management System (TMS) scenarios provide a way to configure test environments and user accounts for enterprise-level testing. This page explains how to configure and use TMS scenarios in your Playwright tests.

Understanding TMS Scenarios#

TMS scenarios define test environments with specific characteristics:

  • Environment type (test, prod, etc.)

  • Region (wus, eus, etc.)

  • Cluster information

  • Service associations

  • User accounts with specific permissions

Each scenario has a unique identifier and can include multiple user accounts, making it easy to test different user roles within the same environment.

Basic Scenario Structure#

A TMS scenario is defined in the config.json file under the tms section:

{
  "name": "scenario-name",
  "type": "cm",
  "env": "test",
  "region": "wus",
  "cluster": "201",
  "serviceTreeId": "service-tree-id",
  "scenarioId": "unique-scenario-id",
  "defaultAlias": "default-user-alias",
  "userScenarios": [
    {
      "alias": "user1-alias",
      "scenarioId": "user1-scenario-id"
    },
    {
      "alias": "user2-alias",
      "scenarioId": "user2-scenario-id"
    }
  ]
}

Key Components of a TMS Scenario#

1. Scenario Identification#

  • name: A human-readable identifier for the scenario

  • scenarioId: A unique GUID that identifies the scenario in the TMS system

2. Environment Details#

  • type: The type of environment (e.g., “cm” for Common Management, “il” for Isolated)

  • env: Environment tier (test, prod, etc.)

  • region: Geographical location (wus = West US, eus = East US, etc.)

  • cluster: Cluster number as a string (e.g., “001”, “201”)

3. Service Association#

  • serviceTreeId: Links the scenario to a specific service in the service tree

4. User Management#

  • defaultAlias: The default user account alias to use for this scenario

  • userScenarios: Array of additional user accounts with their own scenario IDs

Example Scenarios#

Test Environment Scenario#

{
  "name": "playwright-test-harness-wus-test-env",
  "type": "cm",
  "env": "test",
  "region": "wus",
  "cluster": "201",
  "serviceTreeId": "7fcfe381-9d31-4f8f-97b1-20596783029e",
  "scenarioId": "2a4eaccf-3819-4d2d-a725-f1b2f437ea86",
  "defaultAlias": "admin",
  "userScenarios": [
    {
      "alias": "admin",
      "scenarioId": "2a4eaccf-3819-4d2d-a725-f1b2f437ea86"
    }
  ]
}

Production Environment Scenario#

{
  "name": "playwright-app-runtime-wus-prod-env",
  "env": "prod",
  "region": "wus",
  "cluster": "001",
  "serviceTreeId": "3178d812-dac9-43e4-ba8b-53f29e921603",
  "scenarioId": "a9dbc155-f511-4213-ada3-8454df91b86f",
  "defaultAlias": "aurorauser04",
  "userScenarios": [
    {
      "alias": "aurorauser04",
      "scenarioId": "a9dbc155-f511-4213-ada3-8454df91b86f"
    }
  ]
}

Multi-User Scenario#

{
  "name": "portal-power-pages-nightly-test",
  "type": "cm",
  "env": "test",
  "region": "wus",
  "cluster": "201",
  "serviceTreeId": "8df68507-d113-4c57-a123-4ed590788b96",
  "scenarioId": "4ab9543a-716c-4e85-bdca-34ae002a59c5",
  "defaultAlias": "aurorauser04",
  "userScenarios": [
    {
      "alias": "aurorauser04",
      "scenarioId": "4ab9543a-716c-4e85-bdca-34ae002a59c5"
    },
    {
      "alias": "user2",
      "scenarioId": "3ab9543a-716c-4e85-bdca-34ae002a58d6"
    }
  ]
}

Setting Up a New TMS Scenario#

To create a new TMS scenario:

  1. Obtain scenario identifiers:

    • Generate a unique GUID for the scenarioId

    • Get your service’s serviceTreeId from the service tree

  2. Select environment details:

    • Determine environment type, region, and cluster

    • Choose appropriate user accounts

  3. Add to config.json:

    • Add your scenario to the tms array in config.json

  4. Register with TMS service:

    • Work with the TMS team to register your scenario IDs

    • Ensure user accounts have appropriate permissions

Using TMS Scenarios in Tests#

To use TMS scenarios in your tests, you’ll use the TMS integration:

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

test("My test with TMS scenario", async ({ page, tms }) => {
  // tms.scenario contains information about the scenario
  console.log("Using scenario:", tms.scenario.name);

  // tms.user contains information about the current user
  console.log("Logged in as:", tms.user.alias);

  // Your test code here
});

Running Tests with Specific TMS Scenarios#

To run tests with a specific TMS scenario, set the TMS_SCENARIO environment variable:

# Set the scenario name
export TMS_SCENARIO=playwright-test-harness-wus-test-env

# Authenticate all users in the scenario
npm run login-tms

# Run your tests
npm run int-test

TMS Scenario Best Practices#

  1. Naming conventions:

    • Use descriptive names that include environment type, region, and purpose

    • Example: service-name-region-env-type

  2. User management:

    • Create different user accounts for different roles

    • Include at least one admin user and one regular user for role-based testing

  3. Scenario organization:

    • Group related scenarios together in the config file

    • Add comments to explain purpose and usage

  4. Maintenance:

    • Regularly review and clean up unused scenarios

    • Update documentation when scenarios change

  5. Security:

    • Never commit sensitive scenario details directly to source control

    • Use secure methods to store and retrieve scenario credentials

  6. Reusability:

    • Design scenarios to be reusable across multiple test suites

    • Avoid creating scenario-specific tests that can’t be reused

Troubleshooting TMS Scenarios#

Common Issues#

  1. Authentication failures:

    • Verify that the scenario ID is correct

    • Check that the user account has the necessary permissions

    • Run npm run login-tms to refresh authentication

  2. Environment access problems:

    • Confirm the environment is available and accessible

    • Check that the service tree ID is correctly associated with your service

  3. User scenario not found:

    • Verify that the user alias matches an entry in the userScenarios array

    • Check that the user scenario ID is registered with TMS

Diagnostic Steps#

  1. Enable TMS debug logging:

    export TMS_DEBUG=true
npm run login-tms

  2. Verify scenario configuration:

    npx playwright-tms verify-scenario --name "scenario-name"

  3. Check authentication state:

    npx playwright-tms auth-status

Additional Resources#