# Inspect Test (Diagnostic)

The `inspect-test` command exports raw qTest data for a specific test run. It is a diagnostic tool used to investigate why a test execution appears in qTest but does not show up in SeaLights reports.

```bash
npm run inspect-test -- --test-run <TR-ID> --project <project-name>
```

{% hint style="info" %}
This tool is intended for support scenarios. If a tester reports that their test is missing from SeaLights, use this command to collect diagnostic data and share it with SeaLights support.
{% endhint %}

## Usage

```bash
# Inspect a single test run
npm run inspect-test -- --test-run TR-811684 --project MyProject

# Inspect multiple test runs
npm run inspect-test -- --test-run TR-811684 --test-run TR-811685 --project MyProject

# With debug output
npm run inspect-test -- --test-run TR-811684 --project MyProject --debug

# Show help
npm run inspect-test -- --help
```

The test run ID can be specified with or without the `TR-` prefix.

## Output

The command writes a JSON file to:

```
output/inspect-test-{timestamp}.json
```

The file contains:

| Field               | Description                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| Raw test run data   | The full test run object as returned by the qTest API                       |
| Test logs           | All execution log entries for the test run                                  |
| Hierarchy path      | The test cycle → test suite path in qTest                                   |
| Test case details   | The linked test case, if any                                                |
| Diagnostic analysis | The tool's assessment of why the test may have been filtered out of reports |

## Common Diagnostic Findings

The diagnostic analysis section explains why a test may be excluded from reports. Common reasons include:

| Finding                              | Explanation                                                                                                                                      |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| User not in `userLabMapping`         | The tester who ran this test has no lab ID assigned. Run `npm run manage-user-mapping`.                                                          |
| User set to `IGNORE`                 | The tester is explicitly excluded from reports. Update their mapping if this is incorrect.                                                       |
| Test case not in any mapped module   | The test case is in a Test Design folder not covered by `testDesignMapping`. Rebuild the cache with `npm run build-cache` or update the mapping. |
| Execution date outside report window | The test was run before the `--days` window of the last report. Re-run with a wider date range.                                                  |

## Sharing with Support

Send the JSON output file to SeaLights support along with:

* The test run ID(s) you investigated
* The project name
* The date the test was run in qTest
* The date range of the last report run

This gives support the information needed to investigate the issue.