> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qlty.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Coverage Tags

# Coverage Tags

Coverage tags enable you to report on and gate pull requests based on specific subsets of your code coverage reports. This feature is particularly valuable in complex codebases where different components, languages, or test types need to be tracked separately.

## Why Use Coverage Tags?

Tags solve several common challenges when working with code coverage:

* **Monorepos and multi-language projects**: Track coverage separately for frontend vs. backend code, or for different components in a monorepo
* **Different test types**: Separate unit tests, integration tests, and end-to-end tests
* **Selective testing**: When not all tests run on every commit, tags allow Qlty to carry forward coverage information for different components

## How Tags Affect User Experience

When you use coverage tags in your project:

* Each tag reported for a pull request receives its own coverage gate (total coverage and/or diff coverage)
* Individual tag results appear in separate sections in PR comments
* On the pull request coverage tab, changes can be filtered by one or more tags
* When browsing coverage for your default branch, the coverage presented combines coverage across all tags

## Implementing Coverage Tags

To use coverage tags, simply add the `--tag` option to the `qlty coverage publish` command when publishing different parts of your coverage:

<CodeGroup>
  ```yaml GitHub Action lines theme={"system"}
  # Frontend coverage
  - uses: qltysh/qlty-action/coverage@v2
    with:
      token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
      files: frontend/coverage/lcov.info
      tag: frontend

  # Backend coverage

  - uses: qltysh/qlty-action/coverage@v2
    with:
      token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
      files: backend/coverage/coverage.xml
      tag: backend

  ```

  ```bash Qlty CLI lines theme={"system"}
  # Frontend coverage
  qlty coverage publish --tag=frontend frontend/coverage/lcov.info

  # Backend coverage
  qlty coverage publish --tag=backend backend/coverage/coverage.xml
  ```
</CodeGroup>

## Tags with Report Merging

Coverage tags work seamlessly with [report merging](/coverage/merging), allowing complex workflows while maintaining tag-specific insights.

### Important Considerations

When using coverage tags with report merging:

1. Each `qlty coverage publish` command applies to **a single tag** (or no tag)
2. Merging always refers to combining reports **for the same tag**, not across different tags
3. Server-side merging requires tracking completion separately for each tag

### Client-Side Merging with Tags

With client-side merging, run the `qlty coverage publish` command once per tag, combining all reports for that tag:

<CodeGroup>
  ```yaml GitHub Action lines theme={"system"}
  # Publish unit test coverage (combining multiple reports)
  - uses: qltysh/qlty-action/coverage@v2
    with:
      token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
      tag: unit
      files: |
          unit1.lcov
          unit2.lcov

  # Publish integration test coverage (combining multiple reports)

  - uses: qltysh/qlty-action/coverage@v2
    with:
      token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
      tag: integration
      files: |
          integration1.lcov
          integration2.lcov

  ```

  ```bash Qlty CLI lines theme={"system"}
  # Publish unit test coverage (combining multiple reports)
  qlty coverage publish --tag=unit \
      unit1.lcov unit2.lcov

  # Publish integration test coverage (combining multiple reports)
  qlty coverage publish --tag=integration \
      integration1.lcov integration2.lcov
  ```
</CodeGroup>

### Server-Side Merging with Tags

For server-side merging, each tag must be handled independently.

#### Using `total-parts-count` with tags

When using the `total-parts-count` approach, specify the count separately for each tag:

<CodeGroup>
  ```yaml GitHub Action lines theme={"system"}
  # Integration tag example (1 of 4)
  - uses: qltysh/qlty-action/coverage@v2
    with:
      token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
      tag: integration
      total-parts-count: 4
      files: coverage.lcov
  # ... Three more `qltysh/qlty-action/coverage` steps for the `integration` tag ...

  # Unit tag example (1 of 2)

  - uses: qltysh/qlty-action/coverage@v2
    with:
      token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
      tag: unit
      total-parts-count: 2
      files: coverage.lcov

  # ... One more `qltysh/qlty-action/coverage` step for the `unit` tag ...

  ```

  ```bash Qlty CLI lines theme={"system"}
  # Integration tag example (1 of 4)
  qlty coverage publish --tag=integration --total-parts-count=4 coverage.lcov
  # ... Three more `qlty coverage publish` commands for the `integration` tag ...

  # Unit tag example (1 of 2)
  qlty coverage publish --tag=unit --total-parts-count=2 coverage.lcov
  # ... One more `qlty coverage publish` command for the `unit` tag ...
  ```
