Issue 160: Cascaded-directory html reports #687

macetw · 2022-10-25T19:20:34Z

This change implements a hierarchical (aka cascaded) directory-based html report. It adds a new argument: --html-cascaded-directories

This change re-implements how we sort the lists of source files in html, that it uses Jinja to sort, using data stored with what we pass to the template. This way, the sorting can also take into account the subdirectories that have aggregated statistical data that goes with it.

This change needed to implement a new class that manages different directories and the source files they go in. This class also knows about the parent directory that it is inside and the statistics for all of the given directory's contents.

#160

Closes #544

codecov · 2022-10-25T22:14:35Z

Codecov Report

Base: 94.39% // Head: 95.55% // Increases project coverage by +1.15% 🎉

Coverage data is based on head (3280267) compared to base (451b176).
Patch coverage: 92.62% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #687      +/-   ##
==========================================
+ Coverage   94.39%   95.55%   +1.15%     
==========================================
  Files          27       28       +1     
  Lines        3498     3736     +238     
  Branches      605      640      +35     
==========================================
+ Hits         3302     3570     +268     
+ Misses        125       93      -32     
- Partials       71       73       +2

Flag	Coverage Δ
ubuntu-20.04	`94.50% <91.66%> (+0.11%)`	⬆️
windows-2019	`95.22% <92.17%> (?)`

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
gcovr/configuration.py	`99.68% <ø> (ø)`
gcovr/tests/test_args.py	`98.91% <ø> (+0.04%)`	⬆️
gcovr/tests/test_coverage.py	`100.00% <ø> (ø)`
gcovr/utils.py	`92.61% <ø> (+9.19%)`	⬆️
gcovr/writer/csv.py	`100.00% <ø> (ø)`
gcovr/writer/html.py	`95.43% <ø> (+0.41%)`	⬆️
gcovr/writer/json.py	`97.05% <ø> (ø)`
gcovr/writer/txt.py	`97.33% <ø> (ø)`
gcovr/__main__.py	`93.67% <57.14%> (-1.07%)`	⬇️
gcovr/coverage.py	`97.52% <94.78%> (-1.53%)`	⬇️
... and 11 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

Spacetown · 2022-10-26T04:45:16Z

For the Windows specific data you have to download the artefacts and override the files locally.

macetwatargo · 2022-10-26T15:38:27Z

For the Windows specific data you have to download the artefacts and override the files locally.

I wish I had a windows box to practice on. :-/ I'll have to come up with something.

gcovr/tests/cascaded-nonsort/Makefile

gcovr/coverage.py

Spacetown · 2022-10-27T04:34:43Z

Please don't force push. After this we don't see the changes since last review.

gcovr/templates/directory_page.html

Spacetown

Looks good, only some little comments.

Some general questions:

Shall directories always be at the top or sorted between the files? Reflect this in the test.
What shall be done if only one file is in a directory? Is the directory needed in this case or shall the file be added directly, removing one hierarchy level?

setup.cfg

gcovr/coverage.py

gcovr/writer/html.py

gcovr/coverage.py

gcovr/writer/html.py

macetw · 2022-10-31T17:00:44Z

Looks good, only some little comments.

Some general questions:

Shall directories always be at the top or sorted between the files? Reflect this in the test.

What shall be done if only one file is in a directory? Is the directory needed in this case or shall the file be added directly, removing one hierarchy level?

The directories will always be sorted based on the sorting method the user supplied. See function row_sort_keys(), which respects this. This translates into the sorting style applied at the Jinja level.
https://github.com/macetw/gcovr/blob/cdce979872c61b89363e997e8b6bf1f5dcc132aa/gcovr/writer/html.py#L612
https://github.com/macetw/gcovr/blob/cdce979872c61b89363e997e8b6bf1f5dcc132aa/gcovr/templates/directory_page.html#L142
If there is only one file in a directory ... or only one directory in a directory, these conditions cause the hierarchy to be collapsed. It is tested on the tests I put in. The "nested" test case that was already there exercises this, and I tested different sort methods on the cascaded case.
https://github.com/macetw/gcovr/blob/cdce979872c61b89363e997e8b6bf1f5dcc132aa/gcovr/coverage.py#L364
https://github.com/macetw/gcovr/tree/hierarchical_html_new_data_model/gcovr/tests/nested/subdir/A/C/D
https://github.com/macetw/gcovr/tree/hierarchical_html_new_data_model/gcovr/tests/nested/subdir/B

