# Report

The `report` command fetches test execution data from qTest and sends it to SeaLights. It processes both automated and manual test results and separates output by Test Design mapping status.

```bash
npm run report
```

## Options

| Option             | Description                                                      | Default           |
| ------------------ | ---------------------------------------------------------------- | ----------------- |
| `--days <n>`       | Number of days to look back for test executions                  | `7`               |
| `--full`           | Force a complete report, ignoring previously-reported timestamps | Off (incremental) |
| `--project <name>` | Filter by a specific qTest project name                          | All projects      |
| `--stage <name>`   | Filter by a specific test stage name                             | All stages        |
| `--lab <id>`       | Filter by a specific lab ID                                      | All labs          |
| `--debug`          | Enable verbose logging                                           | Off               |
| `--help`           | Show all available options                                       | —                 |

## Incremental vs. Full Mode

By default the report runs in **incremental mode**: each test stage tracks the timestamp of its last successful report. Subsequent runs only send tests executed since that timestamp, preventing duplicate submissions to SeaLights.

Use `--full` to override this and send all tests in the specified date range. This is useful when re-reporting after a configuration change or data issue.

```bash
# Incremental (default) — only new tests since last report
npm run report

# Incremental with extended fallback for stages not yet reported
npm run report -- --days 14

# Full report for the last 7 days
npm run report -- --full

# Full report for the last 30 days
npm run report -- --full --days 30
```

See [Incremental Reporting](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/concepts/incremental-reporting) for details on how this works.

## Common Scenarios

```bash
# Daily scheduled run (typical CI usage)
npm run report -- --days 1

# First run after setup — report historical data
npm run report -- --days 90

# Debug a specific project
npm run report -- --project "MyProject" --debug

# Filter to a single stage
npm run report -- --stage "Regression"
```

## Output Structure

Reports are written to a date-stamped folder under `output/`:

```
output/
└── 2026-01-29/
    ├── mapped/              # Tests matched via Test Design mapping
    │   ├── automation/
    │   │   └── MyProject_RegressionSuite.json
    │   └── manual/
    │       └── MyProject_RegressionSuite.json
    └── unmapped/            # Tests matched via testStageMapping path fallback
        ├── automation/
        │   └── MyProject_ComponentTests.json
        └── manual/
            └── MyProject_ManualTests.json
```

| Folder                 | Contents                                                                      |
| ---------------------- | ----------------------------------------------------------------------------- |
| `mapped/automation/`   | Automated test runs whose stage was resolved from Test Design                 |
| `mapped/manual/`       | Manual test runs whose stage was resolved from Test Design                    |
| `unmapped/automation/` | Automated test runs whose stage fell back to `testStageMapping` path matching |
| `unmapped/manual/`     | Manual test runs using path fallback                                          |

{% hint style="success" %}
**Mapped** tests are preferable — they use the structured Test Design hierarchy rather than raw path strings. Aim to keep the unmapped count low by ensuring your Test Design mapping covers all active test folders.
{% endhint %}

Each JSON file contains test execution data grouped by lab ID, ready to be consumed by SeaLights.

## Handling "Unknown User" Warnings

If the report output shows warnings like `⚠️ Unknown user: 12345`, that user's executions were found but have no lab ID assigned. Run `npm run manage-user-mapping` to assign them a lab ID.

See [User Lab Mapping](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/concepts/user-lab-mapping) for details.