Skip to content

Commit 4364a1a

Browse files
svaningelgemsvaningelgem
committed
docs: updated README
1 parent cf22ef6 commit 4364a1a

File tree

1 file changed

+63
-27
lines changed

1 file changed

+63
-27
lines changed

‎README.md‎

Lines changed: 63 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ A smart Maven plugin that generates textual tree-like coverage reports from JaCo
88
- **JaCoCo Plugin Integration**: Automatically detects and applies exclusion patterns from your existing JaCoCo plugin configuration
99
- **Sonar Pattern Support**: Reads and interprets `sonar.exclusions` and `sonar.coverage.exclusions` from project properties
1010
- **Build Directory Exclusion**: Automatically excludes auto-generated files by parsing package declarations in the build directory
11-
- **Multi-Module Discovery**: Automatically scans for `jacoco.exec` files across all project modules
11+
- **Multi-Module Support**: Aggregates coverage data across all modules when used in multi-module builds
1212
- **Charset Detection**: Automatically detects console encoding (UTF-8 vs ASCII) for proper tree character rendering
1313

1414
### Smart Defaults
@@ -94,24 +94,24 @@ While the plugin works with zero configuration, you can customize its behavior:
9494
| Parameter | Description | Default Value |
9595
|--------------------------------|------------------------------------------------------------------------|--------------------------------------------------|
9696
| `deferReporting` | Wait until last module in multi-module builds | `true` |
97-
| `scanModules` | Auto-discover exec files across modules | `false` |
9897
| `showFiles` | Display individual source files in tree | `false` |
9998
| `showMissingLines` | Display uncovered line numbers for each file (requires showFiles=true) | `false` |
10099
| `showTree` | Display hierarchical package tree | `true` |
101100
| `showSummary` | Display overall coverage summary | `true` |
102101
| `ignoreFilesInBuildDirectory` | Auto-exclude generated files | `true` |
103102
| `interpretSonarIgnorePatterns` | Apply Sonar exclusion patterns | `true` |
104-
| `xmlOutputFile` | Generate aggregated XML report | `${session.executionRootDirectory}/coverage.xml` |
103+
| `writeXmlReport` | Enable XML report generation | `false` |
104+
| `xmlOutputFile` | Path for the generated XML report | `${session.executionRootDirectory}/coverage.xml` |
105105

106106
### Coverage Weight Customization
107107
Control how the combined coverage score is calculated:
108108

109-
| Parameter | Description | Default |
110-
|-----------|-------------|---------|
111-
| `weightClassCoverage` | Weight for class coverage | `0.1` |
112-
| `weightMethodCoverage` | Weight for method coverage | `0.1` |
113-
| `weightBranchCoverage` | Weight for branch coverage | `0.4` |
114-
| `weightLineCoverage` | Weight for line coverage | `0.4` |
109+
| Parameter | Description | Default |
110+
|------------------------|----------------------------|---------|
111+
| `weightClassCoverage` | Weight for class coverage | `0.1` |
112+
| `weightMethodCoverage` | Weight for method coverage | `0.1` |
113+
| `weightBranchCoverage` | Weight for branch coverage | `0.4` |
114+
| `weightLineCoverage` | Weight for line coverage | `0.4` |
115115

116116
## Sample Output
117117

@@ -151,7 +151,7 @@ The missing lines are displayed in a compact format:
151151
- Individual uncovered lines: `23, 45, 67`
152152
- Ranges of consecutive uncovered lines: `33-35`
153153
- Combination: `23, 33-35, 39, 45-48`
154-
154+
- Partially covered lines are shown with "partial: " prefix
155155