…plate, order of function impl.

…ssociated with it.

…sorting the file/directory coverage based on branch coverage.

macetw · 2022-11-30T01:15:30Z

Looks good, only some little comments.
Some general questions:

Shall directories always be at the top or sorted between the files? Reflect this in the test.

What shall be done if only one file is in a directory? Is the directory needed in this case or shall the file be added directly, removing one hierarchy level?

The directories will always be sorted based on the sorting method the user supplied. See function row_sort_keys(), which respects this. This translates into the sorting style applied at the Jinja level.
https://github.com/macetw/gcovr/blob/cdce979872c61b89363e997e8b6bf1f5dcc132aa/gcovr/writer/html.py#L612
https://github.com/macetw/gcovr/blob/cdce979872c61b89363e997e8b6bf1f5dcc132aa/gcovr/templates/directory_page.html#L142

If there is only one file in a directory ... or only one directory in a directory, these conditions cause the hierarchy to be collapsed. It is tested on the tests I put in. The "nested" test case that was already there exercises this, and I tested different sort methods on the cascaded case.
https://github.com/macetw/gcovr/blob/cdce979872c61b89363e997e8b6bf1f5dcc132aa/gcovr/coverage.py#L364
https://github.com/macetw/gcovr/tree/hierarchical_html_new_data_model/gcovr/tests/nested/subdir/A/C/D
https://github.com/macetw/gcovr/tree/hierarchical_html_new_data_model/gcovr/tests/nested/subdir/B

Update:
With the most recent commits, the row_sort_keys() function no longer exists, but the sort_coverage() function is made to sort using the same strategies for files as for directories. Note that the line_coverage() and branch_coverage() functions with DirectoryCoverage had to be implemented but are simple wrapper functions.

…ests.

Spacetown

Some suggestions regarding path normalization.

gcovr/coverage.py

gcovr/utils.py

…_data_model

macetw · 2022-12-06T23:26:25Z

Looks good, only some little comments.
Some general questions:

Shall directories always be at the top or sorted between the files? Reflect this in the test.

What shall be done if only one file is in a directory? Is the directory needed in this case or shall the file be added directly, removing one hierarchy level?

The directories will always be sorted based on the sorting method the user supplied. See function row_sort_keys(), which respects this. This translates into the sorting style applied at the Jinja level.
https://github.com/macetw/gcovr/blob/cdce979872c61b89363e997e8b6bf1f5dcc132aa/gcovr/writer/html.py#L612
https://github.com/macetw/gcovr/blob/cdce979872c61b89363e997e8b6bf1f5dcc132aa/gcovr/templates/directory_page.html#L142

If there is only one file in a directory ... or only one directory in a directory, these conditions cause the hierarchy to be collapsed. It is tested on the tests I put in. The "nested" test case that was already there exercises this, and I tested different sort methods on the cascaded case.
https://github.com/macetw/gcovr/blob/cdce979872c61b89363e997e8b6bf1f5dcc132aa/gcovr/coverage.py#L364
https://github.com/macetw/gcovr/tree/hierarchical_html_new_data_model/gcovr/tests/nested/subdir/A/C/D
https://github.com/macetw/gcovr/tree/hierarchical_html_new_data_model/gcovr/tests/nested/subdir/B

Since I wrote this, I changed the sorting method to run python-based sort_coverage() even within the subdirectory level, based on feedback on this PR. I think there's still a future improvement that a client-user would like to sort based on any column, that it would be javascript/typescript-based sort, but that's just for future-thinking.

Spacetown · 2022-12-11T16:05:56Z

