Configuration

The tool is configured via config.json, environment variables, or CLI flags. All three sources can be combined.

Configuration Priority

Values from multiple sources are merged using this priority order (highest to lowest):

Priority	Source	Example
1 — Highest	CLI flag	npm run report -- --days 7
2	Remote config	Fetched automatically from SeaLights backend
3	Environment variable	SL_DAYS=7
4	config.json	Local configuration file
5 — Lowest	Default value	Built-in defaults

Remote config is fetched automatically when SeaLights credentials are available. If the fetch fails, the tool continues with local config (graceful degradation).

config.json Structure

Create config.json by running npm run setup (recommended) or by copying config.example.json:

cp config.example.json config.json

Full structure with all available fields:

{
  "qTestUrl": "https://your-company.qtestnet.com/",
  "auth": {
    "username": "[email protected]",
    "password": "your-password",
    "clientCredentials": "base64-encoded-credentials"
  },
  "sealights": {
    "token": "your-sealights-agent-token",
    "backendUrl": "https://prod.sealights.co",
    "statusMapping": {
      "passed": "passed",
      "pass": "passed",
      "failed": "failed",
      "fail": "failed",
      "skipped": "skipped",
      "blocked": "skipped"
    }
  },
  "defaultProject": {
    "name": "MyProject"
  },
  "userLabMapping": {
    "123456": "lab-east",
    "789012": "lab-west"
  },
  "testStageMapping": {
    "MyProject / Regression Suite": "Regression",
    "MyProject / E2E Tests": "E2E Tests"
  },
  "testDesignMapping": {
    "mappedModules": {
      "1234567": {
        "name": "Regression Testing",
        "slTestStage": "Regression Testing",
        "parentPath": ["Test Design"],
        "includeSubtree": true
      }
    }
  },
  "recommendations": {
    "skipStatusName": "SL Skipped",
    "enableMockMode": false,
    "reportRecencyThresholdHours": 5,
    "pollIntervalSeconds": 30,
    "pollTimeoutMinutes": 10
  }
}

---

Authentication

OAuth (Username and Password)

{
  "auth": {
    "username": "[email protected]",
    "password": "your-password",
    "clientCredentials": "base64-encoded-credentials"
  }
}

clientCredentials is a base64-encoded string specific to your qTest instance. Contact your qTest administrator if you are unsure of the value.

Bearer Token

If your organization uses token-based authentication, use bearerToken instead:

{
  "auth": {
    "bearerToken": "your-bearer-token"
  }
}

Bearer token authentication is preferred where available — it avoids storing your password in config.json.

---

SeaLights Settings

Field	Description	Required
sealights.token	SeaLights agent token	Yes
sealights.backendUrl	SeaLights backend URL — set automatically during setup	Yes
sealights.statusMapping	Maps qTest result status strings to SeaLights statuses (passed, failed, skipped)	No

Status Mapping

The statusMapping field controls how qTest execution statuses are translated to SeaLights statuses. Customize this if your qTest instance uses non-standard status names:

{
  "sealights": {
    "statusMapping": {
      "passed": "passed",
      "pass": "passed",
      "success": "passed",
      "failed": "failed",
      "fail": "failed",
      "error": "failed",
      "skipped": "skipped",
      "blocked": "skipped",
      "incomplete": "skipped"
    }
  }
}

---

Test Design Mapping

Test Design mapping connects your qTest Test Design folder structure to SeaLights test stage names. It is set up interactively by the Setup Wizard and stored in config.json under testDesignMapping.

{
  "testDesignMapping": {
    "mappedModules": {
      "1234567": {
        "name": "Regression Testing",
        "slTestStage": "Regression Testing",
        "parentPath": ["Test Design Root"],
        "includeSubtree": true
      },
      "1234568": {
        "name": "E2E Tests",
        "slTestStage": "E2E Tests",
        "parentPath": ["Test Design Root"],
        "includeSubtree": true
      }
    }
  }
}

