> 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/quick-start.md).

# Quick Start

Get the SeaLights qTest Integration Tool up and running and generate your first report.

{% hint style="info" %}
For detailed prerequisites and installation instructions, see [Installation](/knowledgebase/setup-and-configuration/integrations/qtest-integration/installation.md).
{% endhint %}

## Step 1 — Install

{% hint style="info" %}
The SeaLights qTest Integration Tool is distributed as a controlled package. Contact your SeaLights Customer Success representative to receive the installation package and version appropriate for your environment.
{% endhint %}

Once you have received the package, extract it and install its dependencies:

```bash
cd sl-qtest-integration-tool
npm install
```

## Step 2 — Run the Setup Wizard

The setup wizard configures your qTest and SeaLights connections and sets up Test Design mapping.

```bash
npm run setup
```

The wizard will:

1. Ask for your qTest URL and credentials, then verify the connection
2. Let you select the default project
3. Ask for your SeaLights agent token, then extract backend settings automatically
4. Guide you through selecting qTest Test Design folders and mapping them to SeaLights test stages
5. Save everything to `config.json`

After setup, secure your config file:

{% tabs %}
{% tab title="Linux / macOS" %}

```bash
chmod 600 config.json
```

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```powershell
icacls config.json /inheritance:r /grant:r "$($env:USERNAME):F"
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
See [Setup Wizard](/knowledgebase/setup-and-configuration/integrations/qtest-integration/commands/setup.md) for a full walkthrough of the wizard flow.
{% endhint %}

## Step 3 — Map Users to Labs

Each tester in qTest needs to be mapped to a **lab ID** — the environment identifier SeaLights uses to group test results.

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

Select **"Discover users from qTest"** to auto-discover all users from recent executions, then assign a lab ID to each one.

{% hint style="info" %}
See [User Mapping](/knowledgebase/setup-and-configuration/integrations/qtest-integration/commands/manage-user-mapping.md) for a full walkthrough.
{% endhint %}

## Step 4 — Generate Your First Report

Run a report for the past 90 days to send your historical test execution data to SeaLights:

```bash
npm run report -- --days 90
```

You will see output similar to:

```
📋 Running hybrid report for project: MyProject (ID: 12345)
   Date range: 2025-10-28 to 2026-01-29

🚀 Using backward pagination...
   ✅ Found 1,234 test runs

💾 Writing output files...
   ✅ Mapped: output/2026-01-29/mapped/automation/MyProject_RegressionSuite.json
   ✅ Unmapped: output/2026-01-29/unmapped/automation/MyProject_ComponentTests.json

📊 Test Design Mapping Stats:
   ✅ Mapped via Test Design: 950 tests
   ⚠️  Unmapped (path fallback): 150 tests
```

{% hint style="warning" %}
If you see "Unknown user" warnings in the output, some testers are not yet mapped. Run `npm run manage-user-mapping` to assign their lab IDs.
{% endhint %}

## Step 5 — Check Your Output

Reports are saved in date-stamped folders:

```
output/
└── 2026-01-29/
    ├── mapped/          # Tests resolved via Test Design mapping (recommended)
    │   ├── automation/
    │   └── manual/
    └── unmapped/        # Tests using path-based stage name fallback
        ├── automation/
        └── manual/
```

See [Report Output](/knowledgebase/setup-and-configuration/integrations/qtest-integration/commands/report.md#output-structure) for details on what each folder contains.

## Next Steps

* Set up regular scheduled reporting — see [CI/CD Integration](/knowledgebase/setup-and-configuration/integrations/qtest-integration/ci-cd-integration.md)
* Customize test stage names in `config.json` — see [Configuration](/knowledgebase/setup-and-configuration/integrations/qtest-integration/configuration.md#test-stage-mapping)
* Get Test Optimization recommendations — see [Recommendations](/knowledgebase/setup-and-configuration/integrations/qtest-integration/commands/recommendations.md)

***

## Step 6 — Try the Recommendations Demo (Optional)

Before deploying SeaLights agents and waiting for model training, you can validate that the full recommendations workflow works correctly using demo mode. Demo mode simulates recommendations using mock data — no data is sent to SeaLights.

```bash
# Step 1: Prepare mock recommendations data
npm run prepare-recommendations-demo

# Step 2: Run recommendations in demo mode
npm run recommendations -- --demo
```

You will see a clear `DEMO MODE ACTIVE` banner throughout the session. The workflow is identical to production mode — the only difference is that SeaLights API calls are replaced with mock data.

{% hint style="success" %}
Use demo mode to verify your qTest integration and train your team on the recommendations workflow before going live.
{% endhint %}


---

# 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/quick-start.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.