Skip to content

Commit af9d4b9

Browse files
ckipp01ckipp01
authored
Merge pull request #346 from ckipp01/docs
Overhaul the README
2 parents db47a65 + 6d87354 commit af9d4b9

File tree

1 file changed

+66
-78
lines changed

1 file changed

+66
-78
lines changed

‎README.md

Lines changed: 66 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,19 @@
66

77
sbt-scoverage is a plugin for sbt that integrates the scoverage code coverage
88
library. Find out more about
9-
[scoverage](https://github.com/scoverage/scalac-scoverage-plugin).
9+
[scoverage here](https://github.com/scoverage/scalac-scoverage-plugin).
1010

11-
## How to use
11+
## Setup
1212

13-
Make sure your sbt version in project/build.properties:
14-
```scala
15-
sbt.version = 1.2.8
16-
```
13+
**Requirements**: Requires sbt 1.2.8 or above
1714

18-
Add the plugin in `project/plugins.sbt`:
19-
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.scoverage/sbt-scoverage/badge.svg?kill_cache=1)](https://search.maven.org/artifact/org.scoverage/sbt-scoverage/)
15+
In `project/plugins.sbt`:
2016
```scala
2117
addSbtPlugin("org.scoverage" % "sbt-scoverage" % "x.x.x")
2218
```
2319

20+
## Usage
21+
2422
Run the tests with enabled coverage:
2523
```
2624
$ sbt clean coverage test
@@ -40,58 +38,40 @@ To generate the coverage reports run
4038
$ sbt coverageReport
4139
```
4240

43-
Coverage reports will be in `target/scala-<scala-version>/scoverage-report`. 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.
44-
45-
If you're running the coverage reports from within an sbt console session (as
46-
opposed to one command per sbt launch), then the `coverage` command is sticky. To
47-
turn it back off when you're done running reports, use the `coverageOff` command or reset `coverageEnabled` with `set coverageEnabled := false`.
48-
49-
Sample project with scoverage in both sbt and maven - [the scoverage samples project](https://github.com/scoverage/sbt-scoverage-samples).
50-
51-
## Notes on upgrading to version 1.6.x
52-
* ´coverageCleanSubprojectFiles´ key has been removed
53-
* scala version 2.12+ is required as a minimum (due to scoverage suppport)
54-
55-
## Notes on upgrading to version 1.6.0
56-
57-
* `coverageAggregate` aggregates raw coverage data, not coverage xml reports for modules.
58-
There is no requirement to generate individual coverage reports for modules (`coverageReport`)
59-
before generating aggregated report (`coverageAggregate`).
60-
61-
If only aggregated report is required, not executing `coverageReport` can reduce the build time significantly.
62-
63-
## Notes on upgrading to version 1.3.0
64-
65-
* The object containing the keys has changed from nested to top level so you might need to adjust the import. It's also an auto plugin now, so you might not need the import at all.
66-
* There is an issue syncing the binary with the sbt-plugin-releases repo, so in the meantime add `resolvers += Resolver.url("scoverage-bintray", url("https://dl.bintray.com/sksamuel/sbt-plugins/"))(Resolver.ivyStylePatterns)` to your build.
67-
68-
## Notes on upgrading to version 1.0.0
41+
Coverage reports will be in your `target/scala-<scala-version>/scoverage-report`
42+
directory. There are HTML and XML reports. The XML is useful if you need to
43+
programatically use the results, or if you're writing a tool.
6944

70-
If you are upgrading from 0.99.x then you must remove the `instrumentSettings` from your build.sbt or Build.scala, as that is no longer needed.
45+
**NOTE**: If you're running the coverage reports from within an sbt console
46+
session (as opposed to one command per sbt launch), then the `coverage` command
47+
is sticky. To turn it back off when you're done running reports, use the
48+
`coverageOff` command or reset `coverageEnabled` with `set coverageEnabled :=
49+
false`.
7150

72-
Next, the keys have been renamed slightly. The new names begin with coverageXXX, eg coverageExcludedPackages and some have had their full name changed. You can see a full list of keys by opening the object ScoverageKeys.
51+
### Multi project reports
7352

74-
## Multi project reports
53+
By default, scoverage will generate reports for each project separately. You can
54+
merge them into an aggregated report by using the following:
7555

76-
By default, scoverage will generate reports for each project separately. You can merge them into an aggregated report by invoking `sbt coverageAggregate`.
77-
78-
(Note, you must do this after all the coverage data is complete as a separate command, so you cannot do `sbt coverage test coverageAggregate` (at least until a way around this is found).)
56+
```
57+
$ sbt coverageAggregate
58+
```
7959

80-
(You do not need to run `coverageReport` before `coverageAggregate`; it aggregates over the sub-projects' coverage data directly, not the report xml.)
60+
**NOTE**: You do not need to run `coverageReport` before `coverageAggregate`; it
61+
aggregates over the sub-projects' coverage data directly, not the report xml.
8162

82-
## Exclude classes and packages
63+
### Exclude classes and packages
8364

84-
You can exclude classes from being considered for coverage measurement by providing semicolon-separated list of
85-
regular expressions.
65+
You can exclude classes from being considered for coverage measurement by
66+
providing semicolon-separated list of regular expressions.
8667

87-
Example:
8868
```scala
8969
coverageExcludedPackages := "<empty>;Reverse.*;.*AuthService.*;models\\.data\\..*"
9070
```
9171

92-
The regular expressions are matched against the fully qualified class name, and must match the entire string to take effect.
93-
94-
Any matched classes will not be instrumented or included in the coverage report.
72+
The regular expressions are matched against the fully qualified class name, and
73+
must match the entire string to take effect. Any matched classes will not be
74+
instrumented or included in the coverage report.
9575

9676
You can also mark sections of code with comments like:
9777

@@ -101,59 +81,67 @@ You can also mark sections of code with comments like:
10181
// $COVERAGE-ON$
10282
```
10383

104-
Any code between two such comments will not be instrumented or included in the coverage report.
84+
Any code between two such comments will not be instrumented or included in the
85+
coverage report.
10586

106-
## Minimum coverage
87+
### Minimum coverage
10788

108-
Based on minimum coverage, you can fail the build with the following keys
89+
Based on minimum coverage, you can fail the build with the following keys:
10990

11091
```scala
11192
coverageMinimum := 80
11293
coverageFailOnMinimum := true
11394
```
11495

115-
These settings will be enforced when the reports are generated.
116-
If you generate an aggregate report using `coverageAggregate` then these settings will apply to that report.
96+
These settings will be enforced when the reports are generated. If you generate
97+
an aggregate report using `coverageAggregate` then these settings will apply to
98+
that report.
99+
100+
## Trouble-shooting failing tests
117101

118-
## Failing tests
119-
Scoverage does a lot of file writing behind the scenes in order to track which statements have been executed.
120-
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:
102+
scoverage does a lot of file writing behind the scenes in order to track which
103+
statements have been executed. If you are running into a scenario where your
104+
tests normally pass, but fail when scoverage is enabled, then the culprit can be
105+
one of the following:
121106

122107
* timing issues on futures and other async operations, try upping the timeouts by an order of magnitude.
123108
* tests are run in a sandbox mode (such as with `java.security.PrivilegedAction<T>`), try running the tests outside of the sandbox.
124109

110+
## Example project
111+
112+
[the scoverage samples project](https://github.com/scoverage/sbt-scoverage-samples).
113+
125114
## Integrations
126115

127116
### Codacy
128117

129-
[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 [sbt-codacy-coverage plugin](https://github.com/codacy/sbt-codacy-coverage).
118+
[Codacy](https://www.codacy.com) integrates with your favorite coverage tool to
119+
provide an in-depth overlook of your project status. scoverage information can
120+
be integrated into Codacy through the
121+
[codacy-coverage-reporter](https://github.com/codacy/codacy-coverage-reporter).
130122

131123
### Coveralls
132124

133-
If you have an open source project then you can add code coverage metrics with the excellent website https://coveralls.io/ Scoverage will integrate with coveralls using the [sbt-coveralls](https://github.com/scoverage/sbt-coveralls) plugin.
134-
135-
### Plugin for SonarQube
125+
If you have an open source project then you can add code coverage metrics with
126+
the [Coveralls](https://coveralls.io/). scoverage will integrate with coveralls
127+
using the [sbt-coveralls](https://github.com/scoverage/sbt-coveralls) plugin.
136128

137-
If you want to visually browse statement coverage reports then use this [plugin for SonarQube](https://github.com/RadoBuransky/sonar-scoverage-plugin).
138-
It allows you to review overall project statement coverage as well as dig deeper into sub-modules, directories and
139-
source code files to see uncovered statements. Statement coverage measurement can become an integral part of your
140-
team's continuous integration process and a required quality standard.
129+
### Codecov
141130

142-
## License
143-
```
144-
This software is licensed under the Apache 2 license, quoted below.
131+
You can integrate with [Codecov](https://about.codecov.io/) easily sending your
132+
reports there via your CI. You can see an example of this here in
133+
[codecov/example-scala](https://github.com/codecov/example-scala).
145134

146-
Copyright 2013-2016 Stephen Samuel and contributors
135+
### Plugin for SonarQube
147136

148-
Licensed under the Apache License, Version 2.0 (the "License"); you may not
149-
use this file except in compliance with the License. You may obtain a copy of
150-
the License at
137+
If you want to visually browse statement coverage reports then use this [plugin
138+
for SonarQube](https://github.com/RadoBuransky/sonar-scoverage-plugin). It
139+
allows you to review overall project statement coverage as well as dig deeper
140+
into sub-modules, directories and source code files to see uncovered statements.
141+
Statement coverage measurement can become an integral part of your team's
142+
continuous integration process and a required quality standard.
151143

152-
http://www.apache.org/licenses/LICENSE-2.0
144+
## Release Notes
153145

154-
Unless required by applicable law or agreed to in writing, software
155-
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
156-
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
157-
License for the specific language governing permissions and limitations under
158-
the License.
159-
```
146+
For any information on releases and upgrading, please refer to the [release
147+
page](https://github.com/scoverage/sbt-scoverage/releases).

0 commit comments

Comments
 (0)