Transform Salesforce Apex code coverage JSONs into other formats accepted by SonarQube, GitHub, GitLab, Azure, Bitbucket, etc.
npm install apex-code-coverage-transformer





A Salesforce CLI plugin that converts Apex code coverage JSON (from deploy or test runs) into formats used by SonarQube, Codecov, GitHub, GitLab, Azure DevOps, Bitbucket, and other tools. Use it to keep coverage in sync with your CI/CD and code quality pipelines.
> Missing an output format via --format? Open an issue or submit a pull request.
Table of Contents
- Prerequisites
- Install
- Quick Start
- Usage
- Salesforce CLI
- SFDX Hardis
- What This Plugin Fixes and Adds
- Command Reference
- sf acc-transformer transform
- Coverage Report Formats
- CI/CD Integration
- Codecov
- SonarQube
- GitHub Actions
- GitLab CI
- Automatic Transformation (Hook)
- Troubleshooting
- Contributing
- License
- Salesforce CLI (sf) installed
- Node.js 20.x or later
- A Salesforce DX project with sfdx-project.json and package directories
- Use only the json coverage formatter from the Salesforce CLI; other formatters are not supported
``bash`
sf plugins install apex-code-coverage-transformer@x.y.z
1. Generate Apex code coverage (JSON)
From tests:
`bash`
sf apex run test --code-coverage --output-dir "coverage"
Or from deploy/validate:
`bash`
sf project deploy start --coverage-formatters json --results-dir "coverage"
# or: sf project deploy validate --coverage-formatters json --results-dir "coverage"
2. Transform to your target format
Test output → coverage/test-result-codecoverage.json. Deploy output → coverage/coverage/coverage.json.
`bash
# SonarQube
sf acc-transformer transform -j "coverage/test-result-codecoverage.json" -r "coverage.xml" -f "sonar"
# Codecov (Cobertura)
sf acc-transformer transform -j "coverage/test-result-codecoverage.json" -r "coverage.xml" -f "cobertura"
# Multiple formats
sf acc-transformer transform -j "coverage/test-result-codecoverage.json" -f "sonar" -f "cobertura" -f "jacoco"
`
3. Upload to your tool
See CI/CD Integration for Codecov, SonarQube, GitHub Actions, and GitLab.
This plugin is for Salesforce DX projects (sfdx-project.json). It maps Apex names in the CLI coverage JSON to file paths in your package directories and only includes files that exist in those directories. Apex from managed or unlocked packages (not in your repo) is excluded and reported with a warning.
To run transformation automatically after deploy or test commands, use the Hook.
Deploy/validate — coverage path: coverage/coverage/coverage.json
`bash`
sf project deploy [start|validate|report|resume] --coverage-formatters json --results-dir "coverage"
Run tests — coverage path: coverage/test-result-codecoverage.json
`bash`
sf apex run test --code-coverage --output-dir "coverage"
sf apex get test --test-run-id
Works with sfdx-hardis:
- sf hardis project deploy smart (when COVERAGE_FORMATTER_JSON=true)sf hardis org test apex
-
Coverage file: hardis-report/apex-coverage-results.json.
- File mapping — Maps names like no-map/AccountTriggerHandler to paths like force-app/main/default/classes/AccountTriggerHandler.cls.
- Normalization — Aligns deploy and test coverage structures so external tools can consume them.
- Extra formats — Outputs Sonar, Cobertura, JaCoCo, LCOV, Clover, and more (see Coverage Report Formats).
- Deploy-coverage fixes — Corrects known CLI issues (e.g. out-of-range covered lines, wrong line counts) by re-numbering covered lines in deploy reports. Uncovered lines are already correct. This workaround will be removed in a future breaking release once Salesforce fixes the API; see forcedotcom/salesforcedx-vscode#5511 and forcedotcom/cli#1568. Test-command coverage is unaffected.
Single command: sf acc-transformer transform.
`
USAGE
$ sf acc-transformer transform -j
FLAGS
-j, --coverage-json=
-r, --output-report=
-f, --format=
Multiple formats append to filename, e.g. coverage-sonar.xml.
-i, --ignore-package-directory=
GLOBAL FLAGS
--json Output as JSON.
`
Use -f / --format to choose the output format. Multiple -f values produce multiple files with the format in the name (e.g. coverage-sonar.xml, coverage-cobertura.xml).
| Format | Description | Typical use | Example |
| ------------ | -------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------- |
| sonar | SonarQube generic coverage | SonarQube, SonarCloud | sf acc-transformer transform -j "coverage.json" -r "coverage.xml" -f "sonar" |sf acc-transformer transform -j "coverage.json" -r "coverage.xml" -f "cobertura"
| cobertura | Cobertura XML | Codecov, Azure, Jenkins, GitLab, GitHub | |sf acc-transformer transform -j "coverage.json" -r "coverage.xml" -f "jacoco"
| jacoco | JaCoCo XML | Codecov, Jenkins, Maven, Gradle | |sf acc-transformer transform -j "coverage.json" -r "coverage.info" -f "lcovonly"
| lcovonly | LCOV | Codecov, Coveralls, GitHub | |sf acc-transformer transform -j "coverage.json" -r "coverage.xml" -f "clover"
| clover | Clover XML | Bamboo, Bitbucket, Jenkins | |sf acc-transformer transform -j "coverage.json" -r "coverage.json" -f "json"
| json | Istanbul JSON | Istanbul/NYC, Codecov | |sf acc-transformer transform -j "coverage.json" -r "coverage.json" -f "json-summary"
| json-summary | JSON summary | Badges, PR comments | |sf acc-transformer transform -j "coverage.json" -r "coverage.json" -f "simplecov"
| simplecov | SimpleCov JSON | Codecov, Ruby tools | |sf acc-transformer transform -j "coverage.json" -r "coverage.xml" -f "opencover"
| opencover | OpenCover XML | Azure DevOps, VS, Codecov | |sf acc-transformer transform -j "coverage.json" -r "coverage.html" -f "html"
| html | HTML report | Browsers, CI artifacts | |
Cobertura is a good default. CLI upload:
`bash`
sf apex run test --code-coverage --output-dir "coverage"
sf acc-transformer transform -j "coverage/test-result-codecoverage.json" -r "coverage.xml" -f "cobertura"
codecovcli upload-process --file coverage.xml
GitHub Action:
`yaml`
name: Salesforce CI with Codecov
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Salesforce CLI
run: npm install -g @salesforce/cli
- name: Install Coverage Transformer Plugin
run: sf plugins install apex-code-coverage-transformer
- name: Authenticate to Salesforce
run: sf org login sfdx-url --sfdx-url-file ${{ secrets.SFDX_AUTH_URL }} --alias ci-org
- name: Run Apex Tests
run: sf apex run test --code-coverage --output-dir coverage --target-org ci-org
- name: Transform Coverage to Cobertura
run: sf acc-transformer transform -j "coverage/test-result-codecoverage.json" -r "coverage.xml" -f "cobertura"
- name: Upload to Codecov
uses: codecov/codecov-action@v4
with:
files: ./coverage.xml
flags: apex
token: ${{ secrets.CODECOV_TOKEN }}
Use the sonar format and upload using SonarQube's generic test coverage report formatter, sonar.coverageReportPaths.
Scanner:
`bash`
sf apex run test --code-coverage --output-dir "coverage"
sf acc-transformer transform -j "coverage/test-result-codecoverage.json" -r "coverage.xml" -f "sonar"
sonar-scanner \
-Dsonar.projectKey=your-project-key \
-Dsonar.sources=force-app \
-Dsonar.tests=force-app \
-Dsonar.test.inclusions=*/Test.cls \
-Dsonar.coverageReportPaths=coverage.xml \
-Dsonar.host.url=https://sonarqube.example.com \
-Dsonar.login=$SONAR_TOKEN
SonarCloud GitHub Action:
`yaml`
name: SonarCloud Analysis
on: [push, pull_request]
jobs:
sonarcloud:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Salesforce CLI
run: npm install -g @salesforce/cli
- name: Install Coverage Transformer Plugin
run: sf plugins install apex-code-coverage-transformer
- name: Authenticate to Salesforce
run: sf org login sfdx-url --sfdx-url-file ${{ secrets.SFDX_AUTH_URL }} --alias ci-org
- name: Run Apex Tests
run: sf apex run test --code-coverage --output-dir coverage --target-org ci-org
- name: Transform Coverage to Sonar Format
run: sf acc-transformer transform -j "coverage/test-result-codecoverage.json" -r "coverage.xml" -f "sonar"
- name: SonarCloud Scan
uses: SonarSource/sonarcloud-github-action@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
with:
args: >
-Dsonar.projectKey=your-project-key
-Dsonar.organization=your-org
-Dsonar.sources=force-app
-Dsonar.tests=force-app
-Dsonar.test.inclusions=*/Test.cls
-Dsonar.coverageReportPaths=coverage.xml
Use Cobertura (or LCOV) with a coverage summary action:
`yaml`
name: Salesforce CI with Coverage Report
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Salesforce CLI
run: npm install -g @salesforce/cli
- name: Install Coverage Transformer Plugin
run: sf plugins install apex-code-coverage-transformer
- name: Authenticate to Salesforce
run: sf org login sfdx-url --sfdx-url-file ${{ secrets.SFDX_AUTH_URL }} --alias ci-org
- name: Run Apex Tests
run: sf apex run test --code-coverage --output-dir coverage --target-org ci-org
- name: Transform Coverage to Cobertura
run: sf acc-transformer transform -j "coverage/test-result-codecoverage.json" -r "coverage.xml" -f "cobertura"
- name: Code Coverage Report
uses: irongut/CodeCoverageSummary@v1.3.0
with:
filename: coverage.xml
badge: true
format: markdown
output: both
- name: Add Coverage PR Comment
uses: marocchino/sticky-pull-request-comment@v2
if: github.event_name == 'pull_request'
with:
recreate: true
path: code-coverage-results.md
Cobertura for coverage in the UI:
`yaml
stages:
- test
apex-tests:
stage: test
image: node:20
before_script:
- npm install -g @salesforce/cli
- sf plugins install apex-code-coverage-transformer
- echo $SFDX_AUTH_URL | sf org login sfdx-url --sfdx-url-stdin --alias ci-org
script:
- sf apex run test --code-coverage --output-dir coverage --target-org ci-org
- sf acc-transformer transform -j "coverage/test-result-codecoverage.json" -r "coverage.xml" -f "cobertura"
coverage: '/TOTAL.*\s+(\d+%)$/'
artifacts:
reports:
coverage_report:
coverage_format: cobertura
path: coverage.xml
paths:
- coverage/
expire_in: 30 days
`
Create .apexcodecovtransformer.config.json in the project root to transform coverage automatically after:
- sf project deploy [start|validate|report|resume]sf apex run test
- sf apex get test
- sf hardis project deploy smart
- (if sfdx-hardis installed and COVERAGE_FORMATTER_JSON=true)sf hardis org test apex
- (if sfdx-hardis installed)
Sample configs: Salesforce CLI, SFDX Hardis.
| Key | Required | Description |
| -------------------------- | ---------- | -------------------------------------------------------- |
| deployCoverageJsonPath | For deploy | Path to deploy coverage JSON. |testCoverageJsonPath
| | For test | Path to test coverage JSON. |outputReportPath
| | No | Output path (default: coverage.[xml/info/json] by format). |format
| | No | Format(s), comma-separated (default: sonar). |ignorePackageDirectories
| | No | Comma-separated package directories to ignore. |
File not in package directory — File is omitted from the report and a warning is shown:
``
Warning: The file name AccountTrigger was not found in any package directory.
No files matched — Report will be empty:
``
Warning: None of the files listed in the coverage JSON were processed. The coverage report will be empty.
Unknown JSON structure — Input is not from deploy or test coverage:
``
Error (1): The provided JSON does not match a known coverage data format from the Salesforce deploy or test command.
Missing project config — Run from a directory that has (or has a parent with) sfdx-project.json:
``
Error (1): sfdx-project.json not found in any parent directory.
Missing package directory — A path in sfdx-project.json does not exist:
```
Error (1): ENOENT: no such file or directory: {packageDir}
Contributions are welcome. See CONTRIBUTING.md for setup, testing, and how to add new coverage formats.
MIT. See LICENSE.