# 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 |

{% hint style="success" %}
Aim to keep the unmapped count as low as possible. Mapped tests produce more accurate and reliable SeaLights reports.
{% endhint %}

## Configuration

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

```json
{
  "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:

```bash
npm run build-cache
```

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

```bash
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:

```json
{
  "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.