Advanced Configuration

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:

1# Frontend coverage
2- uses: qltysh/qlty-action/coverage@v1
3  with:
4    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
5    files: frontend/coverage/lcov.info
6    tag: frontend
7
8# Backend coverage
9- uses: qltysh/qlty-action/coverage@v1
10  with:
11    token: ${{ secrets.QLTY_COVERAGE_TOKEN }} 
12    files: backend/coverage/coverage.xml
13    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:

1# Publish unit test coverage (combining multiple reports)
2- uses: qltysh/qlty-action/coverage@v1
3  with:
4    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
5    tag: unit
6    files: |
7        unit1.lcov
8        unit2.lcov
9
10# Publish integration test coverage (combining multiple reports)
11- uses: qltysh/qlty-action/coverage@v1
12  with:
13    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
14    tag: integration
15    files: |
16        integration1.lcov
17        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:

1# Integration tag example (1 of 4)
2- uses: qltysh/qlty-action/coverage@v1
3  with:
4    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
5    tag: integration
6    total-parts-count: 4
7    files: coverage.lcov
8# ... Three more `qltysh/qlty-action/coverage` steps for the `integration` tag ...
9
10# Unit tag example (1 of 2)
11- uses: qltysh/qlty-action/coverage@v1
12  with:
13    token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
14    tag: unit
15    total-parts-count: 2
16    files: coverage.lcov
17# ... 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 CLI
$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:

Qlty CLI
$# 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:

Qlty CLI
$# 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:

Qlty CLI
$# 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