omni-coveragereporter-maven-plugin

A plugin intended to keep the pace of technology and be able to use the Coveralls platform as Java/Scala/Kotlin updates move onwwards

Features

1. Reporting file supported

Type	Status	Notes	Available from Release	Example Project
Jacoco XML	✅	Jacoco reports seem to report on nonexistent classes in some cases. This seems to happen with Kotlin. This breaks down the functionality of some plugins. In this version we are allowed to ignore this, since it does not affect most reports.	0.0.0
Clover XML	✅		0.1.0
LCov Info	✅		0.1.0
Coverage Py JSON	✅		0.1.0
Jacoco Exec	✅		0.1.0
Coverage Codecov	✅	For unsupported formats, Omni makes the conversion to the generic supported Codecov format (only from known formats to Omni)	0.1.0

NOTE - Only reports generated within maven build folders will be taken automatically in the report parsing, generating and sending. If you want to consider external reports then you need to configure external folders with options extraSourceFolders and extraReportFolders. See below for the generic configuration details or check a real example on project

2. Online API's supported

Type	Status	Notes	Environment Variables	Available from Release
Coveralls	✅		COVERALLS_REPO_TOKEN or COVERALLS_TOKEN	0.0.0
Codacy	✅		CODACY_PROJECT_TOKEN	0.0.7
Codacy API	✅		All of these: CODACY_API_TOKEN, CODACY_ORGANIZATION_PROVIDER, CODACY_USERNAME, CODACY_PROJECT_NAME. It has Priority over CODACY_PROJECT_TOKEN	0.0.9
CodeCov	✅		CODECOV_TOKEN	0.0.9

3. Pipelines Supported

Type	Status	Notes	Available from Release	Example project
Local	✅		0.0.0	N/A
Git Hub	✅		0.0.1
Git Lab	✅		0.0.1
CircleCI	✅		0.1.3
BitBucket	✅		0.1.3

4. Configuration options

Property	Function	Available from Release
failOnUnknown	If an unknown file is found, it will ignore current file and proceed with reporting the rest. It is false by default	0.0.0
failOnNoEncoding	If an explicit encoding is not found, the reporting process will continue. It will fail only should an invalid character be found. Active this if you want the plugin to fail if configuration is not found. It is false by default	?
failOnReportNotFound	If a particular report is not generated, we may not want our process to continue. For the most cases though we may just want a warning about this. It is false by default	0.0.7
failOnReportSendingError	If a particular report has failed to be sent, we may not want our process to continue. For the most cases though we may just want a warning about this. It is false by default	0.0.7
failOnXmlParsingError	If the process fails to parse a Jacoco file, we may not want our process to continue. For the most cases though we may just want a warning about this. It is false by default	0.0.8
disableCoveralls	By default it is set to false. If variables COVERALLS_REPO_TOKEN or COVERALLS_TOKEN are available, Omni reporter will try to send the report to Coveralls. However, you can also prevent this behaviour if you set this to true	0.0.8
disableCodacy	By default it is set to false. If variable CODACY_PROJECT_TOKEN is available, Omni reporter will try to send the report to Codacy. However, you can also prevent this behaviour if you set this to true	0.0.8
disableCodecov	By default it is set to false. If variable CODECOV_TOKEN is available, Omni reporter will try to send the report to Codecov. However, you can also prevent this behaviour if you set this to true	0.0.9
ignoreTestBuildDirectory	By default it is set to true. There is normally no reason to include test reporting files. If you do, however, you can set this flag to false.	0.0.2
branchCoverage	By default it is set to false. If you want include branch coverage in your reporting please activate this flag.	?
useCoverallsCount	By default it is set to true. If you want to let the pipeline determine the numbering for your Job Id and run, then set this to false. It will then search those values via environment variables.	0.0.3
fetchBranchNameFromEnv	Some Coverage frameworks may present the commit hash instead of the branch name under different circumstances. It can vary if you run your tests under Docker or it can vary under certain variable combinations. This flag is set to fals by default. If set to true, it will get the branch name from the pipeline environment variables.	0.0.3
extraSourceFolders	You may want to include extra Source folders for Omni to find. It is better to make sure that in your plugin, you can define and tell maven where are your extra source folders. This parameter is here available as a last resort , should you find a problem where the plugins just don't work the way you expect them to.	0.0.7
extraReportFolders	This is a list of extra report folders you can add for external reports unrelated to Maven. Sources wil be searched across the extraSourceFolders. The search algorithm is based on source file distances to the report. By default all report frameworks generate reports as close as possible to the source code. So keep in mind not to change that default configuration too much.	0.0.7
reportRejectList	This is a string list of reporting filenames you possibly want to reject in some cases (i.e. two different report types of different brands for the same files for the same cases)	0.1.3
coverallsUrl	Should Coveralls ever change the API endpoint, you can change that here	0.0.0
codacyUrl	Should Codacy ever change the API endpoint, you can change that here	0.0.7
codecovUrl	Should Codecov ever change the API endpoint, you can change that here	0.0.7
coverallsToken	Sets the coverallsToken manually. Use this for local tests only or if you have a globally variable not declared in versioned files. Using tokens explicitly in the maven pom.xml file is unsafe. Do NOT place your tokens in the clear. For production purposes use environment variables COVERALLS_REPO_TOKEN or COVERALLS_TOKEN instead	0.0.0
codacyToken	Sets the codacyToken token manually. Use this for local tests only or if you have a globally variable not declared in versioned files. Using tokens explicitly in the maven pom.xml file is unsafe. Do NOT place your tokens in the clear. For production purposes use environment variable CODACY_PROJECT_TOKEN instead	0.0.7
(*1) codacyApiToken	Sets the codacyApiToken token manually. Use this for local tests only or if you have a globally variable not declared in versioned files. Using tokens explicitly in the maven pom.xml file is unsafe. Do NOT place your tokens in the clear. For production purposes use environment variable CODACY_API_TOKEN instead	0.0.9
(*1) codacyOrganizationProvider	Sets the codacyOrganizationProvider token manually. Use this for local tests only or if you have a globally variable not declared in versioned files. Using tokens explicitly in the maven pom.xml file is unsafe. Do NOT place your tokens in the clear. For production purposes use environment variable CODACY_ORGANIZATION_PROVIDER instead	0.0.9
(*1) codacyUserName	Sets the codacyUserName token manually. Use this for local tests only or if you have a globally variable not declared in versioned files. Using tokens explicitly in the maven pom.xml file is unsafe. Do NOT place your tokens in the clear. For production purposes use environment variable CODACY_USERNAME instead	0.0.9
(*1) codacyProjectName	Sets the codacyProjectName token manually. Use this for local tests only or if you have a globally variable not declared in versioned files. Using tokens explicitly in the maven pom.xml file is unsafe. Do NOT place your tokens in the clear. For production purposes use environment variable CODACY_PROJECT_NAME instead	0.0.9
codecovToken	Sets the codecovToken token manually. Use this for local tests only or if you have a globally variable not declared in versioned files. Using tokens explicitly in the maven pom.xml file is unsafe. Do NOT place your tokens in the clear. For production purposes use environment variable CODECOV_TOKEN instead	0.0.9
parallelization	Parallelization - Indicates how big is the pool of threads available to process individual report files. Default value is 4	0.4.0

