Skip to main content

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.

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

​
Tags with Report Merging

Coverage tags work seamlessly with report 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: 
# 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

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

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

​
Common Use Cases for Tags

​
Multi-Language Projects

In projects with multiple programming languages, each with their own test frameworks: 
# 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

​
Monorepo with Multiple Components

For monorepos with distinct components that each need tracking: 
# 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

​
Different Test Types

When separating coverage by test type: 
# 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

​
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