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.

npm run setup

If config.json already exists, the wizard uses your existing values as defaults. Press Enter to keep any value unchanged.

What the Wizard Configures

1

qTest Connection

Enter your qTest instance URL and credentials. The wizard validates the connection before proceeding.

2

Default Project

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

3

SeaLights Connection

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

4

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.

5

Save Configuration

A summary is displayed and config.json is written to disk.

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

Run npm run setup -- --debug to see detailed error output.

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.