Exclude code that follows [DoesNotReturn] from code coverage (#904)

Exclude code that follows [DoesNotReturn] from code coverage

Author: kevin-montrose

Documentation/GlobalTool.md

@@ -17,26 +17,27 @@ Arguments:
   <ASSEMBLY>  Path to the test assembly.
 
 Options:
-  -h|--help                Show help information
-  -v|--version             Show version information
-  -t|--target              Path to the test runner application.
-  -a|--targetargs          Arguments to be passed to the test runner.
-  -o|--output              Output of the generated coverage report
-  -v|--verbosity           Sets the verbosity level of the command. Allowed values are quiet, minimal, normal, detailed.
-  -f|--format              Format of the generated coverage report[multiple value].
-  --threshold              Exits with error if the coverage % is below value.
-  --threshold-type         Coverage type to apply the threshold to[multiple value].
-  --threshold-stat         Coverage statistic used to enforce the threshold value.
-  --exclude                Filter expressions to exclude specific modules and types[multiple value].
-  --include                Filter expressions to include specific modules and types[multiple value].
-  --include-directory      Include directories containing additional assemblies to be instrumented[multiple value].
-  --exclude-by-file        Glob patterns specifying source files to exclude[multiple value].
-  --exclude-by-attribute   Attributes to exclude from code coverage[multiple value].
-  --include-test-assembly  Specifies whether to report code coverage of the test assembly.
-  --single-hit             Specifies whether to limit code coverage hit reporting to a single hit for each location.
-  --merge-with             Path to existing coverage result to merge.
-  --use-source-link        Specifies whether to use SourceLink URIs in place of file system paths.
-  --skipautoprops          Neither track nor record auto-implemented properties.
+  -h|--help                    Show help information
+  -v|--version                 Show version information
+  -t|--target                  Path to the test runner application.
+  -a|--targetargs              Arguments to be passed to the test runner.
+  -o|--output                  Output of the generated coverage report
+  -v|--verbosity               Sets the verbosity level of the command. Allowed values are quiet, minimal, normal, detailed.
+  -f|--format                  Format of the generated coverage report[multiple value].
+  --threshold                  Exits with error if the coverage % is below value.
+  --threshold-type             Coverage type to apply the threshold to[multiple value].
+  --threshold-stat             Coverage statistic used to enforce the threshold value.
+  --exclude                    Filter expressions to exclude specific modules and types[multiple value].
+  --include                    Filter expressions to include specific modules and types[multiple value].
+  --include-directory          Include directories containing additional assemblies to be instrumented[multiple value].
+  --exclude-by-file            Glob patterns specifying source files to exclude[multiple value].
+  --exclude-by-attribute       Attributes to exclude from code coverage[multiple value].
+  --include-test-assembly      Specifies whether to report code coverage of the test assembly.
+  --single-hit                 Specifies whether to limit code coverage hit reporting to a single hit for each location.
+  --merge-with                 Path to existing coverage result to merge.
+  --use-source-link            Specifies whether to use SourceLink URIs in place of file system paths.
+  --skipautoprops              Neither track nor record auto-implemented properties.
+  --does-not-return-attribute  Attributes that mark methods that do not return[multiple value].
 ```
 
 NB. For a [multiple value] options you have to specify values multiple times i.e.

Documentation/MSBuildIntegration.md

@@ -162,6 +162,13 @@ You can also include coverage of the test assembly itself by setting `/p:Include
 Neither track nor record auto-implemented properties.  
 Syntax:  `/p:SkipAutoProps=true`
 
+### Methods that do not return
+
+Methods that do not return can be marked with attributes to cause statements after them to be excluded from coverage.  `DoesNotReturnAttribute` is included by default.
+
+Attributes can be specified with the following syntax.
+Syntax:  `/p:DoesNotReturnAttribute="DoesNotReturnAttribute,OtherAttribute"`
+
 ### Note for Powershell / VSTS users
 To exclude or include multiple assemblies when using Powershell scripts or creating a .yaml file for a VSTS build ```%2c``` should be used as a separator. Msbuild will translate this symbol to ```,```.
 

Documentation/VSTestIntegration.md

@@ -80,6 +80,7 @@ These are a list of options that are supported by coverlet. These can be specifi
 |UseSourceLink   | Specifies whether to use SourceLink URIs in place of file system paths.                  |
 |IncludeTestAssembly    | Include coverage of the test assembly.                  |
 |SkipAutoProps    | Neither track nor record auto-implemented properties.                  |
+|DoesNotReturnAttribute    | Methods marked with these attributes are known not to return, statements following them will be excluded from coverage |
 
 How to specify these options via runsettings?
 ```

src/coverlet.collector/DataCollection/CoverageWrapper.cs

@@ -28,7 +28,8 @@ public Coverage CreateCoverage(CoverletSettings settings, ILogger coverletLogger
                 SingleHit = settings.SingleHit,
                 MergeWith = settings.MergeWith,
                 UseSourceLink = settings.UseSourceLink,
-                SkipAutoProps = settings.SkipAutoProps
+                SkipAutoProps = settings.SkipAutoProps,
+                DoesNotReturnAttributes = settings.DoesNotReturnAttributes
             };
 
             return new Coverage(

src/coverlet.collector/DataCollection/CoverletSettings.cs

@@ -68,6 +68,11 @@ internal class CoverletSettings
         /// </summary>
         public bool SkipAutoProps { get; set; }
 
+        /// <summary>
+        /// Attributes that mark methods that never return.
+        /// </summary>
+        public string[] DoesNotReturnAttributes { get; set; }
+
         public override string ToString()
         {
             var builder = new StringBuilder();
@@ -83,6 +88,7 @@ public override string ToString()
             builder.AppendFormat("SingleHit: '{0}'", SingleHit);
             builder.AppendFormat("IncludeTestAssembly: '{0}'", IncludeTestAssembly);
             builder.AppendFormat("SkipAutoProps: '{0}'", SkipAutoProps);
+            builder.AppendFormat("DoesNotReturnAttributes: '{0}'", string.Join(",", DoesNotReturnAttributes ?? Enumerable.Empty<string>()));
 
             return builder.ToString();
         }

src/coverlet.collector/DataCollection/CoverletSettingsParser.cs

@@ -43,6 +43,7 @@ public CoverletSettings Parse(XmlElement configurationElement, IEnumerable<strin
                 coverletSettings.SingleHit = ParseSingleHit(configurationElement);
                 coverletSettings.IncludeTestAssembly = ParseIncludeTestAssembly(configurationElement);
                 coverletSettings.SkipAutoProps = ParseSkipAutoProps(configurationElement);
+                coverletSettings.DoesNotReturnAttributes = ParseDoesNotReturnAttributes(configurationElement);
             }
 
             coverletSettings.ReportFormats = ParseReportFormats(configurationElement);
@@ -218,6 +219,17 @@ private bool ParseSkipAutoProps(XmlElement configurationElement)
             return skipAutoProps;
         }
 
+        /// <summary>
+        /// Parse attributes that mark methods that do not return.
+        /// </summary>
+        /// <param name="configurationElement">Configuration element</param>
+        /// <returns>DoesNotReturn attributes</returns>
+        private string[] ParseDoesNotReturnAttributes(XmlElement configurationElement)
+        {
+            XmlElement doesNotReturnAttributesElement = configurationElement[CoverletConstants.DoesNotReturnAttributesElementName];
+            return this.SplitElement(doesNotReturnAttributesElement);
+        }
+
         /// <summary>
         /// Splits a comma separated elements into an array
         /// </summary>

src/coverlet.collector/Utilities/CoverletConstants.cs

@@ -21,5 +21,6 @@ internal static class CoverletConstants
         public const string DefaultExcludeFilter = "[coverlet.*]*";
         public const string InProcDataCollectorName = "CoverletInProcDataCollector";
         public const string SkipAutoProps = "SkipAutoProps";
+        public const string DoesNotReturnAttributesElementName = "DoesNotReturnAttribute";
     }
 }

src/coverlet.console/Program.cs

@@ -63,6 +63,7 @@ static int Main(string[] args)
             CommandOption skipAutoProp = app.Option("--skipautoprops", "Neither track nor record auto-implemented properties.", CommandOptionType.NoValue);
             CommandOption mergeWith = app.Option("--merge-with", "Path to existing coverage result to merge.", CommandOptionType.SingleValue);
             CommandOption useSourceLink = app.Option("--use-source-link", "Specifies whether to use SourceLink URIs in place of file system paths.", CommandOptionType.NoValue);
+            CommandOption doesNotReturnAttributes = app.Option("--does-not-return-attribute", "Attributes that mark methods that do not return.", CommandOptionType.MultipleValue);
 
             app.OnExecute(() =>
             {
@@ -89,7 +90,8 @@ static int Main(string[] args)
                     SingleHit = singleHit.HasValue(),
                     MergeWith = mergeWith.Value(),
                     UseSourceLink = useSourceLink.HasValue(),
-                    SkipAutoProps = skipAutoProp.HasValue()
+                    SkipAutoProps = skipAutoProp.HasValue(),
+                    DoesNotReturnAttributes = doesNotReturnAttributes.Values.ToArray()
                 };
 
                 Coverage coverage = new Coverage(module.Value,

src/coverlet.core/Attributes/DoesNotReturnAttribute.cs

@@ -0,0 +1,7 @@
+using System;
+
+namespace Coverlet.Core.Attributes
+{
+    [AttributeUsage(AttributeTargets.Property | AttributeTargets.Method | AttributeTargets.Constructor | AttributeTargets.Class)]
+    internal class DoesNotReturnAttribute : Attribute { }
+}

src/coverlet.core/Coverage.cs

@@ -23,6 +23,7 @@ internal class CoverageParameters
         public bool SingleHit { get; set; }
         public string MergeWith { get; set; }
         public bool UseSourceLink { get; set; }
+        public string[] DoesNotReturnAttributes { get; set; }
         public bool SkipAutoProps { get; set; }
     }
 
@@ -39,6 +40,7 @@ internal class Coverage
         private bool _singleHit;
         private string _mergeWith;
         private bool _useSourceLink;
+        private string[] _doesNotReturnAttributes;
         private bool _skipAutoProps;
         private ILogger _logger;
         private IInstrumentationHelper _instrumentationHelper;
@@ -70,6 +72,7 @@ public Coverage(string module,
             _singleHit = parameters.SingleHit;
             _mergeWith = parameters.MergeWith;
             _useSourceLink = parameters.UseSourceLink;
+            _doesNotReturnAttributes = parameters.DoesNotReturnAttributes;
             _logger = logger;
             _instrumentationHelper = instrumentationHelper;
             _fileSystem = fileSystem;
@@ -124,6 +127,7 @@ public CoveragePrepareResult PrepareModules()
                                                     _includeFilters,
                                                     _excludedSourceFiles,
                                                     _excludeAttributes,
+                                                    _doesNotReturnAttributes,
                                                     _singleHit,
                                                     _skipAutoProps,
                                                     _logger,