> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/concepts/test-design-mapping.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/concepts/test-design-mapping.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.