*N - These variables only work when fully configured in the N set.

5. How to run

mvn clean install
mvn omni-coveragereporter:report

6. Requirements

Java 11 and above only

Reading and interpreting report files

Jacoco Reports

• mi = missed instructions
• ci = covered instructions
• mb = missed branches
• cb = covered branches

Functionality description

1. Path Corrections for Codecov Jacoco reports
2. Codecov support for endpoint V4 version (*1)
3. API token support for codacy
4. Disable flags for Coveralls and Codacy to force them out even when environment variables are available
5. disableCoveralls
6. disableCodacy
7. Exception handling for Codacy formatting issue
8. failOnXmlParsingError, false by default
9. Codacy update so solve Xerces module error. Manual implementation required
10. Codacy support (*1)
11. failOnReportNotFound
12. failOnUnknown Bug fix
13. Possibility to add external root sources - useful in cases where projects are using scala, java, kotlin and/or clojure at the same time. The plugin only recognizes one source directory. Parameter name is extraSourceFolders
14. failOnReportSendingError
15. useCoverallsCount to let Coveralls decide Job and run numbers.
16. Ignore test build directory by default. Make ignoreTestBuildDirectory, true by default.
17. Find files in all sources directories including generated sources
18. Rejection words implemented. Fixes issue with GitHub pipelines build names for Coveralls Report
19. Token log Redacting (even in debug) for Coveralls Report
20. We can ignore unknown class error generated by Jacoco. This happens with some Kotlin code. The option is failOnUnknown
21. Saga and Cobertura support is not given because of the lack of updates in these plugins for more than 5 years.
22. Plugin will search for all jacoco.xml files located in the build directory.
23. If there are two reports with the same file reported, the result will be a sum.
24. Coveralls support (*1)
25. Line Coverage

*1 All of these requirements are part of Milestone 10, which comprises support for three reporting frameworks: Codecov, Codacy and Coveralls with focus on Jacoco Reports.

Release notes

For complete release notes logbook please check ReleaseNotes.md

How to use

1. Omni reporter

Just add the following dependency to your project to get coverage sent to coveralls

<plugin>
    <groupId>org.jesperancinha.plugins</groupId>
    <artifactId>omni-coveragereporter-maven-plugin</artifactId>
    <version>${omni-coveragereporter-maven-plugin.version}</version>
</plugin>

