# 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/installation).
{% 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/commands/setup) 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/commands/manage-user-mapping) 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/commands/report#output-structure) for details on what each folder contains.

## Next Steps

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

***

## 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 %}