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

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

{% hint style="info" %}
Remote config is fetched automatically when SeaLights credentials are available. If the fetch fails, the tool continues with local config (graceful degradation).
{% endhint %}

## config.json Structure

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

```bash
cp config.example.json config.json
```

Full structure with all available fields:

{% code overflow="wrap" lineNumbers="true" %}

```json
{
  "qTestUrl": "https://your-company.qtestnet.com/",
  "auth": {
    "username": "your.email@company.com",
    "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
  }
}
```

{% endcode %}

***

## Authentication

### OAuth (Username and Password)

```json
{
  "auth": {
    "username": "your.email@company.com",
    "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:

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

{% hint style="success" %}
Bearer token authentication is preferred where available — it avoids storing your password in `config.json`.
{% endhint %}

***

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

```json
{
  "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](/knowledgebase/setup-and-configuration/integrations/qtest-integration/commands/setup.md) and stored in `config.json` under `testDesignMapping`.

```json
{
  "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](/knowledgebase/setup-and-configuration/integrations/qtest-integration/concepts/test-design-mapping.md) 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.

```json
{
  "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.

```json
{
  "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](/knowledgebase/setup-and-configuration/integrations/qtest-integration/concepts/user-lab-mapping.md) 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                                                |

{% hint style="warning" %}
Keep `enableMockMode` set to `false` in production. Enable it only for testing or demo purposes.
{% endhint %}

***

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

{% hint style="info" %}
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.
{% endhint %}

***

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

{% tabs %}
{% tab title="Linux / macOS" %}

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

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```powershell
$env:HTTPS_PROXY = "http://proxy.company.com:8080"
npm run setup
npm run report
```

{% endtab %}
{% endtabs %}

***

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


---

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