Test Design Mapping

Test Design mapping connects your qTest Test Design folder structure to SeaLights test stage names. It is the primary mechanism the tool uses to determine which SeaLights test stage a test execution belongs to.

Why It Matters

SeaLights organizes test coverage data by test stage — a named grouping like "Regression", "E2E Tests", or "Component Tests". When test executions are reported from qTest, each execution must be assigned to a test stage so SeaLights can associate it with the right coverage data and generate Test Optimization recommendations correctly.

Without a correct mapping, test executions may be reported to the wrong stage, or not reported at all.

How It Works

Your qTest Test Design folder tree has a structure like:

Test Design
└── Regression Testing          ← Root module
    ├── Component Tests         ← Mapped → "Component Tests" stage
    ├── E2E Tests               ← Mapped → "E2E Tests" stage
    └── API Tests               ← Mapped → "API Tests" stage

During setup, you select the root module ("Regression Testing" in the example above). The tool maps each direct child folder as a separate SeaLights test stage. When a test execution is found in qTest, the tool walks the test's ancestry in the Test Design tree to find the mapped folder and assign the correct stage name.

Mapped vs. Unmapped Tests

The report command separates output into two folders:

Folder	Description
output/mapped/	Tests whose stage was resolved via Test Design mapping
output/unmapped/	Tests whose stage was resolved via testStageMapping path fallback, or not resolved at all

Aim to keep the unmapped count as low as possible. Mapped tests produce more accurate and reliable SeaLights reports.

Configuration

Test Design mapping is stored in config.json under testDesignMapping:

{
  "testDesignMapping": {
    "mappedModules": {
      "1234567": {
        "name": "Component Tests",
        "slTestStage": "Component Tests",
        "parentPath": ["Regression Testing"],
        "includeSubtree": true
      },
      "1234568": {
        "name": "E2E Tests",
        "slTestStage": "E2E Tests",
        "parentPath": ["Regression Testing"],
        "includeSubtree": true
      }
    }
  }
}

The keys in mappedModules are the numeric qTest module IDs. The slTestStage value is the SeaLights test stage name that executions in this module will be reported under.

Updating the Mapping

If test case folders have moved in qTest, rebuild the cache to pick up the new structure:

npm run build-cache

If new test stage folders have been added, re-run the setup wizard to add them to the mapping:

npm run setup

Re-running setup preserves your existing mappings and only adds new ones.

testStageMapping Fallback

For tests that do not match any entry in testDesignMapping, the tool falls back to testStageMapping, which maps the test's qTest path string directly to a stage name:

{
  "testStageMapping": {
    "MyProject / Legacy Regression": "Legacy Regression"
  }
}

Tests that match neither mapping are reported using their raw qTest path as the stage name, and appear in the unmapped/ output folder.