Skip to content

Commit 87e11dc

Browse files
stringbeanstringbean
committed
Complete docs
1 parent 676ea2a commit 87e11dc

File tree

5 files changed

+153
-28
lines changed

5 files changed

+153
-28
lines changed

‎src/paradox/getting-started.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,42 @@ metrics:
2525
```
2626

2727
A detailed HTML report will also be generated in the directory shown that includes line level details of coverage.
28+
29+
## Setting Minimum Coverage Levels
30+
31+
Minimum code coverage levels can be defined so that the build will fail if the requirements are not met:
32+
33+
```scala
34+
jacocoReportSettings := JacocoReportSettings()
35+
.withThresholds(
36+
JacocoThresholds(
37+
instruction = 80,
38+
method = 100,
39+
branch = 100,
40+
complexity = 100,
41+
line = 90,
42+
clazz = 100)
43+
)
44+
```
45+
46+
If the coverage does not meet the thresholds defined the build will fail and the coverge message will highlight the
47+
failed thresholds:
48+
49+
```
50+
[info] ------- Jacoco Coverage Report -------
51+
[info]
52+
[info] Lines: 66.67% (< required 90.0%) covered, 1 of 3 missed, NOK
53+
[info] Instructions: 56.52% (< required 80.0%) covered, 10 of 23 missed, NOK
54+
[info] Branches: 0% (< required 100.0%) covered, 0 of 0 missed, NOK
55+
[info] Methods: 50% (< required 100.0%) covered, 2 of 4 missed, NOK
56+
[info] Complexity: 50% (< required 100.0%) covered, 2 of 4 missed, NOK
57+
[info] Class: 100% (>= required 100.0%) covered, 1 of 2 missed, OK
58+
[info]
59+
[info] Check /home/example/jacoco-test/scala-2.10/jacoco/report for detailed report
60+
[info]
61+
[error] Required coverage is not met
62+
```
63+
64+
@@@ note
65+
By default the minimum coverage levels are set to 0%.
66+
@@@

‎src/paradox/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,13 @@ Key features of _sbt-jacoco_ include:
77

88
* Coverage of Scala and Java code.
99
* Aggregation of multi-project builds.
10-
11-
10+
* Support for unit and @ref:[integration](integration-tests.md) tests.
1211

1312
@@@ index
1413

1514
* [Getting Started](getting-started.md)
1615
* [Integration Tests](integration-tests.md)
16+
* [Multi-Project Builds](multi-project.md)
1717
* [Settings Reference](settings.md)
1818
* [Contributors](contributors.md)
1919

‎src/paradox/integration-tests.md‎

Lines changed: 4 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -11,34 +11,14 @@ Once this has been added you can cover your integration tests using `it:jacoco`.
1111
cover your unit tests the two coverage reports will get merged into a single report showing you the full coverage.
1212

1313

14-
## Combining Unit and Integration Test Results
15-
16-
---
17-
1814
@@@ warning
19-
20-
_sbt-jacoco_ adds settings to the `IntegrationTest` configuration which get overwritten if
21-
22-
If you have
15+
The `JacocoItPlugin` adds settings to the `IntegrationTest` configuration which get overwritten if you have the
16+
following in your build:
2317

2418
```scala
2519
configs(IntegrationTest)
2620
Defaults.itSettings
2721
```
28-
@@@
29-
30-
31-
For integration testing enable the the plugin using:
3222

33-
enablePlugins(JacocoItPlugin)
34-
You will also need to remove the following lines from your config if you have them:
35-
36-
configs(IntegrationTest)
37-
Defaults.itSettings
38-
(this is due to a limitation in SBT where it's difficult for plugins to configure themselves for integration tests).
39-
40-
Once you have enabled the integration test plugin you will be able to cover the integration tests using sbt it:jacoco. Unit and integration tests will get merged automatically leaving you with the following reports:
41-
42-
target/scala-2.10/jacoco/report/test/html/index.html
43-
target/scala-2.10/jacoco/report/it/html/index.html
44-
target/scala-2.10/jacoco/report/merged/html/index.html
23+
These get added automatically by the `JacocoItPlugin` in a way that they don't overwrite the extra settings.
24+
@@@

‎src/paradox/multi-project.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Multi-Project Builds
2+
3+
For the aggregated multi-project build shown below:
4+
5+
```scala
6+
lazy val common = project
7+
.in(file("common"))
8+
9+
lazy val extras = project
10+
.in(file("extras"))
11+
12+
lazy val root = project
13+
.in(file("."))
14+
.aggregate(
15+
common,
16+
extras
17+
)
18+
```
19+
20+
Running `sbt jacocoAggregate` will run the unit tests for each sub-project with coverage and then aggregate the
21+
individual reports into a single report in the root project:
22+
23+
```
24+
[info] ------- Jacoco Coverage Report -------
25+
[info]
26+
[info] Lines: 100% (>= required 0.0%) covered, 0 of 3 missed, OK
27+
[info] Instructions: 100% (>= required 0.0%) covered, 0 of 29 missed, OK
28+
[info] Branches: 0% (>= required 0.0%) covered, 0 of 0 missed, OK
29+
[info] Methods: 100% (>= required 0.0%) covered, 0 of 2 missed, OK
30+
[info] Complexity: 100% (>= required 0.0%) covered, 0 of 2 missed, OK
31+
[info] Class: 100% (>= required 0.0%) covered, 0 of 1 missed, OK
32+
[info]
33+
[info] Check /home/example/jacoco-test/common/target/scala-2.12/jacoco/report for detailed report
34+
...
35+
[info] ------- Jacoco Coverage Report -------
36+
[info]
37+
[info] Lines: 100% (>= required 0.0%) covered, 0 of 1 missed, OK
38+
[info] Instructions: 68.75% (>= required 0.0%) covered, 5 of 16 missed, OK
39+
[info] Branches: 0% (>= required 0.0%) covered, 0 of 0 missed, OK
40+
[info] Methods: 50% (>= required 0.0%) covered, 1 of 2 missed, OK
41+
[info] Complexity: 50% (>= required 0.0%) covered, 1 of 2 missed, OK
42+
[info] Class: 50% (>= required 0.0%) covered, 1 of 2 missed, OK
43+
[info]
44+
[info] Check /home/example/jacoco-test/extras/target/scala-2.12/jacoco/report for detailed report
45+
...
46+
[info] ------- Jacoco Aggregate Coverage Report -------
47+
[info]
48+
[info] Lines: 100% (>= required 0.0%) covered, 0 of 4 missed, OK
49+
[info] Instructions: 88.89% (>= required 0.0%) covered, 5 of 45 missed, OK
50+
[info] Branches: 0% (>= required 0.0%) covered, 0 of 0 missed, OK
51+
[info] Methods: 75% (>= required 0.0%) covered, 1 of 4 missed, OK
52+
[info] Complexity: 75% (>= required 0.0%) covered, 1 of 4 missed, OK
53+
[info] Class: 66.67% (>= required 0.0%) covered, 1 of 3 missed, OK
54+
[info]
55+
[info] Check /home/example/jacoco-test/target/scala-2.12/jacoco/report/aggregate for detailed report
56+
```
57+
58+
@@@ note
59+
Due to a limitation in the way that the aggregate report is generated, there no line-by-line source reports are
60+
generated in the aggregate coverage report. These reports can be viewed by opening the sub-project reports.
61+
@@@
62+
63+
## Customising the Aggregate Report
64+
65+
The aggregate report can be customised using the `jacocoAggregateReportSettings` key in the root project:
66+
67+
```scala
68+
lazy val root = project
69+
.in(file("."))
70+
.aggregate(
71+
common,
72+
extras
73+
)
74+
.settings(
75+
jacocoAggregateReportSettings := JacocoReportSettings(
76+
title = "Foo Project Coverage",
77+
formats = Seq(JacocoReportFormats.ScalaHTML)
78+
)
79+
)
80+
```

‎src/paradox/settings.md‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,22 @@ page.subheaders: true
99

1010
### Common
1111

12+
These are apply to both unit and integration tests.
13+
1214
#### jacocoDirectory
15+
1316
* **Description:** Where JaCoCo should store its execution data and reports.
1417
* **Accepts:** `java.io.File`
1518
* **Default:** `crossTarget / "jacoco"`
1619

1720
#### jacocoReportDirectory
21+
1822
* **Description:** Where JaCoCo should output reports to.
1923
* **Accepts:** `java.io.File`
2024
* **Default:** `jacocoDirectory / "report"`
2125

2226
#### jacocoDataFile
27+
2328
* **Description:** Execution data output file.
2429
* **Accepts:** `java.io.File`
2530
* **Default:** `jacocoDirectory / "data" / "jacoco.exec"`
@@ -84,6 +89,9 @@ JacocoReportSettings(
8489

8590
### Multi-Project Tests
8691

92+
These should be defined in the root project of a multi-project build and control the way that reports for sub-projects
93+
should be aggregated.
94+
8795
#### jacocoAggregateReportSettings
8896

8997
* **Description:** Settings for aggregate JaCoCo report (format, title etc).
@@ -101,9 +109,11 @@ JacocoReportSettings(
101109

102110
### Integration Tests
103111

112+
These are only defined for integration tests and configure merging of unit and integration results.
113+
104114
#### jacocoMergedDataFile
105115

106-
* **Description:** Execution data file contain unit test and integration test data.
116+
* **Description:** Execution data file containing combined unit test and integration test data.
107117
* **Accepts:** `java.io.File`
108118
* **Default:** `jacocoDirectory / "jacoco-it.exec"`
109119

@@ -124,12 +134,28 @@ JacocoReportSettings(
124134

125135
#### jacocoAutoMerge
126136

127-
* **Description:** whether to merge the unittest and integration test reports.
137+
* **Description:** Whether to merge the unit and integration test reports.
128138
* **Accepts:** `Boolean`
129139
* **Default:** `true`
130140

131141
## Types
132142

143+
All types are automatically imported in an `.sbt` based build file and can be imported into `.scala` based builds using:
144+
145+
```scala
146+
import com.github.sbt.jacoco.JacocoPlugin.autoImport._
147+
```
148+
149+
Each type has `.withXXX` methods and default values defined for all parameters giving you a choice of ways to configure:
150+
151+
```scala
152+
jacocoReportSettings := JacocoReportSettings(title = "Report Title", formats = Seq(JacocoReportFormats.HTML))
153+
// or
154+
jacocoReportSettings := JacocoReportSettings()
155+
.withTitle("Report Title")
156+
.withFormats(Seq(JacocoReportFormats.HTML))
157+
```
158+
133159
### JacocoSourceSettings
134160

135161
Properties:

0 commit comments

Comments
 (0)