https://github.com/mcarvin8/apex-code-coverage-transformer
Transform Salesforce Apex code coverage JSONs created during deployments and test runs into other formats accepted by SonarQube, GitHub, GitLab, Azure, Bitbucket, etc.
https://github.com/mcarvin8/apex-code-coverage-transformer
apex clover cobertura code-coverage code-quality continuous-integration jacoco lcov sonarqube
Last synced: 2 months ago
JSON representation
Transform Salesforce Apex code coverage JSONs created during deployments and test runs into other formats accepted by SonarQube, GitHub, GitLab, Azure, Bitbucket, etc.
- Host: GitHub
- URL: https://github.com/mcarvin8/apex-code-coverage-transformer
- Owner: mcarvin8
- License: mit
- Created: 2024-02-07T17:26:03.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-10T04:45:05.000Z (2 months ago)
- Last Synced: 2025-04-10T05:37:16.940Z (2 months ago)
- Topics: apex, clover, cobertura, code-coverage, code-quality, continuous-integration, jacoco, lcov, sonarqube
- Language: TypeScript
- Homepage:
- Size: 1.76 MB
- Stars: 14
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# `apex-code-coverage-transformer`
[](https://www.npmjs.com/package/apex-code-coverage-transformer) [](https://npmjs.org/package/apex-code-coverage-transformer) [](https://raw.githubusercontent.com/mcarvin8/apex-code-coverage-transformer/main/LICENSE.md)
Table of Contents
- [Install](#install)
- [Usage](#usage)
- [Salesforce CLI](#salesforce-cli)
- [SFDX Hardis](#sfdx-hardis)
- [Fixes and Enhancements](#fixes-and-enhancements)
- [Command](#command)
- [`sf acc-transformer transform`](#sf-acc-transformer-transform)
- [Coverage Report Formats](#coverage-report-formats)
- [Hook](#hook)
- [Troubleshooting](#troubleshooting)
- [Issues](#issues)
- [Contributing](#contributing)
- [License](#license)
Transform the Salesforce Apex code coverage JSON files created during deployments and test runs into other [formats](#coverage-report-formats) accepted by SonarQube, GitHub, GitLab, Azure, Bitbucket, etc.
> If there's a coverage format not yet supported by this plugin, feel free to provide a pull request or issue for the coverage format.
## Install
```bash
sf plugins install [email protected]
```
## Usage
This plugin is designed for users deploying Apex or running Apex tests within Salesforce DX projects (`sfdx-project.json`). It transforms Salesforce CLI JSON coverage reports into formats recognized by external tools.
The plugin ensures that coverage data is only reported for files found in your package directories, preventing mismatches in tools like SonarQube. If Apex files are missing from your project (i.e. Apex from managed or unlocked packages), they will be excluded from the transformed report with a [warning](#troubleshooting).
To automate coverage transformation after deployments or test executions, see [Hook](#hook).
### Salesforce CLI
> This plugin will only support the "json" coverage format from the Salesforce CLI. Do not use other coverage formats from the Salesforce CLI.
To create the code coverage JSON when deploying or validating, append `--coverage-formatters json --results-dir "coverage"` to the `sf project deploy` command. This will create a coverage JSON in this relative path - `coverage/coverage/coverage.json`.
```
sf project deploy [start/validate/report/resume] --coverage-formatters json --results-dir "coverage"
```
To create the code coverage JSON when running tests directly in the org, append `--code-coverage --output-dir "coverage"` to the `sf apex run test` or `sf apex get test` command. This will create the code coverage JSON in this relative path - `coverage/test-result-codecoverage.json`
```
sf apex run test --code-coverage --output-dir "coverage"
sf apex get test --test-run-id --code-coverage --output-dir "coverage"
```
### SFDX Hardis
This plugin can be used after running the below [sfdx-hardis](https://github.com/hardisgroupcom/sfdx-hardis) commands:
- `sf hardis project deploy smart` (only if `COVERAGE_FORMATTER_JSON=true` environment variable is defined)
- `sf hardis org test apex`
Both hardis commands will create the code coverage JSON to transform here: `hardis-report/apex-coverage-results.json`.
## Fixes and Enhancements
- **Maps Apex file names** in the original coverage report (e.g., `no-map/AccountTriggerHandler`) to their corresponding relative file paths in the Salesforce DX project (e.g., `force-app/main/default/classes/AccountTriggerHandler.cls`).
- **Normalizes coverage reports** across both deploy and test commands, improving compatibility with external tools.
- **Adds additional coverage formats** not available in the default Salesforce CLI deploy and test commands.
- **"Fixes" inaccuracies** in Salesforce CLI deploy command coverage reports, such as out-of-range covered lines (e.g., line 100 reported as "covered" in a 98-line Apex class) and incorrect total line counts (e.g., 120 lines reported for a 100-line Apex class).
- To address these inaccuracies, the plugin includes a **re-numbering function** that only applies to deploy coverage reports. This function reassigns out-of-range `covered` lines to unused lines, ensuring reports are accepted by external tools.
- The `uncovered` lines are always correctly reported by the deploy command.
- Once Salesforce resolves the issue with the API that affects deploy command coverage reports, the re-numbering function will be removed in a future **breaking** release.
- See issues [5511](https://github.com/forcedotcom/salesforcedx-vscode/issues/5511) and [1568](https://github.com/forcedotcom/cli/issues/1568) for more details.
- **Note**: This does not affect coverage reports generated by the Salesforce CLI test commands.
## Command
The `apex-code-coverage-transformer` has 1 command:
- `sf acc-transformer transform`
## `sf acc-transformer transform`
```
USAGE
$ sf acc-transformer transform -j [-r ] [-f ] [-i ] [--json]
FLAGS
-j, --coverage-json= Path to the code coverage JSON file created by the Salesforce CLI deploy or test command.
-r, --output-report= Path to the code coverage file that will be created by this plugin.
[default: "coverage.[xml/info]"]
-f, --format= Output format for the code coverage format.
[default: "sonar"]
-i, --ignore-package-directory= Package directory to ignore when looking for matching files in the coverage report.
Should be as they appear in the "sfdx-project.json".
Can be declared multiple times.
GLOBAL FLAGS
--json Format output as json.
EXAMPLES
Transform the JSON into Sonar format:
$ sf acc-transformer transform -j "coverage.json" -r "coverage.xml" -f "sonar"
Transform the JSON into Cobertura format:
$ sf acc-transformer transform -j "coverage.json" -r "coverage.xml" -f "cobertura"
Transform the JSON into Clover format:
$ sf acc-transformer transform -j "coverage.json" -r "coverage.xml" -f "clover"
Transform the JSON into LCovOnly format:
$ sf acc-transformer transform -j "coverage.json" -r "coverage.info" -f "lcovonly"
Transform the JSON into Sonar format, ignoring Apex in the "force-app" directory:
$ sf acc-transformer transform -j "coverage.json" -i "force-app"
```
## Coverage Report Formats
The `-f`/`--format` flag allows you to specify the format of the transformed coverage report.
| Flag Option | Description |
| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [sonar](https://raw.githubusercontent.com/mcarvin8/apex-code-coverage-transformer/main/test/sonar_baseline.xml) | Generates a SonarQube-compatible coverage report. This is the default option. |
| [clover](https://raw.githubusercontent.com/mcarvin8/apex-code-coverage-transformer/main/test/clover_baseline.xml) | Produces a Clover XML report format, commonly used with Atlassian tools. |
| [lcovonly](https://raw.githubusercontent.com/mcarvin8/apex-code-coverage-transformer/main/test/lcov_baseline.info) | Outputs coverage data in LCOV format, useful for integrating with LCOV-based tools. |
| [cobertura](https://raw.githubusercontent.com/mcarvin8/apex-code-coverage-transformer/main/test/cobertura_baseline.xml) | Creates a Cobertura XML report, a widely used format for coverage reporting. |
| [jacoco](https://raw.githubusercontent.com/mcarvin8/apex-code-coverage-transformer/main/test/jacoco_baseline.xml) | Creates a JaCoCo XML report, the standard for Java projects. |
## Hook
To enable automatic transformation after the below `sf` commands complete, create a `.apexcodecovtransformer.config.json` in your project’s root directory.
- `sf project deploy [start/validate/report/resume]`
- `sf apex run test`
- `sf apex get test`
- `sf hardis project deploy smart`
- only if `sfdx-hardis` is installed
- `COVERAGE_FORMATTER_JSON=true` must be set in the environment variables
- `sf hardis org test apex`
- only if `sfdx-hardis` is installed
You can copy & update the sample [Salesforce CLI .apexcodecovtransformer.config.json](https://raw.githubusercontent.com/mcarvin8/apex-code-coverage-transformer/main/defaults/salesforce-cli/.apexcodecovtransformer.config.json), which assumes you are running the Salesforce CLI commands and specifying the `--results-dir`/`--output-dir` directory as "coverage".
You can copy & update the sample [SFDX Hardis .apexcodecovtransformer.config.json](https://raw.githubusercontent.com/mcarvin8/apex-code-coverage-transformer/main/defaults/sfdx-hardis/.apexcodecovtransformer.config.json), which assumes you are running the SFDX Hardis commands.
**`.apexcodecovtransformer.config.json` structure**
| JSON Key | Required | Description |
| -------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
| `deployCoverageJsonPath` | Yes (for deploy command) | Code coverage JSON created by the Salesforce CLI deploy commands. |
| `testCoverageJsonPath` | Yes (for test command) | Code coverage JSON created by the Salesforce CLI test commands. |
| `outputReportPath` | No (defaults to `coverage.[xml/info]`) | Transformed code coverage report path. |
| `format` | No (defaults to `sonar`) | Transformed code coverage report [format](#coverage-report-formats). |
| `ignorePackageDirectories` | No | Comma-separated string of package directories to ignore when looking for matching Apex files. |
## Troubleshooting
If a file listed in the coverage JSON cannot be found in any package directory, a warning is displayed, and the file will not be included in the transformed report:
```
Warning: The file name AccountTrigger was not found in any package directory.
```
If **none** of the files in the coverage JSON are found in a package directory, the plugin will print an additional warning, and the generated report will be empty:
```
Warning: The file name AccountTrigger was not found in any package directory.
Warning: The file name AccountProfile was not found in any package directory.
Warning: None of the files listed in the coverage JSON were processed. The coverage report will be empty.
```
Salesforce CLI generates code coverage JSONs in two different structures (deploy and test command formats). If the provided coverage JSON does not match one of these expected structures, the plugin will fail with:
```
Error (1): The provided JSON does not match a known coverage data format from the Salesforce deploy or test command.
```
If `sfdx-project.json` file is missing from the project root, the plugin will fail with:
```
Error (1): sfdx-project.json not found in any parent directory.
```
If a package directory listed in `sfdx-project.json` cannot be found, the plugin will encounter a **ENOENT** error:
```
Error (1): ENOENT: no such file or directory: {packageDir}
```
## Issues
If you encounter any issues or would like to suggest features, please create an [issue](https://github.com/mcarvin8/apex-code-coverage-transformer/issues).
## Contributing
Contributions are welcome! See [Contributing](https://github.com/mcarvin8/apex-code-coverage-transformer/blob/main/CONTRIBUTING.md).
## License
This project is licensed under the MIT license. Please see the [LICENSE](https://raw.githubusercontent.com/mcarvin8/apex-code-coverage-transformer/main/LICENSE.md) file for details.