# 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/commands/setup) 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](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/concepts/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.

```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](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/qtest-integration/concepts/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                                                |

{% 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`.