Don't forget to have the variables available in your environment for the API's you want to send your reports to.

If you want to be more specific in your configuration and need an example here is one of a fully configured plugin:

<plugin>
    <groupId>org.jesperancinha.plugins</groupId>
    <artifactId>omni-coveragereporter-maven-plugin</artifactId>
    <version>${omni-coveragereporter-maven-plugin.version}</version>
    <configuration>
        <failOnUnknown>false</failOnUnknown>
        <failOnNoEncoding>false</failOnNoEncoding>
        <failOnReportNotFound>false</failOnReportNotFound>
        <failOnReportSendingError>false</failOnReportSendingError>
        <failOnXmlParsingError>false</failOnXmlParsingError>
        <disableCoveralls>false</disableCoveralls>
        <disableCodacy>false</disableCodacy>
        <disableCodecov>false</disableCodecov>
        <ignoreTestBuildDirectory>true</ignoreTestBuildDirectory>
        <branchCoverage>false</branchCoverage>
        <useCoverallsCount>false</useCoverallsCount>
        <extraSourceFolders>${project.build.directory}/generated-sources/plugin</extraSourceFolders>
        <coverallsUrl>https://coveralls.io/api/v1/jobs</coverallsUrl>
        <codacyUrl>https://api.codacy.com</codacyUrl>
        <codecovUrl>https://codecov.io/upload</codecovUrl>
        <coverallsToken>AAAAAAAAAAAAAAAAAAA</coverallsToken>
        <codacyToken>AAAAAAAAAAAAAAAAAAA</codacyToken>
        <codacyApiToken>AAAAAAAAAAAAAAAAAAA</codacyApiToken>
        <codacyOrganizationProvider>AAAAAAAAAAAAAAAAAAA</codacyOrganizationProvider>
        <codacyUserName>AAAAAAAAAAAAAAAAAAA</codacyUserName>
        <codacyProjectName>AAAAAAAAAAAAAAAAAAA</codacyProjectName>
        <codecovToken>AAAAAAAAAAAAAAAAAAA</codecovToken>
        <fetchBranchNameFromEnv>true</fetchBranchNameFromEnv>
        <parallelization>4</parallelization>
        <extraSourceFolders>
            <param>${project.basedir}/source1</param>
            <param>${project.basedir}/source2</param>
            <param>${project.basedir}/source3</param>
            <param>${project.basedir}</param>
        </extraSourceFolders>
        <extraReportFolders>
            <param>${project.basedir}/folder1/coverage</param>
            <param>${project.basedir}/folder2/target</param>
            <param>${project.basedir}/folder3/build</param>
            <param>${project.basedir}/folder4/dist</param>
            <param>${project.basedir}/folder5/bin</param>
            <param>${project.basedir}</param>
        </extraReportFolders>
        <reportRejectList>
            <param>filename.extension</param>
        </reportRejectList>
    </configuration>
</plugin>

2. Jacoco Reports

You'll need Maven surefire plugin and the jacoco plugin. Here is an example:

<plugins>
    <plugin>
        <groupId>org.jacoco</groupId>
        <artifactId>jacoco-maven-plugin</artifactId>
        <version>${jacoco-maven-plugin.version}</version>
        <executions>
            <execution>
                <goals>
                    <goal>prepare-agent</goal>
                </goals>
            </execution>
            <execution>
                <id>report</id>
                <phase>test</phase>
                <goals>
                    <goal>report</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>${maven-surefire-plugin.version}</version>
    </plugin>
</plugins>

Troubleshooting

Having issues running this plugin? Please check the Troubleshooting.md document.

---

Test files

In all Omni projects, there are test files scattered all over the place. This is needed to see how the application behaves in different test scenarios. To keep things organized, this is the list of the files that are here specifically for test purposes:

• test
• test2
• test3
• test4

---

Repository ~/.m2/settings.xml

<?xml version="1.0" encoding="UTF-8" ?>
<settings xsi:schemaLocation='http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd'
          xmlns='http://maven.apache.org/SETTINGS/1.0.0' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
    <profiles>
        <profile>
            <id>ossrh</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <properties>
                <gpg.executable>gpg</gpg.executable>
                <gpg.passphrase>{{password}}</gpg.passphrase>
            </properties>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>ossrh</activeProfile>
    </activeProfiles>
    <servers>
        <server>
            <id>ossrh</id>
            <username>{{username}}</username>
            <password>{{password}}</password>
        </server>
    </servers>
</settings>

Coverage report Graphs

References

• Codacy Coverage Reporter
• Jackson Module
• XCode Environment Variable Reference
• Cross-CI reference
• Coveralls API reference
• Git Hub Environment Variables
• Git Lab Environment Variables
• Check Run Reporter
• Codacy Maven Plugin
• Coveralls Maven Plugin
• Example Java Maven for CodeCov
• CodeCov Maven Plugin

About me