CI Integration / Uploader

Integrating code coverage reporting into your CI pipeline ensures that coverage data is consistently collected and reported for every build.

Qlty is compatible with every major CI provider, and offers specific workflow support for GitHub (via a GitHub Action) and Circle CI (via an Orb).

CI Provider Integration

GitHub Actions

Use Qlty’s official GitHub Action for the simplest integration.

Using OIDC (Recommended)

1 # .github/workflows/test.yml
2 name: Test and Coverage
3 
4 on:
5   push:
6     branches: [ main ]
7   pull_request:
8     branches: [ main ]
9 
10 permissions:
11   contents: read
12   id-token: write # Required for OIDC
13 
14 jobs:
15   test:
16     runs-on: ubuntu-latest
17     steps:
18       - uses: actions/checkout@v3
19       
20       # Run your tests with coverage
21       - name: Run tests
22         run: npm test -- --coverage
23       
24       # Upload coverage to Qlty
25       - uses: qltysh/qlty-action/coverage@v1
26         with:
27           oidc: true
28           files: coverage/lcov.info

Using a Coverage Token

1 # .github/workflows/test.yml
2 name: Test and Coverage
3 
4 on:
5   push:
6     branches: [ main ]
7   pull_request:
8     branches: [ main ]
9 
10 jobs:
11   test:
12     runs-on: ubuntu-latest
13     steps:
14       - uses: actions/checkout@v3
15       
16       # Run your tests with coverage
17       - name: Run tests
18         run: npm test -- --coverage
19       
20       # Upload coverage to Qlty
21       - uses: qltysh/qlty-action/coverage@v1
22         with:
23           token: ${{ secrets.QLTY_COVERAGE_TOKEN }}
24           files: coverage/lcov.info

CircleCI

Qlty offers a CircleCI Orb for easy integration.

Using the Orb

Add the Qlty orb to your .circleci/config.yml:

1 version: 2.1
2 
3 orbs:
4   qlty: qltysh/qlty-orb@0.0
5 
6 jobs:
7   test:
8     docker:
9       - image: cimg/node:16.13
10     steps:
11       # Checkout is required
12       - checkout
13       - run:
14           name: Install dependencies
15           command: npm ci
16       - run:
17           name: Run tests with coverage
18           command: npm test
19       - qlty/coverage_publish:
20           files: coverage/lcov.info
21 
22 workflows:
23   main:
24     jobs:
25       - test

Manual Integration

If you prefer not to use the orb:

1 version: 2.1
2 
3 jobs:
4   test:
5     docker:
6       - image: cimg/node:16.13
7     steps:
8       - checkout
9       - run:
10           name: Install dependencies
11           command: npm ci
12       - run:
13           name: Run tests with coverage
14           command: npm test
15       - run:
16           name: Install Qlty CLI
17           command: curl https://qlty.sh | sh
18       - run:
19           name: Upload coverage
20           command: qlty coverage publish coverage/lcov.info
21           environment:
22             QLTY_COVERAGE_TOKEN: ${QLTY_COVERAGE_TOKEN}
23 
24 workflows:
25   main:
26     jobs:
27       - test

Travis CI

Add Qlty coverage reporting to your .travis.yml:

1 language: node_js
2 node_js:
3   - 16
4 
5 script:
6   - npm test -- --coverage
7 
8 after_success:
9   - curl https://qlty.sh | sh
10   - qlty coverage publish coverage/lcov.info

Make sure to add your QLTY_COVERAGE_TOKEN in the Travis CI repository settings.

GitLab CI

Add coverage reporting to your .gitlab-ci.yml:

1 test:
2   stage: test
3   script:
4     - npm ci
5     - npm test -- --coverage
6     - curl https://qlty.sh | sh
7     - qlty coverage publish coverage/lcov.info
8   artifacts:
9     paths:
10       - coverage/

Add your QLTY_COVERAGE_TOKEN as a CI/CD variable in your GitLab project settings.

Buildkite

Add the following steps to your pipeline.yml:

1 steps:
2   - label: "Run tests with coverage"
3     commands:
4       - npm ci
5       - npm test -- --coverage
6       
7   - label: "Upload coverage to Qlty"
8     commands:
9       - curl https://qlty.sh | sh
10       - qlty coverage publish coverage/lcov.info
11     env:
12       QLTY_COVERAGE_TOKEN: "${QLTY_COVERAGE_TOKEN}"

Advanced CI Configuration

Parallelized Tests

When running tests in parallel, you’ll need to merge the coverage reports before uploading. Qlty supports both client-side and server-side merging.

Client-side Merging

Collect all coverage reports into a single location and upload them together:

$ qlty coverage publish report1.lcov report2.lcov report3.lcov

Server-side Merging

Upload each part separately and specify the total number of parts:

$ # Part 1
> qlty coverage publish --total-parts-count=3 report1.lcov
> 
> # Part 2
> qlty coverage publish --total-parts-count=3 report2.lcov
> 
> # Part 3
> qlty coverage publish --total-parts-count=3 report3.lcov

Learn more about Coverage Merging.

Multiple Test Suites

If you have different types of tests (unit, integration, e2e), you can track them separately using coverage tags:

$ # Upload unit test coverage
> qlty coverage publish --tag=unit unit-coverage.lcov
> 
> # Upload integration test coverage
> qlty coverage publish --tag=integration integration-coverage.lcov

Learn more about Coverage Tags.

Path Fixing

If your coverage report contains absolute paths or paths that don’t match your repository structure:

$ # Remove a prefix from paths
> qlty coverage publish --strip-prefix=/absolute/path/to/project coverage.lcov
> 
> # Add a prefix to paths
> qlty coverage publish --add-prefix=src coverage.lcov

Learn more about Path Fixing.

Branch and Commit Detection

Qlty automatically detects branch names and commit SHAs from CI environment variables. If automatic detection fails, you can specify them manually:

$ qlty coverage publish --override-branch=feature/new-feature --override-commit-sha=abc123 coverage.lcov

CI Provider Detection

Qlty automatically detects and extracts metadata from these CI providers:

GitHub Actions
CircleCI
Travis CI
GitLab CI
Buildkite
Codefresh
Semaphore

If your CI provider is not listed above, double check our Qlty repository to see if an implementation has been added recently (and let us know so we can update our docs).

If your CI provider is not support, you’ll need to manually provide the following required arguments to qlty coverage publish:

--override-branch
--override-commit
--override-build-id

Troubleshooting

Common Issues

Authentication failures: Check that your token is correctly set as an environment variable
Report format not recognized: Make sure you’re using a supported coverage format
Path mismatches: Use the --strip-prefix and --add-prefix options to fix file paths
Missing metadata: Use --override-branch, --override-commit and --override-build-id if CI detection fails

Debug Mode

To get more information about what’s happening during upload:

$ QLTY_DEBUG=true qlty coverage publish coverage.lcov