# User Mapping

The `manage-user-mapping` command is an interactive tool for discovering qTest users and assigning them to lab IDs. Lab IDs are the environment identifiers SeaLights uses to group test results by testing environment or tester.

```bash
npm run manage-user-mapping
```

## Menu Options

```
Select action:
   0. Fix pending mappings (users with TODO-lab-id)
   1. Edit existing mapping
   2. Add new mapping manually
   3. View all mappings
   4. Refresh user names from reports
   5. Discover users from qTest
   6. Exit
```

## Discovering Users

Users are added to `userLabMapping` in two ways:

1. **Automatically during report generation** — Any user ID found in qTest executions that is not already in `userLabMapping` is added with the placeholder value `TODO-lab-id`.
2. **Manually via the mapping tool** — Use option `5. Discover users from qTest` to scan recent executions for unknown users without running a full report.

After discovery, users with `TODO-lab-id` appear under option `0. Fix pending mappings`.

## Assigning Lab IDs

```
Select action: 0

⚠️  Users pending lab assignment:
   0. John Smith (ID: 226846)  →  TODO-lab-id
   1. Jane Doe (ID: 123456)    →  TODO-lab-id

Select user to assign: 0
Enter lab ID for John Smith: lab-east
✅ Updated: John Smith → lab-east
```

Repeat for each user until all `TODO-lab-id` entries are resolved.

## Lab ID Guidelines

* Use your internal environment naming convention (e.g. `lab-east`, `lab-west`, `qa-1`, `staging`)
* Assign the same lab ID to all testers who work in the same environment
* Be consistent across your organization — the same lab ID string must be used in both qTest integration config and the SeaLights configuration for the application under test

## Ignoring Users

Set a user's lab ID to `IGNORE` to permanently exclude their test executions from all reports:

```json
{
  "userLabMapping": {
    "999999": "IGNORE"
  }
}
```

Use `IGNORE` for automation bot accounts, qTest system users, or testers you intentionally exclude from SeaLights tracking.

## Example Session

```
╔═══════════════════════════════════════════════════════════════╗
║           User Lab Mapping Manager (v3.19.0)                  ║
╚═══════════════════════════════════════════════════════════════╝

✅ Found 5 user names
✅ Loaded discovery cache: 15 users from "MyProject"

📋 Found 12 new user(s) not yet in config.json
Add them now? (y/n): y
✅ Added 12 user(s) with TODO-lab-id

📊 Current Status:
   Total users in mapping: 15
   ✅ Mapped to labs: 3
   ⚠️  Pending (TODO-lab-id): 12
```

## When to Run

* **After the first report** — New users are discovered automatically; run this to assign their lab IDs
* **When new testers join** — Discover and map them before the next report cycle
* **After team reorganization** — Update lab assignments if testers move to different environments