> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-integration/3.0/use-harness-ci/use-harness-ci/run-tests/test-management/ci-test-quarantine.md).

# Test Quarantine

Skip unstable tests to unblock deployments while you investigate

{% hint style="info" %}
**PREREQUISITES**

Test Quarantine requires the feature flag `TI_POLICY_EVALUATION_ENABLED` to be enabled on your account. To use hcli commands for managing quarantined tests, you must also set the environment variable `CI_ENABLE_HCLI_FOR_TESTS=true` in your pipeline.

Contact [Harness Support](mailto:support@harness.io) to enable the feature flag. Go to [Environment variables](/continuous-integration/use-harness-ci/use-harness-ci/run-step-settings.md#environment-variables) to configure environment variables.
{% endhint %}

## Test Quarantine <a href="#test-quarantine" id="test-quarantine"></a>

When an unstable test blocks every deployment, quarantine lets you bypass it while you investigate. Quarantined tests still run, so you see if they're fixed, but their failures don't block the pipeline.

{% hint style="warning" %}
**QUARANTINE IS TEMPORARY**

Create a tracking issue with a deadline for every quarantined test. Quarantined tests represent untested code paths.
{% endhint %}

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before using test quarantine commands, ensure you have:

* **Harness account access:** Account ID for your Harness account.
* **Personal Access Token (PAT):** Required for API authentication. Go to [Manage API keys](/harness-platform/3.0/harness-platform-resources/automation/api/add-and-manage-api-keys.md) to create a PAT.
* **hcli installed:** Harness CLI tool must be available in your environment. Go to [Install and configure Harness CLI](/harness-platform/3.0/harness-platform-resources/automation/cli/install.md) to download hcli for your operating system and architecture.

***

### Enable Quarantine in Your Pipeline <a href="#enable-quarantine-in-your-pipeline" id="enable-quarantine-in-your-pipeline"></a>

Many test steps are configured to fail the build when any test fails. When quarantine is enabled, Harness evaluates the test results and **ignores failures from quarantined tests when determining the step status**.

Quarantined tests still run and their results are recorded, but they won’t cause the step to fail.

To enable this behavior, add the following environment variable to your test step:

```yaml
env:
  CI_ENABLE_QUARANTINED_TEST_SKIP: "true"
```

Full pipeline example:

{% tabs %}
{% tab title="Python" %}

```yaml
- run:
    script: |-
      pytest --junitxml=test-results.xml -v
      hcli test-reports upload test-results.xml
    env:
      CI_ENABLE_QUARANTINED_TEST_SKIP: "true"
```

{% endtab %}

{% tab title="Java/Gradle" %}

```yaml
- step:
    type: Run
    name: Run Tests
    spec:
      shell: Sh
      command: |
        ./gradlew clean test
        hcli test-reports upload "build/test-results/test/*.xml"
      envVariables:
        CI_ENABLE_QUARANTINED_TEST_SKIP: "true"
```

{% endtab %}
{% endtabs %}

### When to Quarantine <a href="#when-to-quarantine" id="when-to-quarantine"></a>

| Situation                                | Quarantine?     |
| ---------------------------------------- | --------------- |
| Flaky test blocks every deployment       | Yes             |
| External service is temporarily down     | Yes             |
| Urgent release needed, will fix tomorrow | Yes             |
| Test is slow but always passes           | No, optimize it |
| Test fails consistently on all runs      | No, fix the bug |

### How Quarantine Works <a href="#how-quarantine-works" id="how-quarantine-works"></a>

| Original Result | With Quarantine | Pipeline Impact |
| --------------- | --------------- | --------------- |
| FAIL            | PASS (ignored)  | Does not block  |
| PASS            | PASS            | No change       |
| SKIP            | SKIP            | No change       |

The test still executes, you'll see if it passes or fails—but failures are ignored for pipeline status.

### Quarantine a Test <a href="#quarantine-a-test" id="quarantine-a-test"></a>

Use the `set` command with the `--quarantine=true` flag to quarantine a test:

```bash
hcli test-management set \
  --account-id="$HARNESS_ACCOUNT_ID" \
  --repo="<URL_for_your_repo>" \
  --endpoint="https://<your-instance>/gateway/ti-service/" \
  --api-key="$HARNESS_PAT" \
  --class-name="com.example.PaymentTest" \
  --test-name="testRefundTimeout" \
  --quarantine=true
```

{% hint style="info" %}
**REPOSITORY URL FORMAT**

The `.git` suffix is optional. If omitted, it will be appended automatically.
{% endhint %}

{% hint style="info" %}
**WHEN TO USE SUITE NAME**

Use the `--suite-name` parameter when your JUnit XML reports include a test suite structure, and you need to uniquely identify a test within a specific suite. This is helpful when the same test name appears in multiple suites.
{% endhint %}

{% hint style="info" %}
**ENDPOINT VARIES BY INSTANCE**

The `--endpoint` value is based on your Harness instance domain: `https://<your-instance>/gateway/ti-service/`

For example, if you access Harness at `https://your-instance.harness.io`, use `https://your-instance.harness.io/gateway/ti-service/`.
{% endhint %}

#### Required Parameters <a href="#required-parameters" id="required-parameters"></a>

* `--account-id`: Your Harness account ID
* `--repo`: Repository URL (with or without `.git` suffix)
* `--endpoint`: TI service endpoint URL
* `--api-key`: Your Personal Access Token (PAT) starting with `pat.`
* `--class-name`: Test class name (must match the class name in your JUnit XML report)
* `--test-name`: Test method name (must match the test name in your JUnit XML report)
* `--quarantine`: Set to `true` to quarantine, `false` to remove from quarantine, or `unmark` to remove the marking entirely

#### Optional Parameters <a href="#optional-parameters" id="optional-parameters"></a>

* `--suite-name`: Test suite name (if the test belongs to a specific suite in your JUnit XML report)
* `--org-id`: Organization ID (if scoped to an organization)
* `--project-id`: Project ID (if scoped to a project)

### View Quarantined Tests <a href="#view-quarantined-tests" id="view-quarantined-tests"></a>

```bash
hcli test-management get \
  --account-id="$HARNESS_ACCOUNT_ID" \
  --repo="<URL_for_your_repo>" \
  --endpoint="https://<your-instance>/gateway/ti-service/" \
  --api-key="$HARNESS_PAT"
```

#### Required Parameters <a href="#required-parameters" id="required-parameters"></a>

* `--account-id`: Your Harness account ID
* `--repo`: Repository URL (with or without `.git` suffix)
* `--endpoint`: TI service endpoint URL
* `--api-key`: Your Personal Access Token (PAT) starting with `pat.`

#### Optional Parameters <a href="#optional-parameters" id="optional-parameters"></a>

* `--org-id`: Organization ID (filters results to a specific organization)
* `--project-id`: Project ID (filters results to a specific project)

Example output:

```
Found 6 quarantined test(s):
  - com.taskmanager.FlakyTest::flakyTest1
  - com.taskmanager.FlakyTest::Flaky Test 2: Timing sensitive
  - com.taskmanager.FlakyTest::Flaky Test 3: Random number comparison
  - com.taskmanager.service.WorkItemServiceTest::Flaky test that randomly fails
Page 1 of 1 (total: 6 tests)
```

### Remove from Quarantine <a href="#remove-from-quarantine" id="remove-from-quarantine"></a>

After fixing the test, use the `set` command with `--quarantine=false`:

```bash
hcli test-management set \
  --account-id="$HARNESS_ACCOUNT_ID" \
  --repo="<URL_for_your_repo>" \
  --endpoint="https://<your-instance>/gateway/ti-service/" \
  --api-key="$HARNESS_PAT" \
  --class-name="com.example.PaymentTest" \
  --test-name="testRefundTimeout" \
  --quarantine=false
```

***

### Advanced: Set Multiple Test Statuses <a href="#advanced-set-multiple-test-statuses" id="advanced-set-multiple-test-statuses"></a>

The `set` command can update both flaky and quarantine status in a single command:

```bash
hcli test-management set \
  --account-id="$HARNESS_ACCOUNT_ID" \
  --repo="<URL_for_your_repo>" \
  --endpoint="https://<your-instance>/gateway/ti-service/" \
  --api-key="$HARNESS_PAT" \
  --class-name="com.example.PaymentTest" \
  --test-name="testRefundTimeout" \
  --flaky=true \
  --quarantine=true
```

#### Available Values <a href="#available-values" id="available-values"></a>

`--flaky` and `--quarantine` accept `true`, `false`, and `unmark`:

* **true:** Mark the test with the status
* **false:** Remove the status from the test
* **unmark:** Remove any manual override and let auto-detection decide

#### Examples <a href="#examples" id="examples"></a>

Mark a test as flaky only:

```bash
hcli test-management set \
  --class-name="tests.TestSuite" \
  --test-name="test_method" \
  --flaky=true \
  --account-id="$HARNESS_ACCOUNT_ID" \
  --repo="<URL_for_your_repo>" \
  --endpoint="https://<your-instance>/gateway/ti-service/" \
  --api-key="$HARNESS_PAT"
```

Quarantine a test with suite name:

```bash
hcli test-management set \
  --class-name="com.example.PaymentTest" \
  --test-name="testRefundTimeout" \
  --suite-name="com.example.PaymentTestSuite" \
  --quarantine=true \
  --account-id="$HARNESS_ACCOUNT_ID" \
  --repo="<URL_for_your_repo>" \
  --endpoint="https://<your-instance>/gateway/ti-service/" \
  --api-key="$HARNESS_PAT"
```

Remove quarantine marking entirely:

```bash
hcli test-management set \
  --class-name="tests.TestSuite" \
  --test-name="test_method" \
  --quarantine=unmark \
  --account-id="$HARNESS_ACCOUNT_ID" \
  --repo="<URL_for_your_repo>" \
  --endpoint="https://<your-instance>/gateway/ti-service/" \
  --api-key="$HARNESS_PAT"
```

***

### Automate with Policies <a href="#automate-with-policies" id="automate-with-policies"></a>

Instead of manually quarantining tests, use [policies](/continuous-integration/use-harness-ci/use-harness-ci/run-tests/test-management/ci-test-policies.md) to automate:

```json
[
  {
    "when": ["test failed"],
    "action": ["mark quarantine"]
  }
]
```

This automatically quarantines any test that fails in the current pipeline execution.

### Best Practices <a href="#best-practices" id="best-practices"></a>

| Practice                | Why                                         |
| ----------------------- | ------------------------------------------- |
| Create a tracking issue | Every quarantined test needs an owner       |
| Set a deadline          | Quarantine should be temporary (7 days max) |
| Review weekly           | Prevent accumulation of quarantined tests   |
| Fix the root cause      | Don't just quarantine—investigate and fix   |

### Next Steps <a href="#next-steps" id="next-steps"></a>

* [Set up policies](/continuous-integration/use-harness-ci/use-harness-ci/run-tests/test-management/ci-test-policies.md) to automate quarantine decisions
* [View flaky tests](/continuous-integration/use-harness-ci/use-harness-ci/run-tests/test-management/ci-flaky-tests.md) to find quarantine candidates

{% @harness-feedback/feedback %}