156156
### Summary Section
157157
```text
@@ -166,15 +166,16 @@ The missing lines are displayed in a compact format:
166166

167167
## Advanced Configuration Examples
168168

169-
### Multi-Module with Custom Weights
169+
### Multi-Module with Custom Weights and XML Output
170170
```xml
171171
<plugin>
172172
<groupId>io.github.svaningelgem</groupId>
173173
<artifactId>jacoco-console-reporter</artifactId>
174174
<version>1.0.0</version>
175175
<configuration>
176-
<!-- Enable module scanning for automatic exec file discovery -->
177-
<scanModules>true</scanModules>
176+
<!-- Enable XML report generation -->
177+
<writeXmlReport>true</writeXmlReport>
178+
<xmlOutputFile>${project.build.directory}/aggregated-coverage.xml</xmlOutputFile>
178179
<!-- Emphasize line and branch coverage over class/method -->
179180
<weightClassCoverage>0.05</weightClassCoverage>
180181
<weightMethodCoverage>0.15</weightMethodCoverage>
@@ -192,7 +193,8 @@ The missing lines are displayed in a compact format:
192193
<version>1.0.0</version>
193194
<configuration>
194195
<showFiles>true</showFiles>
195-
<xmlOutputFile>${project.build.directory}/aggregated-coverage.xml</xmlOutputFile>
196+
<showMissingLines>true</showMissingLines>
197+
<writeXmlReport>true</writeXmlReport>
196198
</configuration>
197199
</plugin>
198200
```
@@ -211,24 +213,19 @@ The missing lines are displayed in a compact format:
211213
</plugin>
212214
```
213215

214-
### Detailed Coverage with Missing Lines
216+
### Immediate Reporting per Module
215217
```xml
216218
<plugin>
217219
<groupId>io.github.svaningelgem</groupId>
218220
<artifactId>jacoco-console-reporter</artifactId>
219221
<version>1.0.0</version>
220222
<configuration>
221-
<!-- Show individual files and their uncovered lines -->
222-
<showFiles>true</showFiles>
223-
<showMissingLines>true</showMissingLines>
224-
<!-- Generate XML report as well -->
225-
<xmlOutputFile>${project.build.directory}/aggregated-coverage.xml</xmlOutputFile>
223+
<!-- Report immediately for each module instead of waiting -->
224+
<deferReporting>false</deferReporting>
226225
</configuration>
227226
</plugin>
228227
```
229228

230-
This configuration provides maximum detail, showing exactly which lines in each file need additional test coverage, similar to Python's coverage.py output.
231-
232229
## Integration with Existing Tools
233230

234231
### JaCoCo Plugin Compatibility
@@ -248,12 +245,12 @@ The console reporter automatically respects your existing JaCoCo configuration:
248245
</configuration>
249246
</plugin>
250247

251-
<!-- Console reporter automatically detects the above configuration -->
248+
<!-- Console reporter automatically detects the above configuration -->
252249
<plugin>
253-
<groupId>io.github.svaningelgem</groupId>
254-
<artifactId>jacoco-console-reporter</artifactId>
255-
<version>1.0.0</version>
256-
<!-- No additional configuration needed -->
250+
<groupId>io.github.svaningelgem</groupId>
251+
<artifactId>jacoco-console-reporter</artifactId>
252+
<version>1.0.0</version>
253+
<!-- No additional configuration needed -->
257254
</plugin>
258255
```
259256

@@ -275,6 +272,45 @@ Works seamlessly with existing Sonar configurations:
275272
</properties>
276273
```
277274

275+
## Multi-Module Builds
276+
277+
In multi-module projects, the plugin:
278+
1. Collects execution data from each module's JaCoCo configuration
279+
2. Aggregates all coverage data across modules
280+
3. By default, defers reporting until the last module (controlled by `deferReporting`)
281+
4. Deduplicates coverage data to prevent double-counting shared code
282+
283+
Example multi-module configuration:
284+
285+
```xml
286+
<!-- In parent pom.xml -->
287+
<build>
288+
<pluginManagement>
289+
<plugins>
290+
<plugin>
291+
<groupId>io.github.svaningelgem</groupId>
292+
<artifactId>jacoco-console-reporter</artifactId>
293+
<version>1.0.0</version>
294+
<configuration>
295+
<deferReporting>true</deferReporting>
296+
<writeXmlReport>true</writeXmlReport>
297+
</configuration>
298+
</plugin>
299+
</plugins>
300+
</pluginManagement>
301+
</build>
302+
303+
<!-- In each module's pom.xml -->
304+
<build>
305+
<plugins>
306+
<plugin>
307+
<groupId>io.github.svaningelgem</groupId>
308+
<artifactId>jacoco-console-reporter</artifactId>
309+
</plugin>
310+
</plugins>
311+
</build>
312+
```
313+
278314
## Technical Implementation
279315

280316
### Execution Data Merging

0 commit comments

Comments
 (0)