Add support for UnreachableException in .NET code

The issue names no repository files, tests, or entry points. Start with the C# switch example and the linked UnreachableException references, then trace how the coverage tools produce the shown XML; done means UnreachableException paths are excluded from coverable lines and branches as in the expected output.

.NET 7 added the UnreachableException class, which is meant to be thrown when executing a branch that isn't isn't expected to execute, due to the developer believing it to be unreachable. The Microsoft code coverage tools should analyze code that throws UnreachableException and reduce the number of coverable lines and branches accordingly.

Consider the following example:

using System.Diagnostics;

enum E
{
    A,
    B,
    C,
}

static partial class C
{
    public static void M()
    {
        E value = GetValue();

        switch (value) // line 16
        {
            case E.A:
                PerformActionA();
                break;

            case E.B:
                PerformActionB();
                break;

            case E.C:
                PerformActionC();
                break;

            default:
                throw new UnreachableException(); // line 31
        }
    }
}

Currently, this will yield coverage data for M() like so:

<method line-rate="0.9090909090909091" branch-rate="0.75" complexity="4" name="M" signature="()">
  <lines>
    <line number="13" hits="1" branch="False" />
    <line number="14" hits="1" branch="False" />
    <line number="16" hits="1" branch="True" condition-coverage="75% (3/4)">
      <conditions>
        <condition number="0" type="switch" coverage="75%" />
      </conditions>
    </line>
    <line number="19" hits="1" branch="False" />
    <line number="20" hits="1" branch="False" />
    <line number="23" hits="1" branch="False" />
    <line number="24" hits="1" branch="False" />
    <line number="27" hits="1" branch="False" />
    <line number="28" hits="1" branch="False" />
    <line number="31" hits="0" branch="False" />
    <line number="33" hits="1" branch="False" />
  </lines>
</method>

We see that the condition on line 16 shows four branches (one of which is the default case and is uncovered) and that line 31 shows no hits. If the developer has otherwise guaranteed that GetValue() will return a valid value of E—one of the known enum cases—and they handle the remaining case in the above sample by throwing UnreachableException, the code coverage findings should reflect that. Given the above example, if the code coverage tools were aware of UnreachableException, I would instead expect to see the following coverage data:

<method line-rate="1" branch-rate="1" complexity="4" name="M" signature="()">
  <lines>
    <line number="13" hits="1" branch="False" />
    <line number="14" hits="1" branch="False" />
    <line number="16" hits="1" branch="True" condition-coverage="100% (3/3)">
      <conditions>
        <condition number="0" type="switch" coverage="100%" />
      </conditions>
    </line>
    <line number="19" hits="1" branch="False" />
    <line number="20" hits="1" branch="False" />
    <line number="23" hits="1" branch="False" />
    <line number="24" hits="1" branch="False" />
    <line number="27" hits="1" branch="False" />
    <line number="28" hits="1" branch="False" />
    <line number="33" hits="1" branch="False" />
  </lines>
</method>

Recognizing the developer's intent with regards to intentionally unreachable code will provide for more accurate code coverage results, and will make the tooling more usable for teams who want to enforce 100% code coverage in their test suites.

References:

• UnreachableException class
• API Proposal: UnreachableException
• Add UnreachableException