# Recommendations

The `recommendations` command retrieves Test Optimization recommendations from SeaLights and applies them to qTest. SeaLights analyzes recent code changes and identifies which tests are safe to skip. The tool then marks those tests in qTest with the configured skip status (e.g. "SL Skipped").

```bash
npm run recommendations
```

## Prerequisites

Before running recommendations in production:

* SeaLights agents must be deployed on the application under test
* At least one successful test execution report must have been sent to SeaLights (via `npm run report`)
* The SeaLights model must have completed training — this typically takes a few days after the first reports are received
* `config.json` must contain a valid `recommendations.skipStatusName` value that matches a status in your qTest instance

{% hint style="info" %}
Not ready for production yet? Use [demo mode](#demo-mode) to validate the workflow without waiting for model training.
{% endhint %}

## The Recommendations Wizard

The wizard is an interactive 8-step flow:

| Step       | Description                                                                                                                                         |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Step 0** | **Operator identification** — Identifies you from `config.auth.username` (or prompts for your email) and looks up your lab ID from `userLabMapping` |
| **Step 1** | Select the qTest project                                                                                                                            |
| **Step 2** | Select the Test Design module                                                                                                                       |
| **Step 3** | Auto-discover available test stages                                                                                                                 |
| **Step 4** | Select the target Test Execution location in qTest                                                                                                  |
| **Step 5** | Create the recommendations structure in qTest                                                                                                       |
| **Step 6** | Validate the skip status configuration                                                                                                              |
| **Step 7** | For each test stage: report executions → receive recommendations → apply skip status                                                                |

### Step 0 — Operator Identification

Before any recommendations are fetched, the wizard identifies who you are:

1. Your email is read from `config.auth.username`, or you are prompted to enter it
2. Your qTest user ID is looked up automatically
3. Your lab ID is read from `userLabMapping` (or you are prompted to enter one)
4. SeaLights fetches the Applications Under Test (AUT) associated with your lab

All subsequent API calls include your lab ID so that recommendations are scoped correctly to your testing environment.

## Example Session

```
╔══════════════════════════════════════════════════════════════════╗
║         SeaLights qTest Recommendations Wizard (v3.30.0)         ║
╚══════════════════════════════════════════════════════════════════╝

Step 0: Operator Identification
──────────────────────────────────────────────────────────────────
✅ Identified as: jane.doe@company.com (ID: 12345)
   Lab ID: lab-east
   AUT: MyApplication v2.1.0

Step 1: Select Project
──────────────────────────────────────────────────────────────────
   [1] MyProject (ID: 12345)
Select: 1

Step 2: Select Test Design Module
──────────────────────────────────────────────────────────────────
   [1] 📁 Regression Testing
Select: 1

Step 3: Discovering test stages...
   ✅ Found 3 test stages: Component Tests, E2E Tests, API Tests

...

Step 7: Processing test stages
──────────────────────────────────────────────────────────────────
Processing: Component Tests
   📤 Reporting executions to SeaLights...
   ✅ Reported 245 test executions
   ⏳ Waiting for recommendations...
   ✅ Received 87 recommendations
   ✅ Applied "SL Skipped" to 87 tests in qTest

Processing: E2E Tests
   ...
```

## Demo Mode

Use demo mode to validate your qTest integration and train your team on the workflow without requiring SeaLights agents or model training.

```bash
# Step 1: Generate mock recommendation data from your test cases
npm run prepare-recommendations-demo

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

A prominent `DEMO MODE ACTIVE` banner is displayed throughout the session. The wizard flow is identical to production — but SeaLights API calls are replaced with mock data and no data is sent to SeaLights.

{% hint style="warning" %}
Do not use demo mode in production. Ensure `recommendations.enableMockMode` is `false` (or not set) in `config.json` for all production runs.
{% endhint %}

## Verifying Recommendations in qTest

After the wizard completes, open qTest Test Execution and verify:

1. Tests recommended for skipping are marked with the configured skip status (e.g. "SL Skipped")
2. The count of skipped tests matches the wizard's output summary
3. Non-recommended tests remain with their original status

## Configuration

Recommendations behavior is controlled by the `recommendations` block in `config.json`:

| Field                         | Description                                                                                                |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `skipStatusName`              | The qTest execution status applied to skipped tests. Must match an existing status in your qTest instance. |
| `reportRecencyThresholdHours` | Minimum hours since last report for recommendations to be considered valid                                 |
| `pollIntervalSeconds`         | How often the tool polls SeaLights for recommendation results                                              |
| `pollTimeoutMinutes`          | Maximum wait time for recommendation results                                                               |

See [Configuration — Recommendations Settings](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/configuration#recommendations-settings).