# Test Project ID

## Overview

**Test Project ID** allows you to run multiple test cycles with the same test stage name (e.g., "regression", "smoke") while keeping them completely separate in SeaLights Test Optimization.

### Who Should Use This?

* **DevOps Engineers** onboarding test runner pipelines for multiple products/teams
* **QA Managers** managing manual testing frameworks (e.g., qTest) across different teams
* **Any organization** where multiple teams or products share the same testing lab environment

***

## The Problem This Solves

### Scenario Without Test Project ID

Imagine you have two products testing in the same lab:

* **Product A** starts a "regression" test cycle
* **Product B** also starts a "regression" test cycle at the same time

**What happens?** Both products' tests merge into a single "regression" cycle in SeaLights. You'll see:

* ❌ Mixed test results from both products
* ❌ Combined coverage from Product A and Product B applications
* ❌ No way to separate which tests belong to which product

### Solution With Test Project ID

By assigning each product its own Test Project ID:

* **Product A:** `test-stage=regression`, `test-project-id=Product A`
* **Product B:** `test-stage=regression`, `test-project-id=Product B`

**What you'll see in Test Optimization:**

* ✅ Two separate test cycles: `regression (Product A)` and `regression (Product B)`
* ✅ Clear separation between products/teams

***

## How It Appears in the UI

In the **SeaLights Test Optimization** dashboard, test cycles are displayed with their Test Project ID.

**Test Cycle List View:**

<table><thead><tr><th width="246.10546875">Test Cycle Name</th><th>Status</th><th>Applications</th><th>Coverage</th></tr></thead><tbody><tr><td><code>regression (Product A)</code></td><td>Running</td><td>App1, App2</td><td>78%</td></tr><tr><td><code>regression (Product B)</code></td><td>Running</td><td>App3, App4, App5</td><td>82%</td></tr><tr><td><code>smoke (Product A)</code></td><td>Completed</td><td>App1, App2</td><td>65%</td></tr></tbody></table>

{% hint style="info" %}
The Test Project ID appears in parentheses after the test stage name, making it easy to identify which cycle belongs to which product or team.
{% endhint %}

***

## Configuration

You can configure Test Project ID using either:

1. **Command-line parameter** (when running your test agent)
2. **Environment variable** (set in your CI/CD pipeline or test environment)

### Option 1: Command-Line Parameter

The exact CLI parameter depends on your test runner technology. Refer to your technology-specific documentation for the correct parameter name and syntax.

**General pattern:**

```bash
<your-test-runner-command> --test-stage=regression --test-project-id="Product A"
```

### Option 2: Environment Variable

Set the following environment variable before running your tests:

```bash
export SL_TEST_PROJECT_ID="Product A"
```

**Example in CI/CD pipeline:**

```yaml
# Jenkins, GitLab CI, etc.
environment:
  SL_TEST_PROJECT_ID: "Product A"
```

***

## Technology-Specific Configuration

### Gradle

Add `testProjectId` to your `sl-config.json` configuration file to distinguish test stages with the same name (e.g., "Component Tests" or "BDD Tests") when triggered by different teams or test sets.

**When to use:**

* Multiple teams run the same test stage name against the same application
* You need separate tracking of test results from different sources
* Different pipelines execute identical test stages concurrently

**Example scenario:** Team A and Team B both run "BDD Tests" against the same application. Using different `testProjectId` values ensures their results are tracked separately in the SeaLights Dashboard.

#### Configuration

**Gradle Plugin 4.0.1013 and later** — add `testProjectId` to `sl-config.json`:

```json
{
  "executionType": "testsonly",
  "tokenFile": "./sltoken.txt",
  "labId": "<lab-id>",
  "runFunctionalTests": true,
  "testStage": "BDD Tests",
  "testProjectId": "<your-test-project-identifier>"
}
```

**Older versions** — you must also pass the value via `sealightsJvmParams`:

```json
{
  "executionType": "testsonly",
  "tokenFile": "./sltoken.txt",
  "labId": "<lab-id>",
  "runFunctionalTests": true,
  "testStage": "BDD Tests",
  "testProjectId": "<your-test-project-identifier>",
  "sealightsJvmParams": {
    "sl.testProjectId": "<your-test-project-identifier>"
  }
}
```

{% hint style="success" %}
**Recommendation:** Use the latest version of the SeaLights Java agent. From Gradle Plugin 4.0.1013+, only the `testProjectId` field in `sl-config.json` is required.
{% endhint %}

