[C#]使用 AltCover 獲得程式碼覆蓋率

背景

在 CI/CD 流程當中，測試是 CI 中很重要的部分。跟開發人員關係最大的就是單元測試，單元測試編寫完成之後，我們可以使用 IDE 或者 dot cover 等工具獲得單元測試對於業務程式碼的覆蓋率。不過我們需要一個獨立的 CLI 工具，這樣我們才能夠在 Jenkins 的 CI 流程整合。

端到端測試(End to End Test) 是在 Preview 版本部署完成之後，需要對 Preview 版本進行自動化測試，測試完成之後輸出對應的覆蓋率報告。根據程式碼覆蓋率報告，我們可以瞭解 QA 編寫的測試用例，是否完整覆蓋了所有分支流程。

實現

工具選型

單元測試框架我選擇的是 xUnit，它對於 .NET Core 與 .NET Framework 的支援都不錯，並且也提供了獨立於 IDE 之外的 Console Runner，可以很方便地同 Jenkins 整合。

覆蓋率收集工具我選擇的是 AltCover，因為它能夠收集到部署在 IIS 的 ASP.NET MVC 程式覆蓋率指標，這樣我們就能夠對一些 .NET Framework 老專案進行測試覆蓋率彙總計算。AltCover 可以生成多種格式的覆蓋率報告，預設格式是 OpenCover。

AltCover 生成的覆蓋率報告並不是直接可讀的，我們需要一個工具來生成人類可以閱讀理解的報告。這裡我選擇的是 ReportGenerator ，它支援 OpenCover 格式的覆蓋率報告，並生成對應的 HTML 檔案方便檢視。

.NET Framework 整合

我建立了一個簡單的 ASP.NET Web API 專案(.NET Framework 4.8)，提供了一個 ApiTestController 控制器，暴露了一個 HTTP POST 方法 CreateOrder，內部邏輯比較簡單，就是建立了一個新的 OrderAggregateRoot 範例，然後返回了一個 Success 文字。

/// <summary>
/// ApiTestController.
/// </summary>
[Route("api/test")]
public class ApiTestController : ApiController
{
    private readonly IOrderRepository _orderRepository;

    /// <summary>
    /// <see cref="ApiTestController"/>.
    /// </summary>
    public ApiTestController()
    {
        _orderRepository = new FakeOrderRepository();
    }

    /// <summary>
    /// CreateOrder.
    /// </summary>
    [HttpPost]
    [Route("api/test/create")]
    public IHttpActionResult CreateOrder(CreateOrderInputDto input)
    {
        var newOrder = new OrderAggregateRoot(null, input.Items.Select(x => new OrderItem(x.Price, x.Number)).ToList());
        _orderRepository.InsertAsync(newOrder);

        return Ok("Success");
    }
}

單元測試覆蓋率報告

單元測試專案建立比較簡單，我建立了一個 AltCoverTestUnitTest 專案，並且新增了 ASP.NET Web API 專案的參照，在內部新增了 AltCover 與 xUnit 相關包的參照。

AltCover 與 xUnit Console Runner 包安裝完成之後，對於 .NET Framework 專案來說，會在對應的解決方案目錄下面有一個 packages 資料夾，在裡面找到 packages\altcover.8.3.838\tools\net472 目錄，在這個目錄裡面有一個 AltCover.exe 的可執行檔案，這個就是 AltCover 的 CLI 工具。

而 xUnit Console Runner 對應的 CLI 工具則在 packages\xunit.runner.console.2.4.2\tools\net472 中，根據自己的平臺使用 xunit.console.exe 或者是 xunit.console.x86.exe 均可。

隨後我們直接使用 MSBuild 命令/IDE 重新編譯一下單元測試專案，轉到對應的 bin\Debug 目錄。在 .bin\Debug 目錄中，執行以下命令，將會生成一個新的資料夾，裡面會包含修改後的 DLL 檔案。

這裡 CLI 工具的路徑，取決於你的實際路徑，就在你解決方案對應的 pacakges 裡面。

D:\CoverageTool\AltCoverTestRESFul\packages\altcover.8.3.838\tools\net472\AltCover.exe /o=./__UnitTestWithAltCover -s=Adapter -s=Shouldly -s=Microsoft -t="Shouldly." -s="AltCover.Monitor" -t="System." -s=xunit -e="EmptyFiles" -e=Tests -r=".\_Reports\UnitTestWithAltCover.xml"

這裡我解釋以下命令，其中 /o 引數指的是修改後 DLL 的輸出目錄，這裡我指定的當前目錄下的 __UnitTestWithAltCover 資料夾。-s 引數指的是需要排除的程式集名稱，支援萬用字元與正規表示式。-e 的作用與 -s 類似，具體可以檢視 Usage ，最有一個 -r 引數指定報告的輸出路徑，也就是 OpenCover 格式的 XML 檔案輸出路徑。

為什麼需要排除？因為我們的專案可能會參照很多第三方庫，這個時候我們為了減少報告的噪音，你也不想在報告裡面看到一堆 Microsoft 的程式碼吧，所以需要手動排除掉這些程式集。

為什麼叫做修改後，因為執行命令後，AltCover 會重新生成一個新的 DLL，這個新的 DLL 反編譯後可以看到會在每行程式碼插入 Instance.Visit() 來記錄程式碼的存取路徑。

命令執行完成之後，可以看到對應的覆蓋率檔案生成了，但是這裡面覆蓋率是 0，因為我們的單元測試還沒開始跑。

隨後我們執行下面的命令，使用 xUnit Console Runner 執行我們的單元測試專案。

D:\CoverageTool\AltCoverTestRESFul\packages\xunit.runner.console.2.4.2\tools\net47\xunit.console.exe ./__UnitTestWithAltCover/AltCoverTestUnitTest.dll -xml "./_Reports/UnitTestWithAltCoverReport.xml"

第一個引數是需要執行的單元測試 DLL，第二個引數 -xml 說明我們具體的執行結果輸出路徑，這裡我們也輸出到了 _Reports 資料夾，這個時候我們就有兩個 XML 檔案了。

切換到 _Reports 資料夾，開啟終端，我們這個時候需要使用 reportgeneator 工具，根據這兩個 XML 檔案生成人類可讀的 HTML 報告。

reportgenerator "-reports:UnitTestWithAltCover.xml;UnitTestWithAltCoverReport.xml" "-targetdir:coveragereport" -reporttypes:Html

上述命令的意思就是根據這兩個 xml ，在當前目錄的 coveragereport 資料夾，生成一個新的 HTML 報告。

關於 reportgenerator 的安裝，可以參考官方的 線上工具，它會根據你選擇的情況返回適合的安裝命令。我自己直接使用的 dotnet tool install --global dotnet-reportgenerator-globaltool 命令進行的安裝。

最後的效果:

IIS Web API 覆蓋率報告

我們建立一個新的 IIS 站點，並將對應的 DLL 檔案放到對應的目錄下面。首先暫停對應 IIS 站點，並且停止對應的應用程式池。

隨後執行以下命令，將會修改對應的 DLL 檔案，以便後續進行覆蓋率跟蹤，原理跟上面的一樣。

D:\CoverageTool\AltCoverTestRESFul\packages\altcover.8.3.838\tools\net472\AltCover.exe --save --inplace -i "D:\TempFiles\IIS\AltCoverTestWebSite\bin" -s=Adapter -s=Shouldly -s="Antlr3.Runtime" -s=Microsoft -t="Shouldly." -s="AltCover.Monitor" -t="System." -s=xunit -e="EmptyFiles" -e=Tests

執行完上述命令以後，將會在終端執行目錄下生成兩個檔案，一個是 coverage.xml ，一個是 coverage.xml.acv 檔案，後者是 AltCover 的控制檔案，用於記錄程式在執行過程中的執行程式碼路徑。

隨後啟動對應的 IIS 站點與應用程式池，執行自動化測試，或者呼叫對應的介面。

如果需要停止測試了，需要將對應的 IIS 站點與應用程式池停止，只有停止了，AltCover 才會將已執行程式碼路徑資訊寫入到對應的控制檔案當中。

可以看到 coverage.xml.0.acv 檔案已經有內容了，但是我們還需要將控制檔案的資訊合併到 coverage.xml 當中，這個時候需要執行第二個命令進行合併。

D:\CoverageTool\AltCoverTestRESFul\packages\altcover.8.3.838\tools\net472\AltCover.exe runner --collect -r "D:\TempFiles\IIS\AltCoverTestWebSite\bin"

output:

... D:\TempFiles\IIS\AltCoverTestWebSite\coverage.xml.0.acv (380b)
308 visits recorded in 00:00:00.0171096 (18,002 visits/sec)
A total of 308 visits recorded
Coverage statistics flushing took 0.04 seconds
Visited Classes 10 of 12 (83.33)
Visited Methods 14 of 22 (63.64)
Visited Points 65 of 93 (69.89)
Visited Branches 4 of 30 (13.33)
Maximum CRAP score 30
==== Alternative Results (includes all methods including those without corresponding source) ====
Alternative Visited Classes 13 of 15 (86.67)
Alternative Visited Methods 20 of 30 (66.67)
Alternative maximum CRAP score 30

可以看到控制檯的輸出已經有 308 visits recorded，隨後我們使用 reportgenerator 工具生成 HTML 報告。

.NET Core 整合

單元測試覆蓋率報告

整合方法同 .NET Framework 一樣。

ASP .NET Core 覆蓋率報告

這裡我使用的是 dotnet tool 安裝的 altcover 命令，安裝命令如下，前提是你得有 .NET Core 執行時。

dotnet tool install --global altcover.global --version

隨後編譯對應的 ASP.NET Core 專案，並且在對應的 bin\Debug 目錄開啟終端，執行以下命令進行準備工作。

altcover /o=./__UnitTestWithAltCover -i .

隨後使用 altcover runner 命令啟動對應的程式。

altcover runner -x .\__UnitTestWithAltCover\AltCoverTestRESTFulCore.exe -r .\__UnitTestWithAltCover\

如果已經完成了測試，請終止掉對應的程序，否則 AltCover 不會將資料寫入到 XML 檔案，最後也使用 reportgenerator 工具生成 HTML 報告。

總結

如果你的專案是基於 .NET Core ，那麼可以直接選擇微軟主推的 coverlet ，AltCover 對於 .NET Framework、Mono、.NET Core 專案都有不錯的支援，並且作者維護得也很勤快。