coverlet-coverage / coverlet

Cross platform code coverage for .NET
MIT License
2.93k stars 385 forks source link

Poor documentation around attribute-based exclusion #1591

Closed richardissimo closed 4 months ago

richardissimo commented 5 months ago

I am trying to find somewhere in the documentation which states the default list of attributes that cause things to be excluded from coverage.

I'm guessing the answer is simply "System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverageAttribute", but I can't see that documented anywhere.

I'm using the "dotnet test" approach if that matters. I think the documentation for that is https://github.com/coverlet-coverage/coverlet/blob/master/Documentation/VSTestIntegration.md

The only mention on there of anything close to this is the example which shows

Obsolete,GeneratedCodeAttribute,CompilerGeneratedAttribute

but there is no explanation for what that does. For example, does that setting replace the default attributes that are used to exclude things, or does it just add to it?

I have read elsewhere that these are just the "name" of the attribute, without needing to be fully-qualified... it would be nice if that was documented here as well.

And I saw a comment somewhere saying don't forget the "Attribute" on the end. If that's true, if would be useful to have that here too, and if that's the case, then is the "Obsolete" example faulty?

daveMueller commented 5 months ago

I'm guessing the answer is simply "System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverageAttribute", but I can't see that documented anywhere.

Yes you are right. We have written this down a bit more detailed here: docs By default the ExcludeFromCodeCoverageAttribute can be used. If you want to use additional attributes for exclusion, you can use the ExcludeByAttribute property or the cli switch for the global tool (coverlet.console).

I'm using the "dotnet test" approach if that matters. I think the documentation for that is https://github.com/coverlet-coverage/coverlet/blob/master/Documentation/VSTestIntegration.md

No matter what driver you are using you need to run the test at some point which is usually done by dotnet test. But I got what you mean, you are probably using coverlet.collector.

For example, does that setting replace the default attributes that are used to exclude things, or does it just add to it?

With this setting you can specify additional attributes for exclusion. So it just adds to it.

And I saw a comment somewhere saying don't forget the "Attribute" on the end. If that's true, if would be useful to have that here too, and if that's the case, then is the "Obsolete" example faulty?

You can specify the additional exclusion attributes with or without the postfix. This can be seen here: https://github.com/coverlet-coverage/coverlet/blob/master/src/coverlet.core/Instrumentation/Instrumenter.cs#L96

But only the type names without the namespaces, e.g. Coverlet.Custom.CodeAnalysis.CustomExcludeAttribute would not work but therefore CustomExcludeFromCodeCoverageAttribute and CustomExcludeFromCodeCoverage.

tonyhallett commented 5 months ago

But only the type names without the namespaces, e.g. Coverlet.Custom.CodeAnalysis.CustomExcludeAttribute would not work but therefore CustomExcludeFromCodeCoverageAttribute and CustomExcludeFromCodeCoverage.

https://github.com/coverlet-coverage/coverlet/issues/1589