> 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/commands/report.md).

# 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](/knowledgebase/setup-and-configuration/integrations/qtest-integration/concepts/incremental-reporting.md) 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](/knowledgebase/setup-and-configuration/integrations/qtest-integration/concepts/user-lab-mapping.md) for details.


---

# 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/commands/report.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.