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.

1# .github/workflows/test.yml
2name: Test and Coverage
3
4on:
5 push:
6 branches: [ main ]
7 pull_request:
8 branches: [ main ]
9
10permissions:
11 contents: read
12 id-token: write # Required for OIDC
13
14jobs:
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
2name: Test and Coverage
3
4on:
5 push:
6 branches: [ main ]
7 pull_request:
8 branches: [ main ]
9
10jobs:
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:

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

Manual Integration

If you prefer not to use the orb:

1version: 2.1
2
3jobs:
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
24workflows:
25 main:
26 jobs:
27 - test

Travis CI

Add Qlty coverage reporting to your .travis.yml:

1language: node_js
2node_js:
3 - 16
4
5script:
6 - npm test -- --coverage
7
8after_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:

1test:
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.

Azure DevOps

Add the following steps to your Azure Pipelines YAML file:

1steps:
2- task: NodeTool@0
3 inputs:
4 versionSpec: '16.x'
5 displayName: 'Install Node.js'
6
7- script: npm ci
8 displayName: 'Install dependencies'
9
10- script: npm test -- --coverage
11 displayName: 'Run tests with coverage'
12
13- script: |
14 curl https://qlty.sh | sh
15 qlty coverage publish coverage/lcov.info
16 displayName: 'Upload coverage to Qlty'
17 env:
18 QLTY_COVERAGE_TOKEN: $(QLTY_COVERAGE_TOKEN)

Add your coverage token as a pipeline variable.

Buildkite

Add the following steps to your pipeline.yml:

1steps:
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

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
  • Azure DevOps
  • Buildkite
  • Jenkins
  • AppVeyor
  • Bitbucket Pipelines
  • AWS CodeBuild
  • Drone CI

If you’re using another CI provider, you may need to manually specify branch and commit information.

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 and --override-commit-sha if CI detection fails

Debug Mode

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

$QLTY_DEBUG=true qlty coverage publish coverage.lcov

See Also