</CodeGroup>

#### Using `coverage complete` with tags

When using the `--incomplete` flag approach, upload parts for each tag and then send a completion signal for that specific tag:

<CodeGroup>
  ```bash Qlty CLI lines theme={"system"}
  qlty coverage publish --tag=unit --incomplete unit1.lcov
  qlty coverage publish --tag=unit --incomplete unit2.lcov
  qlty coverage complete --tag=unit

  qlty coverage publish --tag=integration --incomplete integration1.lcov
  qlty coverage publish --tag=integration --incomplete integration2.lcov
  qlty coverage publish --tag=integration --incomplete integration3.lcov
  qlty coverage complete --tag=integration

  ```
</CodeGroup>

## Common Use Cases for Tags

### Multi-Language Projects

In projects with multiple programming languages, each with their own test frameworks:

<CodeGroup>
  ```bash Qlty CLI lines theme={"system"}
  # JavaScript code coverage
  qlty coverage publish --tag=javascript frontend/coverage/lcov.info

  # Python code coverage
  qlty coverage publish --tag=python backend/coverage.xml

  # Rust code coverage
  qlty coverage publish --tag=rust services/coverage.lcov
  ```
</CodeGroup>

### Monorepo with Multiple Components

For monorepos with distinct components that each need tracking:

<CodeGroup>
  ```bash Qlty CLI lines theme={"system"}
  # API service coverage
  qlty coverage publish --tag=api-service api/coverage/lcov.info

  # Web application coverage

  qlty coverage publish --tag=web-app web/coverage/lcov.info

  # Mobile application coverage

  qlty coverage publish --tag=mobile-app mobile/coverage/lcov.info

  ```
</CodeGroup>

### Different Test Types

When separating coverage by test type:

<CodeGroup>
  ```bash Qlty CLI lines theme={"system"}
  # Unit tests coverage
  qlty coverage publish --tag=unit tests/unit/coverage.lcov

  # Integration tests coverage
  qlty coverage publish --tag=integration tests/integration/coverage.lcov

  # E2E tests coverage
  qlty coverage publish --tag=e2e tests/e2e/coverage.lcov
  ```
</CodeGroup>

## Tag Management

### Tags Persistence

Because Qlty supports selective testing with tags, tags "live forever" once created. This ensures that coverage information for each tag can be tracked and reported consistently over time, even when tests for certain tags aren't run on every commit.

### Deleting Tags

If you need to remove a tag that's no longer being used:

1. Navigate to your project in Qlty Cloud
2. Go to Project Settings → Code Coverage
3. Find the tag in the list of coverage tags
4. Click the "Delete" button next to the tag name

Note that deleting a tag will remove all historical coverage data associated with that tag, so use this option with caution.

## Troubleshooting

### Tag Reporting Issues

If you're experiencing issues with tagged coverage reports:

1. Verify that the tag name is consistent across all commands
2. Ensure you're providing the correct tag when using `coverage complete` commands
3. Check that the tag name doesn't contain special characters or spaces

### Missing Tag Data

If coverage data for a specific tag isn't appearing:

1. Confirm that the coverage report was successfully uploaded
2. Verify that the correct tag was specified in the upload command
3. For reports using server-side merging, check that the completion signal was sent
4. Ensure all parts of a tagged report have been uploaded if using the `total-parts-count` approach

## See Also

* [Coverage Merging](/coverage/merging) - How to merge multiple coverage reports
* [CI Integration](/coverage/ci) - Automate coverage reporting in CI
* [Path Fixing](/coverage/ci#path-fixing) - Fix path discrepancies in reports