#### Integration Steps

1. Integrate with your Gradle project:

```bash
java -jar sl-build-scanner.jar -gradle -configfile sl-config.json -workspacepath .
```

2. Run your tests:

```bash
./gradlew <your-test-task-name>
```

3. Restore build files:

```bash
java -jar sl-build-scanner.jar -restoreGradle -workspacepath .
```

***

## Best Practices

**✅ DO:**

* **Use descriptive names** that clearly identify the product, team, or project
  * Good: `"Product A"`, `"Mobile-Team"`, `"PaymentService"`
  * Avoid: `"test1"`, `"proj"`, `"abc"`
* **Be consistent** across all pipelines for the same product
  * All Product A pipelines should use the same Test Project ID
* **Use Test Project ID whenever multiple teams share:**
  * The same test lab environment
  * The same test stage names (regression, smoke, etc.)
* **Leverage for test organization:**
  * Group related tests together (e.g., by test suite, functional area, or component)
  * Maintain visibility into different test groups while keeping consolidated coverage metrics

**❌ DON'T:**

* Change the Test Project ID mid-cycle (keeps cycles distinct)
* Use special characters that might cause issues in URLs or file systems

***

## Common Use Cases

### Use Case 1: Multiple Products in Shared Lab

**Scenario:** Two products deploy to the same central testing lab

**Configuration:**

* Product A Pipeline: `--test-stage=regression --test-project-id="Product A"`
* Product B Pipeline: `--test-stage=regression --test-project-id="Product B"`

**Result:** Two separate `regression` cycles in Test Optimization

***

### Use Case 2: Multiple Teams Testing Same Application

**Scenario:** Frontend team and Backend team both run "integration" tests

**Configuration:**

* Frontend Team: `--test-stage=integration --test-project-id="Frontend"`
* Backend Team: `--test-stage=integration --test-project-id="Backend"`

**Result:** Separate integration cycles: `integration (Frontend)` and `integration (Backend)`

***

### Use Case 3: Different Product Versions

**Scenario:** Testing v1.0 and v2.0 simultaneously

**Configuration:**

* Version 1: `--test-stage=regression --test-project-id="v1.0"`
* Version 2: `--test-stage=regression --test-project-id="v2.0"`

**Result:** Clear separation between version testing cycles

***

### Use Case 4: Splitting Test Suites Within Same Test Stage

**Scenario:** You want to run API tests and UI tests as separate cycles, but track their combined coverage under "regression"

**Configuration:**

* API Tests: `--test-stage=regression --test-project-id="API-Suite"`
* UI Tests: `--test-stage=regression --test-project-id="UI-Suite"`

**Result:** Two distinct test cycles in Test Optimization (`regression (API-Suite)` and `regression (UI-Suite)`), while coverage for both rolls up to the "regression" test stage

***

## Troubleshooting

<details>

<summary><strong>Issue: "I don't see my Test Project ID in the cycle name"</strong></summary>

**Possible causes:**

1. Verify the parameter was set correctly (check your test runner logs)
2. Ensure you're looking at the correct test stage
3. &#x20;Refresh the Test Optimization dashboard

</details>

<details>

<summary><strong>Issue: "My test cycles are still merging together"</strong></summary>

**Check:**

* Both pipelines must use **different** Test Project IDs
* The Test Project ID must be set **before** the test-runner agent starts sending data
* Verify the environment variable or CLI parameter is correctly passed to the test-runner

</details>

***

## Additional Resources

* **Technology-Specific Configuration:** See the [Gradle configuration section](#gradle) above for `sl-config.json` setup and version compatibility details
* **Test Optimization Dashboard:** Learn more about viewing and analyzing test cycles
* **Customer Support:** Contact SeaLights support for assistance with onboarding

***

## Summary

**Test Project ID** gives you precise control over how test cycles are organized in SeaLights, especially when:

* Multiple teams share testing infrastructure
* Different products use the same test stage names
* You need clear separation of test results and coverage data

**Next Steps:**

1. Identify which pipelines need Test Project IDs
2. Choose meaningful, consistent names for each product/team
3. Configure your test runners using CLI parameters or environment variables
4. Verify the cycles appear correctly in Test Optimization


---

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

```
GET https://docs.sealights.io/knowledgebase/guides/test-optimization/test-project-id.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.