> 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/commands/setup.md).

# 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.


---

# 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/commands/setup.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.