From 9adae9a889e26bf86765a6e9a221503e15eb347f Mon Sep 17 00:00:00 2001 From: Roland Tritsch Date: Tue, 23 Jul 2024 15:34:02 +0100 Subject: [PATCH 1/2] README: Fix maven badge. Use footnotes for links. Reformat/Refresh. --- README.md | 143 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 84 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 25cd9c0..109dc5e 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,20 @@ # sbt-scoverage -[![Gitter](https://img.shields.io/gitter/room/scoverage/scoverage.svg)](https://gitter.im/scoverage/scoverage) -[![Maven Central](https://img.shields.io/github/v/release/scoverage/sbt-scoverage?label=maven-central)](https://search.maven.org/artifact/org.scoverage/sbt-scoverage/) -[![License](http://img.shields.io/:license-Apache%202-red.svg)](http://www.apache.org/licenses/LICENSE-2.0.txt) +[![gitter-badge][]][gitter] +[![maven-badge][]][maven] +[![license-badge][]][license] -sbt-scoverage is an sbt plugin that offers support for Scala code coverage using -[scoverage](https://github.com/scoverage/scalac-scoverage-plugin). This plugin -supports Scala 2.12, 2.13, and 3. +sbt-scoverage is an sbt plugin that offers support for Scala code +coverage using [scoverage][]. This plugin supports Scala 2.12, 2.13, +and 3. -**NOTE**: that ScalaJS and Scala Native support is limited to Scala 2. -**NOTE**: that Scala 3 support starts with 3.2.x. +**NOTE**: ScalaJS and Scala Native support is limited to Scala 2. + +**NOTE**: Scala 3 support starts with 3.2.x. ## Setup -**Requirements**: Requires sbt 1.2.8 or above +**Requirements**: Requires sbt 1.2.8 or above. In `project/plugins.sbt`: ```scala @@ -46,40 +47,43 @@ To generate the coverage reports run sbt coverageReport ``` -Coverage reports will be in your `target/scala-/scoverage-report` -directory. There are HTML and XML reports. The XML is useful if you need to -programatically use the results, or if you're writing a tool. +Coverage reports will be in your +`target/scala-/scoverage-report` directory. There are +HTML and XML reports. The XML is useful if you need to programatically +use the results, or if you're writing a tool. -**NOTE**: If you're running the coverage reports from within an sbt console -session (as opposed to one command per sbt launch), then the `coverage` command -is sticky. To turn it back off when you're done running reports, use the -`coverageOff` command or reset `coverageEnabled` with `set coverageEnabled := -false`. +**NOTE**: If you're running the coverage reports from within an sbt +console session (as opposed to one command per sbt launch), then the +`coverage` command is sticky. To turn it back off when you're done +running reports, use the `coverageOff` command or reset +`coverageEnabled` with `set coverageEnabled := false`. ### Multi project reports -By default, scoverage will generate reports for each project separately. You can -merge them into an aggregated report by using the following: +By default, scoverage will generate reports for each project +separately. You can merge them into an aggregated report by using the +following: ``` $ sbt coverageAggregate ``` -**NOTE**: You do not need to run `coverageReport` before `coverageAggregate`; it -aggregates over the sub-projects' coverage data directly, not the report xml. +**NOTE**: You do not need to run `coverageReport` before +`coverageAggregate`; it aggregates over the sub-projects' coverage +data directly, not the report xml. ### Exclude classes and packages and files -You can exclude classes from being considered for coverage measurement by -providing semicolon-separated list of regular expressions. +You can exclude classes from being considered for coverage measurement +by providing semicolon-separated list of regular expressions. ```scala coverageExcludedPackages := ";Reverse.*;.*AuthService.*;models\\.data\\..*" ``` -The regular expressions are matched against the fully qualified class name, and -must match the entire string to take effect. Any matched classes will not be -instrumented or included in the coverage report. +The regular expressions are matched against the fully qualified class +name, and must match the entire string to take effect. Any matched +classes will not be instrumented or included in the coverage report. You can also exclude files and file paths. @@ -87,9 +91,10 @@ You can also exclude files and file paths. coverageExcludedFiles := ".*\\/two\\/GoodCoverage;.*\\/three\\/.*" ``` -Note: The `.scala` file extension needs to be omitted from the filename, if one is given. +**NOTE**: The `.scala` file extension needs to be omitted from the +filename, if one is given. -Note: These two options only work for Scala2 and Scala 3.4.2+. +**NOTE**: These two options only work for Scala2 and Scala 3.4.2+. You can also mark sections of code with comments like: @@ -102,7 +107,7 @@ You can also mark sections of code with comments like: Any code between two such comments will not be instrumented or included in the coverage report. -Note: Comments exclusion works only for Scala2. +**NOTE**: Comments exclusion works only for Scala2. ### Minimum coverage @@ -118,13 +123,14 @@ coverageMinimumStmtPerFile := 85 coverageMinimumBranchPerFile := 80 ``` -These settings will be enforced when the reports are generated. If you generate -an aggregate report using `coverageAggregate` then these settings will apply to -that report. +These settings will be enforced when the reports are generated. If +you generate an aggregate report using `coverageAggregate` then these +settings will apply to that report. ### Override Location for Coverage Data And Report -If desired, one could override the default location for generating the sbt report and data through setting `coverageDataDir`: +If desired, one could override the default location for generating the +sbt report and data through setting `coverageDataDir`: Example in data-dir test: ```scala @@ -138,49 +144,68 @@ set coverageDataDir := file("/tmp") ## Trouble-shooting failing tests -scoverage does a lot of file writing behind the scenes in order to track which -statements have been executed. If you are running into a scenario where your -tests normally pass, but fail when scoverage is enabled, then the culprit can be -one of the following: +scoverage does a lot of file writing behind the scenes in order to +track which statements have been executed. If you are running into a +scenario where your tests normally pass, but fail when scoverage is +enabled, then the culprit can be one of the following: -* timing issues on futures and other async operations, try upping the timeouts by an order of magnitude. -* tests are run in a sandbox mode (such as with `java.security.PrivilegedAction`), try running the tests outside of the sandbox. +* timing issues on futures and other async operations, try upping the + timeouts by an order of magnitude. +* tests are run in a sandbox mode (such as with + `java.security.PrivilegedAction`), try running the tests outside + of the sandbox. ## Example project -[the scoverage samples project](https://github.com/scoverage/sbt-scoverage-samples). +To see the plugin in action you can checkout the scoverage [samples][] +project. ## Integrations ### Codacy -[Codacy](https://www.codacy.com) integrates with your favorite coverage tool to -provide an in-depth overlook of your project status. scoverage information can -be integrated into Codacy through the -[codacy-coverage-reporter](https://github.com/codacy/codacy-coverage-reporter). +[Codacy][] integrates with your favorite coverage tool to provide an +in-depth overlook of your project status. scoverage information can be +integrated into Codacy through the [codacy-coverage-reporter][]. ### Coveralls -If you have an open source project then you can add code coverage metrics with -the [Coveralls](https://coveralls.io/). scoverage will integrate with coveralls -using the [sbt-coveralls](https://github.com/scoverage/sbt-coveralls) plugin. +If you have an open source project then you can publish the code +coverage metrics with [Coveralls][]. This plugin will integrate with +coveralls using the [sbt-coveralls][] plugin. ### Codecov -You can integrate with [Codecov](https://about.codecov.io/) easily sending your -reports there via your CI. You can see an example of this here in -[codecov/example-scala](https://github.com/codecov/example-scala). +You can also integrate with [Codecov][] by sending your reports there +via your CI. You can see an example in [codecov-example-scala][]. -### Plugin for SonarQube +### SonarQube -If you want to visually browse statement coverage reports then use this [plugin -for SonarQube](https://github.com/RadoBuransky/sonar-scoverage-plugin). It -allows you to review overall project statement coverage as well as dig deeper -into sub-modules, directories and source code files to see uncovered statements. -Statement coverage measurement can become an integral part of your team's -continuous integration process and a required quality standard. +If you want to visually browse coverage reports then you can use the +[SonarQube][] plugin. It allows you to review overall project +statement coverage as well as dig deeper into sub-modules, directories +and source code files to see uncovered statements. Statement coverage +measurement can become an integral part of your team's continuous +integration process and a required quality standard. ## Release Notes -For any information on releases and upgrading, please refer to the [release -page](https://github.com/scoverage/sbt-scoverage/releases). +For any information on releases and upgrading, please refer to the +[release][] page. + +[gitter]: https://gitter.im/scoverage/scoverage +[gitter-badge]: https://img.shields.io/gitter/room/scoverage/scoverage.svg +[maven]: https://search.maven.org/artifact/org.scoverage/sbt-scoverage +[maven-badge]: https://index.scala-lang.org/scoverage/sbt-scoverage/sbt-scoverage/latest.svg&label=maven-central +[license]: http://www.apache.org/licenses/LICENSE-2.0.txt +[license-badge]: http://img.shields.io/:license-Apache%202-red.svg +[scoverage]: https://github.com/scoverage/scalac-scoverage-plugin +[samples]: https://github.com/scoverage/sbt-scoverage-samples +[codacy-coverage-reporter]: https://github.com/codacy/codacy-coverage-reporter +[Codacy]: https://www.codacy.com +[Coveralls]: https://coveralls.io +[sbt-coveralls]: https://github.com/scoverage/sbt-coveralls +[Codecov]: https://about.codecov.io +[codecov-example-scala]: https://github.com/codecov/example-scala +[SonarQube]: https://github.com/RadoBuransky/sonar-scoverage-plugin +[release]: https://github.com/scoverage/sbt-scoverage/releases From a211ec53832f5cec1a3173aa35c3c85db72274d7 Mon Sep 17 00:00:00 2001 From: Roland Tritsch Date: Tue, 23 Jul 2024 15:37:29 +0100 Subject: [PATCH 2/2] README: Fix maven badge. Use footnotes for links. Reformat/Refresh. --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 109dc5e..7b04f1a 100644 --- a/README.md +++ b/README.md @@ -193,19 +193,19 @@ integration process and a required quality standard. For any information on releases and upgrading, please refer to the [release][] page. -[gitter]: https://gitter.im/scoverage/scoverage -[gitter-badge]: https://img.shields.io/gitter/room/scoverage/scoverage.svg -[maven]: https://search.maven.org/artifact/org.scoverage/sbt-scoverage -[maven-badge]: https://index.scala-lang.org/scoverage/sbt-scoverage/sbt-scoverage/latest.svg&label=maven-central -[license]: http://www.apache.org/licenses/LICENSE-2.0.txt -[license-badge]: http://img.shields.io/:license-Apache%202-red.svg -[scoverage]: https://github.com/scoverage/scalac-scoverage-plugin -[samples]: https://github.com/scoverage/sbt-scoverage-samples -[codacy-coverage-reporter]: https://github.com/codacy/codacy-coverage-reporter [Codacy]: https://www.codacy.com -[Coveralls]: https://coveralls.io -[sbt-coveralls]: https://github.com/scoverage/sbt-coveralls [Codecov]: https://about.codecov.io -[codecov-example-scala]: https://github.com/codecov/example-scala +[Coveralls]: https://coveralls.io [SonarQube]: https://github.com/RadoBuransky/sonar-scoverage-plugin +[codacy-coverage-reporter]: https://github.com/codacy/codacy-coverage-reporter +[codecov-example-scala]: https://github.com/codecov/example-scala +[gitter-badge]: https://img.shields.io/gitter/room/scoverage/scoverage.svg +[gitter]: https://gitter.im/scoverage/scoverage +[license-badge]: http://img.shields.io/:license-Apache%202-red.svg +[license]: http://www.apache.org/licenses/LICENSE-2.0.txt +[maven-badge]: https://index.scala-lang.org/scoverage/sbt-scoverage/sbt-scoverage/latest.svg +[maven]: https://search.maven.org/artifact/org.scoverage/sbt-scoverage [release]: https://github.com/scoverage/sbt-scoverage/releases +[samples]: https://github.com/scoverage/sbt-scoverage-samples +[sbt-coveralls]: https://github.com/scoverage/sbt-coveralls +[scoverage]: https://github.com/scoverage/scalac-scoverage-plugin