Closed connor4312 closed 8 months ago
Would it be possible to load the coverage data directly from a file on disk (or in the remote workspace, whatever we want to call it) rather than as a result of the output of the test run? It seems like it'd be pretty limiting to only have coverage if it were provided by a test runner extension, if I'm understanding your current API draft correctly.
In my codebase for work, the test suite takes well over 90 minutes to run in full. So it pretty much only gets run in CI (parallelized, obviously), which means that the coverage is only available as a CI artifact. It never exists locally (at least, not from a full run).
The more likely case where this might be useful would be if you ran your test suite locally (because it was fast enough), but not using a VS Code Test Explorer extension. So then you just had the coverage.xml
(or whatever file/format your test framework outputs) on your machine, and VS Code would either know to look for that, or could be told to go into coverage mode using the data inside it.
Would it be possible to load the coverage data directly from a file on disk (or in the remote workspace, whatever we want to call it) rather than as a result of the output of the test run? It seems like it'd be pretty limiting to only have coverage if it were provided by a test runner extension, if I'm understanding your current API draft correctly.
Yes, the APIs are designed for this π You can call createTestRun
at any time, so you could do that when you load the file (passing in persist
as false
since VS Code does not need to remember the already-externally-stored results), parse them, then immediately .end()
the run.
also: I'm pretty interested in getting the CI story right, so I'm glad to have someone who has an existing use case and need for it! Please let me know if this or any other parts are confusing or seem to present roadblocks for you.
I'd make sure to document the coverage-from-file use-case specifically (I know this is an API draft and actual docs are a while away, but I think it's important π).
Regarding CI, probably a crazy idea, but:
It'd be nice to point VS Code at a URL where it can get the coverage file (maybe it passes a param with the current branch name as well) so I wouldn't have to download the coverage.xml myself manually. But that'd have to be custom-built to redirect to the latest CI artifacts somehow since there's no stable URL that CircleCI (or any other CI system) provides for something like this, as far as I know.
And maybe that should be a capability handled by an extension rather than as something in core VS Code. π€·ββοΈ
Yep, that's a good idea for an extension
I have a question about the FileCoverage API. If I am looking at a coverage report, it looks like I only know the file URI. So, if someone starts a coverage test run (which may take a while to run) then makes any changes to the file the statements may not line up correctly with the current editor.
In the TextDocument API there is a version
field that tracks revisions to a specific TextDocument.
Should we track FileCoverage to the specific version of the file the test run was started with? Maybe as an optional param?
While we could store the version, there's not a lot of useful things we can do with it (and it gets reset if the file is opened and closed). The most reliable way to do this would be for the extension to use registerFileSystemProvider
to create a custom uri scheme/readonly filesystem from which it can serve the version of the file that was used for the coverage run.
The field executionCount
in *Coverage
classes shows the excution information, what about the missed part.
For example, a method or a line might have 4 branches, but only 2 of them are executed.
Take the Jacoco
in Java as an example, the coverage will contains such information:
In editor each line can also have this metadata
forget about it, I just realized, if the executionCount
is zero, then it's uncovered.
For reference, there is an updated API with migration guide that was posted: https://github.com/microsoft/vscode/issues/122208#issuecomment-865391103
I implement the coverage API and data flow for it internally. There's no UI for it, but it's there to try out. At some point in the next few weeks UI will magically show up β¨
@connor4312 will the AutoRun have an option to re-run tests if lines under their coverage are edited in the file, or will we need to provide our own implementation of that?
Autorun will be primarily extension-controlled
Sounds good, was thinking of basically implementing it this way (as a configurable option):
Should the coverage be a boolean flag on the TestRunRequest or should it be an entirely different profile?
In my existing Test Profiles I'm using the configureHandler
to let users enable coverage reporting (handled by my own extension until this API is stabilized) with the Run
or Debug
profiles. But if I made a distinct profile for Coverage, would that mean I'd need to register two versions of it (one for Run + Coverage and a second one for Debug + Coverage)?
In this model we assume run-with-coverage and debugging are disjoint. This is the same as what IntelliJ and Visual Studio do by default, and in some runtimes (e.g. nyc in its default instrumented mode) debugging coverage is not possible at all.
I implement the coverage API and data flow for it internally. There's no UI for it, but it's there to try out. At some point in the next few weeks UI will magically show up β¨
@connor4312 what is the current status of UI for the coverage API? I'm not seeing any when I run test-provider-sample even though it seems to implement coverage.
My wish is this new UI doesn't affect existing workflow. Like adding breakpoints beside line numbers. Or mask squiggly lines intellisense code issues.
Also hoping it can work well for lcov and pytest cases. Since one problem there is the coverage report path argument can't be dynamically changed based on which test are actually being ran.
@connor4312 what is the current status of UI for the coverage API? I'm not seeing any when I run test-provider-sample even though it seems to implement coverage.
A quick ping to see if there's any sign of this coming down the pike...
It's coming, but still a couple iterations out; my time is currently used by a new thing that'll be announced soon.
@connor4312 all your great efforts are appreciated, we look forward to it!
I implemented support for the proposed coverage interface, and I have coverage, but I don't seem to see it in the UI. What am I doing wrong?
@ioquatix you're not doing anything wrong. Coverage isn't yet surfaced in the UI. I think this is still on @connor4312's todo list.
It would be pretty neat if we could attach coverage to test items, so that when those lines are changed, the test items are automatically re-run. I guess we can do this by hand but it seems a little tricky.
@ioquatix: better if that would be by range rather than by line (some coverage regions span only part of a line, some span many lines).
From Visual Studio Code Java team, we have been facing increasing demand for testing coverage. From January 2023 survey feedback, 5 out of 6 verbatims related to testing have mentioned coverage.
It seems this feature is particulary important to java developers and they take this as part of the complete experience for testing, so updates to the API would be greatly appreciated, thank you :)
Hi! I am also looking to get this API merged in sooner than later. I'm about to overhaul a code-coverage extension I wrote for IBM i (COBOL, C, RPG) and I can see the testing
namespace does not yet really support coverage tests.
@connor4312 is there any prospect that the UI for test coverage will "magically show up β¨" soon?
@connor4312 any progress on this? π
Some will be made in this November iteration
UI mockup:
Followup from team discussion:
@connor4312
Some concern about view proliferation. Perhaps we have an option to show coverage in the explorer view instead of a separate view.
Please consider how we can provide results in our own views also. I'd really like to set coverage results for a Uri and then any tree view that has a TreeNode
with the resourceUri
which matches the coverage result, it would show the UI for that TreeNode
item.
This similar to how DiagnosticCollection
works. If I set diagnostics based on Uri, then in any view where I references the Uri in the resourceUri
property, then the number + color shown on my TreeItem
label will be based on the diagnostic collection (if there are warnings it's yellow, if errors it's red, etc). Perhaps even being able to lock it down to resourceUri
and the view
context would be good too.
The reason I ask for this is because I'd like to not only expose the coverage data in the explorer (which I absolutely will be doing), but also in my own trees where I show data from a coverage services running on another platform.
Nonetheless, your mock looks awesome. I'm so ready to start exposing my coverage data in a more VS Code native fashion.
I'd like to update my plugin to report coverage, how can we try this out?
Can we associate tests with a covered region to allow running tests that affect given code?
That should be possible, as every coverage region was at some point executed by atleast one test, which will result in the neccessary relation. I think the Live Unit Testing feature in Visual Studio works very similar to this. Will be interesting later which coverage providers collect such data or discard it. Still, would be really helpful to have some API to set such relations in order to have similar features like Live Unit Testing or to hover over coverage regions and get a list of succeeding/failing tests like in VS.
I really appreciate the work on the code coverage feature, as I am eagerly waiting for this for a long time. ProgressBar-like style looks very reasonable for a quick overview compared to a number with 1% precision as in IntelliJ.
EDIT:
Some concern about view proliferation. Perhaps we have an option to show coverage in the explorer view instead of a separate view.
Also +1 for the idea to show the coverage data in the explorer view. Maybe one could add a button to toggle between the coverage results and warning/error badges as needed. This could even be extended to regular test results. So there really would be some potential.
* I had this idea for the view inspired by [xcode's coverage view](https://developer.apple.com/library/archive/documentation/DeveloperTools/Conceptual/testing_with_xcode/Art/twx-codedov-4_2x.png). I didn't want to go [IntelliJ's direction](https://resources.jetbrains.com/help/img/idea/2023.2/coverage-report-overview.png) with a massive, dense table.
ππ½ Will the tree be expandable down to functions like in the screenshot?
And I assume when you double-click an item it opens the file and shows line coverage?
I'd really like to set coverage results for a Uri and then any tree view that has a TreeNode with the resourceUri which matches the coverage result, it would show the UI for that TreeNode item.
My concern here is that the bars are very big and on tree items with inline actions could end up overflowing or occluding the contents of the container. This may be something we do, and would be configurable, will have to explore.
I'd like to update my plugin to report coverage, how can we try this out?
Check this out: https://code.visualstudio.com/api/advanced-topics/using-proposed-api The UI isn't in VS Code yet, but it will be soon. Also, please provide feedback whether the APIs work or don't work for you!
Will the tree be expandable down to functions like in the screenshot?
I want that, but it potentially needs an API tweak. Currently we may not know know whether a file has function coverage until we resolveFileCoverage
, and if there's no function coverage at that point we may end up looking silly (unless we have other information we can always show there, maybe granular coverage info?)
Hi @connor4312,
I tried the coverage api with the help of the extension sample (test-provider-sample), and have a question:
In the sample extension, looks like it does not use the TestRunProfileKind.Coverage
profile. After running the tests, user needs to click the button in the TEST RESULTS
view to see the coverage status.
Why not using TestRunProfileKind.Coverage
?
I tried to create a TestRunProfileKind.Coverage
profile, but didn't see the shortcut appear in the test explorer, neither the context menu of the items in the text explorer. Is it by design or I missed anything?
I thought that if the user runs the test with the coverage profile, the coverage explorer should automatically appear.
After running the tests, user needs to click the button in the TEST RESULTS view to see the coverage status.
In the latest Insiders, coverage is automatically opened when an extension finishes a test run that includes coverage.
Why not using TestRunProfileKind.Coverage?
I will add this π that kind is pretty much unused right now, but making sure that works fluidly is something I'll do before release.
For general edification, the month of December is our housekeeping iteration, and then we resume feature development in Jan. My goal is for coverage to be feature-complete in January and get our team self-hosting on it for VS Code development, and then finalize the API for the February 2024 release. Depending where we are, coverage could be finalized in January instead, but I don't anticipate this.
Some questions and feedbacks:
FunctionCoverage
Currently, after feeding the function coverage to VS Code, the coverage view will show the function coverage ratio for each file. Looks like currently the UI will not reflect the information about the name
and location
fields of the function coverage. Will they be used in the future?
Just my personal feeling. Currently the number of the coverage bars displayed in the coverage view are different across different files. It depends on
As a user, he may not be able to get the ratio of each kind of coverage with a quick glance. Sometimes he may need to hover onto those coverage bars to get which kind it is. Seems a little bit inconvenient.
Looks like currently the UI will not reflect the information about the name and location fields of the function coverage. Will they be used in the future?
Yes, they will
Sometimes he may need to hover onto those coverage bars to get which kind it is. Seems a little bit inconvenient.
I think the thing to do here is to report a CoveredCount of 0 covered / 0 total for each kind you want to report, if there's no other information available.
Currently those will show green as 100% covered, but I think I'll change it so that they're muted.
I noticed the latest Insider will not show the coverage information in the File Explorer, will we have any kind of decorator/description hint for the file entry in the file explorer in the future?
In my point of view, the coverage support and source control support have a lot of similarity about UI component. In VS Code, it provides two ways to provide information about source control status.
Source Control
view shows all the details for all the changed files.I think the same concept can be applied to coverage as well:
About the current coverage view, I have one more input about the presentation. I understand that the table view makes people feel complex and heavy, which may not apply to VS code's product philosophy. However, the advantage of table is that user can get an accurate coverage number quickly. While for the progress bar, User cannot tell that until hovering the mouse onto it.
You can imagine this case: a project requires the coverage to reach 70%. both 69% and 71% looks similar when it's a progress bar, user have to hover the mouse onto it to tell the difference. This is another reason that a summary hint besides the file item in file explorer is helpful. Take IDEA as an example:
The latest Insiders does have test coverage information in the explorer, following https://github.com/microsoft/vscode/pull/198891, which will be visible if coverage locations match the URIs of files in the workspace.
straightforward UI hints: editor gutter decorator, file decorator in file explorer
will come in Jan π
However, the advantage of table is that user can get an accurate coverage number quickly. While for the progress bar, User cannot tell that until hovering the mouse onto it.... You can imagine this case: a project requires the coverage to reach 70%. both 69% and 71% looks similar when it's a progress bar, user have to hover the mouse onto it to tell the difference.
I'm curious how often a user would care about e.g. a 69% coverage versus a 70% coverage. Would that be pretty much exclusively for reaching a number for acceptance? If so, would allowing the user to customize when the bar is red/yellow/green accomplish the same goal? I.e. if I set my yellow at 70%, then as long as I run coverage and don't see any red then I know at a glance I'm okay.
Would that be pretty much exclusively for reaching a number for acceptance?
Yes, in Java, the Jacoco Maven plugin can set the coverage ratio. Below is an example which requires an overall instruction coverage of 80% and no class must be missed:
<rules>
<rule>
<element>BUNDLE</element>
<limits>
<limit>
<counter>INSTRUCTION</counter>
<value>COVEREDRATIO</value>
<minimum>0.80</minimum>
</limit>
<limit>
<counter>CLASS</counter>
<value>MISSEDCOUNT</value>
<maximum>0</maximum>
</limit>
</limits>
</rule>
</rules>
If so, would allowing the user to customize when the bar is red/yellow/green accomplish the same goal?
This can be a solution, I guess. I'm ok to wait for more users feedback. At least there is a solution now.
Okay, I managed to get it working.. sort of. I definitely don't have 100% coverage on every file... probably a bug in my code.
Ah, this is looking better/more accurate:
Are we planning to add code coverage to the editor/code view as well? It would be useful to know what lines are not executed.
Are we planning to add code coverage to the editor/code view as well? It would be useful to know what lines are not executed.
Yes, that will happen next month, after the holidays
I believe that this % is lines covered. MS code coverage file (.coverage) contains Lines Covered
, Lines Partially Coveredand Lines Not Covered
. I wonder how this kind of information can be displayed. Maybe like [70%-20%-10%] or some other way.
Ah, this is looking better/more accurate:
I believe that this % is lines covered. MS code coverage file (.coverage) contains
Lines Covered
, Lines Partially Coveredand Lines Not Covered
. I wonder how this kind of information can be displayed. Maybe like [70%-20%-10%] or some other way.
I am of the opinion your extension could go by token rather than by line in that case and generate a more accurate entry, I don't see the need to clutter this unnecessarily with a stratified coverage.
For the most part I encourage people to aim for 100% coverage so the main goals would be:
Showing 90% (statement|branch|whatever) coverage of file x isnβt as important IMHO as simply pointing out that coverage is missing.
@connor4312
I noticed that VS Code now can display the profile for coverage kind, is this heart icon just a placeholder? π
I noticed that codicon already has an icon named debug-coverage
π£ 2024-03 update: test coverage support has been finalized. You can find the finished, usable version of the API in
vscode.d.ts
and a guide in our docs.Original discussion has been preserved below.
Notes researching of existing formats:
This results in the following API. The
TestCoverageProvider
is given as an optional provider on the managed TestRun object. This is similar to theSourceControl
interface in vscode.d.ts. The provider is then pretty standard; it'll only be examined when the run finishes, so all its data is static.It has a method to get general coverage information for all files involved in the run, and a method to provide detailed coverage for a URI.
I refer to the atomic unit of coverage as "statement coverage". The examined test formats only provide line-based coverage, but statement coverage is what these are actually trying convey approximate and most tooling (e.g. istanbul/nyc) is technically capable of per-statement rather than per-line coverage. Therefore, it's called statement coverage, but it can be used as line coverage.
The API is physically large due to the nature of data being provided, but is conceptually pretty simple (at least compared to the Test Controller API!). I don't like the method names on the TestCoverageProvider, but have not thought of better ones yet.