# Setup Wizard

The setup wizard (`npm run setup`) guides you through configuring the tool for first-time use. It creates or updates `config.json` with your qTest connection, SeaLights token, and Test Design mapping.

```bash
npm run setup
```

{% hint style="info" %}
If `config.json` already exists, the wizard uses your existing values as defaults. Press Enter to keep any value unchanged.
{% endhint %}

## What the Wizard Configures

{% stepper %}
{% step %}
**qTest Connection**

Enter your qTest instance URL and credentials. The wizard validates the connection before proceeding.
{% endstep %}

{% step %}
**Default Project**

Choose which qTest project to use as the default. The wizard lists all projects your account can access.
{% endstep %}

{% step %}
**SeaLights Connection**

Paste your SeaLights agent token. The wizard extracts the backend URL and customer ID automatically.
{% endstep %}

{% step %}
**Test Design Mapping**

Navigate the qTest Test Design folder tree and select the root folder whose sub-folders should become SeaLights test stages. All direct children of the selected folder are mapped automatically.
{% endstep %}

{% step %}
**Save Configuration**

A summary is displayed and `config.json` is written to disk.
{% endstep %}
{% endstepper %}

## Example Session

```
╔═════════════════════════════════════════════════════════════════╗
║           SeaLights qTest Integration - Setup Wizard            ║
╚═════════════════════════════════════════════════════════════════╝

✅ Existing config.json found - press Enter to keep current values

Step 1/5: qTest Configuration
─────────────────────────────────────────────────────────────────
Enter your qTest URL [https://company.qtestnet.com]: ↵
✅ qTest connection verified!

Step 2/5: Project Selection
─────────────────────────────────────────────────────────────────
Available projects:
   [1] MyProject (ID: 12345)
   [2] AnotherProject (ID: 67890)
Select project [1]: ↵
✅ Selected project: MyProject

Step 3/5: SeaLights Configuration
─────────────────────────────────────────────────────────────────
Paste your SeaLights token: eyJ...
✅ SeaLights token validated!
   Backend URL: https://prod.sealights.co
   Customer ID: your-company

Step 4/5: Test Design Mapping
─────────────────────────────────────────────────────────────────
Navigate to the Test Design folder to map as test stages:

   [1] 📁 Regression Testing
   [2] 📁 Integration Tests
   [3] ← Back

Select folder: 1

📂 Regression Testing
   [1] ✅ Map ALL sub-folders as test stages
   [2] 📁 Component Tests
   [3] 📁 E2E Tests
   [4] ← Back

Select: 1
✅ Mapped 2 modules as test stages

Step 5/5: Configuration Summary
─────────────────────────────────────────────────────────────────
✅ Configuration saved to config.json

📊 Configuration:
   qTest Project:      MyProject (ID: 12345)
   Test Stage Modules: 2

🔜 Next Steps:
   1. Run 'npm run manage-user-mapping' to discover & map users
   2. Run 'npm run report -- --days 90' for initial report
```

## Troubleshooting Setup

| Issue                 | Solution                                                                   |
| --------------------- | -------------------------------------------------------------------------- |
| "Invalid credentials" | Double-check your qTest username and password                              |
| "Connection refused"  | Verify the qTest URL — it should end with `/`                              |
| "No projects found"   | Ensure your account has access to at least one project                     |
| "Invalid token"       | Re-generate your SeaLights token from the SeaLights dashboard              |
| "No modules found"    | Ensure your qTest project has folders in the Test Design section           |
| Server errors (5xx)   | The wizard automatically retries 3 times — wait a moment and try again     |
| Step failed           | Choose `[R]` to retry, `[B]` to go back, or `[Q]` to quit and re-run later |

{% hint style="info" %}
Run `npm run setup -- --debug` to see detailed error output.
{% endhint %}

## When to Re-run Setup

* When new test stage folders are added to qTest Test Design
* When the SeaLights token expires or needs to be rotated
* After changing the default project
* After changing qTest credentials

Re-running setup preserves your existing mappings and only updates the fields you change.