# User Lab Mapping

User lab mapping links each qTest user to a **lab ID** — the environment identifier SeaLights uses to group test results by testing environment.

## Why It Matters

In SeaLights, a **lab ID** represents a specific testing environment or context. When test executions are reported, SeaLights needs to know which environment each execution came from so it can correctly attribute coverage and generate per-environment Test Optimization recommendations.

Without user lab mapping:

* Test executions from unmapped users are excluded from SeaLights reports
* SeaLights cannot track which environments have been tested
* Test Optimization recommendations may be incomplete or incorrect

## How User IDs Are Discovered

qTest executions include the ID of the user who ran the test. The tool collects these user IDs during report generation and adds any new ones to `config.json` with the placeholder value `TODO-lab-id`:

```json
{
  "userLabMapping": {
    "226846": "lab-east",
    "123456": "TODO-lab-id",
    "789012": "IGNORE"
  }
}
```

You then use `npm run manage-user-mapping` to assign a real lab ID to each `TODO-lab-id` entry.

## Mapping Values

| Value                             | Meaning                                                                             |
| --------------------------------- | ----------------------------------------------------------------------------------- |
| A lab ID string (e.g. `lab-east`) | Executions by this user are reported to SeaLights under this lab                    |
| `TODO-lab-id`                     | Discovered but not yet mapped — assign a lab ID using `npm run manage-user-mapping` |
| `IGNORE`                          | User's executions are excluded from all reports                                     |

## Choosing Lab IDs

* Use your internal environment naming convention consistently across your organization
* Typical examples: `lab-east`, `lab-west`, `qa-1`, `qa-2`, `staging`, `uat`
* Multiple testers can share the same lab ID if they test in the same environment
* The lab ID must match the lab ID configured in the SeaLights coverage collector for the application under test in that environment

## Maintaining Mappings

| Situation                               | Action                                                                                              |
| --------------------------------------- | --------------------------------------------------------------------------------------------------- |
| New tester joins                        | Run a report (they are auto-discovered), then run `npm run manage-user-mapping` to assign their lab |
| Tester moves to a different environment | Edit their mapping in `npm run manage-user-mapping` or directly in `config.json`                    |
| System/bot account appears in results   | Set to `IGNORE`                                                                                     |

See [User Mapping Command](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/commands/manage-user-mapping) for the interactive tool walkthrough.