Only one last question before merging this PR.
In the test cascaded-no-details only folder A is shown without more information. I think this doesn't make sense. Three ideas how to prevent this:

The option --html-cascaded-directories implies --html-details (my prefered solution).
The option --html-cascaded-directories is ignored (with a warning) if --html-details is missing.
The option --html-cascaded-directories without --html-details will raise an error.

If you agree that the cascading directories only make sens with the details I would also suggest to rename the option to --html-details-cascaded-directories to show that it's related to the details.

latk · 2022-12-11T16:23:04Z

Naming command line options is the kind of thing where we only have one attempt to get it right – once some behaviour is implemented, people will depend on that for the next half decade or so.

I agree with @Spacetown that cascaded-directories will typically imply detail-pages.

I expect that this option will be used quite frequently, and will replace --html-details as the typical way to get HTML output. Thus, the command line options to get a cascaded report should be short and easy to type.

My preferred solution would be three levels of detail in the HTML report, with each level including the content of the previous levels:

--html for a summary of the entire project in a single HTML file
--html-details for that summary plus annotated per-source-file reports
--html-nested for per-directory summaries plus annotated per-source-file reports, intended for large projects where summarizing all coverage data in a single HTML file would be overwhelming

If we want to enable nested summaries without per-source-file annotated reports, I'd rather do this via something like --html-nested --no-html-details, but I'm not sure if our configuration data model can express that (since these options aren't boolean flags, but take a destination filename).

Spacetown · 2022-12-11T16:38:06Z

My preferred solution would be three levels of detail in the HTML report, with each level including the content of the previous levels:

* `--html` for a summary of the entire project in a single HTML file

* `--html-details` for that summary plus annotated per-source-file reports

* `--html-nested` for per-directory summaries plus annotated per-source-file reports, intended for large projects where summarizing all coverage data in a single HTML file would be overwhelming

I think this options are the way we should go. Since nested without details will hide the needed information someone needs good arguments to request this.

- The option is changed from a flag to a output option (same as --html-details). Use all possibilities to set the output file. - Add --html-syntax-highlighting as main name for --html-details-syntax-highlighting since it is used for details and for nested reports.

Spacetown · 2023-01-06T23:58:46Z

@macetw I've pushded the open changes on your branch. If you don't have pending changes I can merge the PR.

macetw · 2023-01-07T00:04:05Z

For what it's worth, these additional changes by @Spacetown look good. Thank you.

macetw · 2023-01-07T00:07:00Z

@macetw I've pushded the open changes on your branch. If you don't have pending changes I can merge the PR.

Please proceed as you see fit. Thank you

Spacetown · 2023-01-07T16:33:36Z

@macetw Thanks for implementing this long requested feature.

…istics per directory. (gcovr#687) Co-authored-by: Spacetown <[email protected]>

macetw force-pushed the hierarchical_html_new_data_model branch from bb26f9e to 848fe3c Compare October 25, 2022 19:24

macetwatargo mentioned this pull request Oct 25, 2022

To make heirarchical HTML reports (#160) #664

Closed

macetw force-pushed the hierarchical_html_new_data_model branch from 848fe3c to 47fd53e Compare October 25, 2022 19:48

macetw added this to the Upcoming release milestone Oct 25, 2022

macetw requested a review from latk October 25, 2022 20:03

macetw force-pushed the hierarchical_html_new_data_model branch 2 times, most recently from 3043093 to 71df7c5 Compare October 25, 2022 22:04

macetw force-pushed the hierarchical_html_new_data_model branch from 71df7c5 to 1236637 Compare October 25, 2022 23:02

macetw linked an issue Oct 26, 2022 that may be closed by this pull request

Is it possible to hyperlink and nest directories in --html-details output? #160

Closed

macetw commented Oct 26, 2022

View reviewed changes

gcovr/tests/cascaded-nonsort/Makefile Show resolved Hide resolved

Spacetown reviewed Oct 26, 2022

View reviewed changes

gcovr/coverage.py Show resolved Hide resolved

Issue 160: Cascaded-directory html reports

cdce979

macetw force-pushed the hierarchical_html_new_data_model branch from 1236637 to cdce979 Compare October 26, 2022 23:35

Spacetown requested changes Oct 29, 2022

View reviewed changes

gcovr/templates/directory_page.html Outdated Show resolved Hide resolved

Spacetown requested changes Oct 29, 2022

View reviewed changes

macetwatargo added 5 commits October 31, 2022 12:55

Changes based on PR feedback: name of constant, beautification of tem…

45cb8e5

…plate, order of function impl.

Simplified impl. of add_directory_coverage as per PR feedback

e57cdd6

Issue 160: Reversal of jinja-based sorting

3207cae

Issue 160: Added cascaded test with no html details and fixed a bug a…

030d873

…ssociated with it.

Issue 160: Implemented a simple wrapper function for the use case of …

b1fdd5d

…sorting the file/directory coverage based on branch coverage.

Issue 160: Removed unused code. Fixed nuances of dircov. Added unit t…

6579ab4

…ests.

Spacetown requested changes Dec 6, 2022

View reviewed changes

gcovr/coverage.py Outdated Show resolved Hide resolved

gcovr/coverage.py Outdated Show resolved Hide resolved

gcovr/coverage.py Outdated Show resolved Hide resolved

gcovr/utils.py Outdated Show resolved Hide resolved

gcovr/utils.py Outdated Show resolved Hide resolved

macetwatargo added 2 commits December 6, 2022 13:47

Issue 160: remediated failing MS-based build, pathname / vs \

d4d8da5

Merge remote-tracking branch 'fork/master' into hierarchical_html_new…

55eaa88

…_data_model

Issue 160: Fixes of bugs introduced from resolving merge conflicts.

92155e6

Corrected use of path separators on Windows, fixing unit tests.

679d43b

Spacetown added 3 commits January 6, 2023 23:43

Move sort_coverage from utils.py to coverage.py.

9b5505d

Undo removal of condition and simplify logic.

9d1702c

Spacetown force-pushed the hierarchical_html_new_data_model branch from 218ef00 to e0c775a Compare January 6, 2023 23:20

Fix CI errors.

93c7b4a

Spacetown force-pushed the hierarchical_html_new_data_model branch from e0c775a to 93c7b4a Compare January 6, 2023 23:34

Spacetown approved these changes Jan 6, 2023

View reviewed changes

Remove the type hint "Options".

3280267

Spacetown merged commit dce78fc into gcovr:master Jan 7, 2023

Spacetown mentioned this pull request Feb 11, 2023

Would you be open to a PR that adds in an option to use alternative templates? #714

Closed

D-Walther pushed a commit to D-Walther/gcovr that referenced this pull request Jun 16, 2025

Add nested reports that summarize subdirectories with aggregated stat…

add3b1b

…istics per directory. (gcovr#687) Co-authored-by: Spacetown <[email protected]>

Issue 160: Cascaded-directory html reports #687

Issue 160: Cascaded-directory html reports #687

Uh oh!

Conversation

macetw commented Oct 25, 2022 • edited by Spacetown Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Oct 25, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Spacetown commented Oct 26, 2022

Uh oh!

macetwatargo commented Oct 26, 2022

Uh oh!

Uh oh!

Uh oh!

Spacetown commented Oct 27, 2022

Uh oh!

Uh oh!

Spacetown left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

macetw commented Oct 31, 2022

Uh oh!

macetw commented Nov 30, 2022

Uh oh!

Spacetown left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

macetw commented Dec 6, 2022

Uh oh!

Spacetown commented Dec 11, 2022

Uh oh!

latk commented Dec 11, 2022

Uh oh!

Spacetown commented Dec 11, 2022

Uh oh!

Spacetown commented Jan 6, 2023

Uh oh!

macetw commented Jan 7, 2023

Uh oh!

macetw commented Jan 7, 2023

Uh oh!

Spacetown commented Jan 7, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

macetw commented Oct 25, 2022 •

edited by Spacetown

Loading

codecov bot commented Oct 25, 2022 •

edited

Loading