Quick Start

Get the SeaLights qTest Integration Tool up and running and generate your first report.

For detailed prerequisites and installation instructions, see Installation.

Step 1 — Install

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.

Once you have received the package, extract it and install its dependencies:

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.

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:

Linux / macOS

chmod 600 config.json

Windows (PowerShell)

See Setup Wizard for a full walkthrough of the wizard flow.

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.

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.

See User Mapping for a full walkthrough.

Step 4 — Generate Your First Report

Run a report for the past 90 days to send your historical test execution data to SeaLights:

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

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.

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 for details on what each folder contains.

Next Steps

• Set up regular scheduled reporting — see CI/CD Integration
• Customize test stage names in config.json — see Configuration
• Get Test Optimization recommendations — see 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.

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

Use demo mode to verify your qTest integration and train your team on the recommendations workflow before going live.