Field	Description
mappedModules	Map of qTest Test Design module IDs to their SeaLights test stage configuration
name	The qTest module name (informational)
slTestStage	The SeaLights test stage name this module maps to
parentPath	The parent folder path in the qTest Test Design tree (informational)
includeSubtree	Whether to include all sub-folders of this module in the mapping

See Test Design Mapping for a full explanation of how this works.

---

Test Stage Mapping

testStageMapping is a simpler path-based fallback used when a test is not matched by testDesignMapping. It maps qTest path strings to SeaLights stage names.

{
  "testStageMapping": {
    "MyProject / Regression Suite": "Regression",
    "MyProject / Integration Tests": "Integration"
  }
}

The key is the full qTest path (Project / Folder). The value is the SeaLights test stage name to use. Tests that match neither mapping use their raw qTest path as the stage name.

---

User Lab Mapping

Maps qTest user IDs to lab identifiers. User IDs are discovered automatically during report generation.

{
  "userLabMapping": {
    "226846": "lab-east",
    "123456": "lab-west",
    "789012": "TODO-lab-id",
    "999999": "IGNORE"
  }
}

Value	Meaning
A lab ID (e.g. lab-east)	User's test executions are reported to SeaLights under this lab
TODO-lab-id	User was discovered but not yet mapped — use npm run manage-user-mapping to assign
IGNORE	User's test executions are silently excluded from all reports

Use IGNORE for system accounts, automation bots, or users you intentionally exclude from tracking.

See User Lab Mapping for more details.

---

Recommendations Settings

Field	Default	Description
skipStatusName	"SL Skipped"	The qTest execution status applied to tests that SeaLights recommends skipping
enableMockMode	false	Set to true to use mock recommendations instead of the real SeaLights API (for testing only)
reportRecencyThresholdHours	5	Minimum hours since last report before recommendations are considered valid
pollIntervalSeconds	30	How often to poll SeaLights for recommendation results
pollTimeoutMinutes	10	Maximum time to wait for recommendation results

Keep enableMockMode set to false in production. Enable it only for testing or demo purposes.

---

Environment Variables

All key configuration values can be set via environment variables, which is the recommended approach for CI/CD pipelines.

Environment Variable	Config Equivalent	Description
SL_TOKEN	sealights.token	SeaLights agent token
SL_BACKEND_URL	sealights.backendUrl	SeaLights backend URL
SL_QTEST_URL	qTestUrl	qTest instance URL
SL_QTEST_TOKEN	auth.bearerToken	qTest bearer token
SL_PROJECT	defaultProject.name	Default project name
SL_PROJECT_ID	defaultProject.id	Default project ID
SL_DAYS	cli.days	Number of days to look back (default: 30)
SL_DEBUG	cli.debug	Set to true to enable verbose debug output

Environment variable names are case-insensitive — SL_TOKEN, sl_token, and Sl_Token are all equivalent. Empty values (e.g. SL_DEBUG=) are treated as unset.

---

Proxy Configuration

If your network requires a corporate proxy, set the following environment variables before running any command:

Variable	Description	Example
HTTPS_PROXY	Proxy for HTTPS traffic	http://proxy.company.com:8080
HTTP_PROXY	Proxy for HTTP traffic	http://proxy.company.com:8080
NO_PROXY	Comma-separated hosts to bypass	localhost,127.0.0.1,.internal.com

Linux / macOS

export HTTPS_PROXY=http://proxy.company.com:8080
npm run setup
npm run report

Windows (PowerShell)

---

Security

Do	Don't
Set chmod 600 config.json (Linux/macOS) or equivalent	Store config.json in shared or public directories
Keep config.json in the project directory	Commit config.json to version control
Use bearer token authentication where available	Share credentials across users
Rotate tokens periodically	Log or print credential values

config.json is included in .gitignore by default. Never remove it from .gitignore.