dotnet test

本文適用于: ✔️.NET Core 3.1 SDK 和更新版本

Name

dotnet test - 用來執行單元測試的 .NET 測試驅動程式。

概要

dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
    [-a|--test-adapter-path <ADAPTER_PATH>] [--arch <ARCHITECTURE>]
    [--blame] [--blame-crash]
    [--blame-crash-dump-type <DUMP_TYPE>] [--blame-crash-collect-always]
    [--blame-hang] [--blame-hang-dump-type <DUMP_TYPE>]
    [--blame-hang-timeout <TIMESPAN>]
    [-c|--configuration <CONFIGURATION>]
    [--collect <DATA_COLLECTOR_NAME>]
    [-d|--diag <LOG_FILE>] [-f|--framework <FRAMEWORK>]
    [--filter <EXPRESSION>] [--interactive]
    [-l|--logger <LOGGER>] [--no-build]
    [--nologo] [--no-restore] [-o|--output <OUTPUT_DIRECTORY>] [--os <OS>]
    [-r|--results-directory <RESULTS_DIR>] [--runtime <RUNTIME_IDENTIFIER>]
    [-s|--settings <SETTINGS_FILE>] [-t|--list-tests]
    [-v|--verbosity <LEVEL>]
    [<args>...]
    [[--] <RunSettings arguments>]

dotnet test -h|--help

描述

dotnet test命令是用來在指定的解決方案中執行單元測試。 dotnet test命令會建置方案,並針對方案中的每個測試專案執行測試主應用程式。 測試主機會使用測試架構在指定的專案中執行測試,例如:MSTest、NUnit 或 xUnit,並報告每個測試的成功或失敗。 如果所有測試都成功,則測試執行器會傳回 0 作為結束代碼;如果有任何測試失敗,則會傳回 1。

針對多目標專案,會針對每個目標架構執行測試。 測試主機和單元測試架構會封裝為NuGet套件,並還原為專案的一般相依性。

測試專案會使用一般 <PackageReference> 元素指定測試執行器,如下列範例專案檔中所示:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.2.0" />
    <PackageReference Include="xunit" Version="2.4.1" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.4.5" />
  </ItemGroup>

</Project>

其中 Microsoft.NET.Test.Sdk 是測試主機, xunit 是測試架構。 而且 xunit.runner.visualstudio 是測試配接器,可讓 xUnit 架構與測試主機搭配運作。

隱含還原

您不需要執行 dotnet restore ,因為它會由需要還原的所有命令隱含執行,例如 dotnet newdotnet build 、、 dotnet rundotnet testdotnet publishdotnet pack 。 若要停用隱含還原,請使用 --no-restore 選項。

在某些 dotnet restore 明確還原有意義的案例中,命令仍然很有用,例如Azure DevOps Services中的持續整合組建,或在需要明確控制還原何時發生的組建系統中。

如需如何管理NuGet摘要的資訊,請參閱dotnet restore

工作負載資訊清單下載

當您執行此命令時,它會起始工作負載廣告資訊清單的非同步背景下載。 如果此命令完成時仍執行下載,則會停止下載。 如需詳細資訊,請參閱 廣告資訊清單

引數

  • PROJECT | SOLUTION | DIRECTORY | DLL | EXE

    • 測試專案的路徑。
    • 解決方案的路徑。
    • 包含專案或方案之目錄的路徑。
    • 測試專案 .dll 檔案的路徑。
    • 測試專案 .exe 檔案的路徑。

    如果未指定,效果會與使用 DIRECTORY 引數來指定目前目錄相同。

選項

  • -a|--test-adapter-path <ADAPTER_PATH>

    要搜尋其他測試配接器之目錄的路徑。 只會檢查 .dll 尾碼 .TestAdapter.dll 的檔案。 如果未指定,則會搜尋測試 .dll 的目錄。

  • --arch <ARCHITECTURE>

    指定目標架構。 這是設定 執行時間識別碼 (RID) 的速記語法,其中所提供的值會與預設 RID 結合。 例如,在 win-x64 機器上,指定 --arch x86 RID 設定為 win-x86 。 如果您使用此選項,請勿使用 -r|--runtime 選項。 自 .NET 6 Preview 7 起提供。

  • --blame

    在歸責模式下執行測試。 此選項有助於隔離造成測試主機當機的問題測試。 偵測到當機時,它會在 中 TestResults/<Guid>/<Guid>_Sequence.xml 建立順序檔案,以擷取在損毀之前執行的測試順序。

  • --blame-crash 自 .NET 5.0 SDK) 起可用的 (

    以歸責者模式執行測試,並在測試主機意外結束時收集損毀傾印。 此選項取決於使用的 .NET 版本、錯誤類型和作業系統。

    針對 Managed 程式碼中的例外狀況,傾印將會在 .NET 5.0 和更新版本上自動收集。 它會產生 testhost 或任何在 .NET 5.0 上執行並損毀的子進程傾印。 原生程式碼中的當機不會產生傾印。 此選項適用于 Windows、macOS 和 Linux。

    原生程式碼中的損毀傾印,或使用 .NET Core 3.1 或較舊版本時,只能使用 Procdump 在 Windows 上收集。 包含 procdump.exeprocdump64.exe 的目錄必須位於 PATH 或 PROCDUMP_PATH 環境變數中。 下載工具--blame表示 。

    若要從在 .NET 5.0 或更新版本上執行的原生應用程式收集損毀傾印,您可以將環境變數設定 VSTEST_DUMP_FORCEPROCDUMP1 來強制使用 Procdump。

  • --blame-crash-dump-type <DUMP_TYPE> 自 .NET 5.0 SDK) 起可用的 (

    要收集的損毀傾印類型。 --blame-crash表示 。

  • --blame-crash-collect-always 自 .NET 5.0 SDK) 起可用的 (

    收集預期的損毀傾印,以及非預期的測試主機結束。

  • --blame-hang 自 .NET 5.0 SDK) 起可用的 (

    以責任者模式執行測試,並在測試超過指定的逾時時收集停止回應傾印。

  • --blame-hang-dump-type <DUMP_TYPE> 自 .NET 5.0 SDK) 起可用的 (

    要收集的損毀傾印類型。 它應該是 fullmininone 。 指定 時 none ,會在逾時終止測試主機,但不會收集任何傾印。 --blame-hang表示 。

  • --blame-hang-timeout <TIMESPAN> 自 .NET 5.0 SDK) 起可用的 (

    個別測試逾時,之後會觸發停止回應傾印,並測試主機進程及其所有子進程都會傾印和終止。 逾時值是以下列其中一種格式指定:

    • 1.5h、1.5hour、1.5hours
    • 90m、90 分鐘、90 分鐘、90 分鐘
    • 5400s、5400sec、5400second、5400seconds
    • 5400000ms、5400000mil、5400000millisecond、54000000milliseconds

    例如,當未使用任何單位時, (5400000) ,則會假設此值為毫秒。 與資料驅動測試搭配使用時,逾時行為取決於所使用的測試配接器。 針對 xUnit 和 NUnit,會在每次測試案例之後更新逾時。 針對 MSTest,逾時會用於所有測試案例。 Windows和更新版本、Linux netcoreapp3.1 和更新版本,以及搭配 net5.0 或更新版本macOS支援此選項 netcoreapp2.1--blame表示 和 --blame-hang

  • -c|--configuration <CONFIGURATION>

    定義組建組態。 大部分專案的預設值是 Debug ,但您可以覆寫專案中的組建組態設定。

  • --collect <DATA_COLLECTOR_NAME>

    測試回合啟用資料收集器。 如需詳細資訊,請參閱監視及分析測試回合

    在 Windows (x86、x64 和 arm64) 上,Linux (x64) 和 macOS (x64) ,您可以使用 選項收集程式碼涵蓋範圍 --collect "Code Coverage" 。 如需詳細資訊,請參閱 使用程式碼涵蓋範圍自訂程式碼涵蓋範圍分析

    若要在 .NET Core 支援的任何平臺上收集程式碼涵蓋範圍,請安裝 Coverlet 並使用 --collect "XPlat Code Coverage" 選項。

  • -d|--diag <LOG_FILE>

    啟用測試平臺的診斷模式,並將診斷訊息寫入指定的檔案及其旁邊的檔案。 記錄訊息的程式會決定要建立的檔案,例如 *.host_<date>.txt 測試主機記錄檔,以及 *.datacollector_<date>.txt 資料收集器記錄檔。

  • -f|--framework <FRAMEWORK>

    目標 Framework Moniker (TFM) 目標 Framework 來執行測試。 目標 Framework 也必須在專案檔中指定。

  • --filter <EXPRESSION>

    使用指定的運算式篩選出目前專案中的測試。 如需詳細資訊,請參閱篩選選項詳細資料一節。 如需如何使用選擇性單元測試篩選的詳細資訊及範例,請參閱執行選擇性單元測試

  • -?|-h|--help

    列印如何使用 命令的描述。

  • --interactive

    可讓命令停止,並等候使用者輸入或進行動作。 例如完成驗證。 自 .NET Core 3.0 SDK 起提供。

  • -l|--logger <LOGGER>

    指定測試結果的記錄器。 不同于MSBuild, dotnet test 不接受縮寫:而不是 -l "console;v=d" 使用 -l "console;verbosity=detailed" 。 指定參數多次以啟用多個記錄器。 如需詳細資訊,請參閱報告 測試結果記錄器的參數,以及本文稍後的 範例

  • --no-build

    不會在執行前建置測試專案。 它也會隱含地設定 - --no-restore 旗標。

  • --nologo

    執行測試而不顯示 Microsoft TestPlatform 橫幅。 自 .NET Core 3.0 SDK 起提供。

  • --no-restore

    執行命令時,不會執行隱含還原。

  • -o|--output <OUTPUT_DIRECTORY>

    在其中尋找要執行的二進位檔的目錄。 如果未指定,則預設路徑為 ./bin/<configuration>/<framework>/。 對於具有多個目標架構的專案, (透過 TargetFrameworks 屬性) ,您也需要在指定此選項時定義 --frameworkdotnet test 一律會從輸出目錄執行測試。 您可以使用 來取用 AppDomain.BaseDirectory 輸出目錄中的測試資產。

  • --os <OS>

    指定作業系統 (作業系統) 。 這是設定 執行時間識別碼 (RID) 的速記語法,其中所提供的值會與預設 RID 結合。 例如,在 win-x64 機器上,指定 --os linux RID 設定為 linux-x64 。 如果您使用此選項,請勿使用 -r|--runtime 選項。 自 .NET 6 起提供。

  • -r|--results-directory <RESULTS_DIR>

    要放置測試結果的目錄。 如果指定的目錄不存在,則會建立該目錄。 預設值位於 TestResults 包含專案檔的目錄中。

  • --runtime <RUNTIME_IDENTIFIER>

    要測試的目標執行時間。

  • -s|--settings <SETTINGS_FILE>

    用來執行測試的 .runsettings 檔案。 元素 TargetPlatform (x86|x64) 對 沒有任何作用 dotnet test 。 若要執行以 x86 為目標的測試,請安裝 .NET Core 的 x86 版本。 路徑上 dotnet.exe 的位性是將用於執行測試的專案。 如需詳細資訊,請參閱下列資源:

  • -t|--list-tests

    列出探索到的測試,而不是執行測試。

  • -v|--verbosity <LEVEL>

    設定命令的詳細資訊層級。 允許的值為 q[uiet]m[inimal]n[ormal]d[etailed]diag[nostic]。 預設為 minimal。 如需詳細資訊,請參閱LoggerVerbosity

  • args

    指定要傳遞至配接器的額外引數。 使用空格來分隔多個引數。

    可能的引數清單取決於指定的行為:

    • 當您指定專案、方案或目錄時,或如果您省略此引數,則會將呼叫轉送到 msbuild 。 在此情況下,您可以在 dotnet msbuild 檔中找到可用的引數。
    • 當您指定 .dll.exe時,呼叫會轉接至 vstest 。 在此情況下,您可以在 dotnet vstest 檔中找到可用的引數。
  • RunSettings 參數

內嵌 RunSettings 會在命令列 「--」 之後當做最後一個引數傳遞, (記下 --) 後面的空格。 內嵌 RunSettings 會指定為 [name]=[value] 配對。 空格適用來分隔多個 [name]=[value] 組。

範例: dotnet test -- MSTest.DeploymentEnabled=false MSTest.MapInconclusiveToFailed=True

如需詳細資訊,請參閱 透過命令列傳遞 RunSettings 引數

範例

  • 執行目前目錄之專案中的測試:

    dotnet test
    
  • 執行 test1 專案中的測試︰

    dotnet test ~/projects/test1/test1.csproj
    
  • 使用 test1.dll 元件執行測試:

    dotnet test ~/projects/test1/bin/debug/test1.dll
    
  • 在目前目錄中的專案中執行測試,並以 trx 格式產生測試結果檔案:

    dotnet test --logger trx
    
  • 在目前目錄中的專案中執行測試,並在安裝 Coverlet 收集器整合之後產生程式碼涵蓋範圍檔案 () :

    dotnet test --collect:"XPlat Code Coverage"
    
  • 在目前目錄中的專案中執行測試,並只產生程式碼涵蓋範圍檔案 (Windows) :

    dotnet test --collect "Code Coverage"
    
  • 在目前目錄中的專案中執行測試,並記錄主控台的詳細詳細資訊:

    dotnet test --logger "console;verbosity=detailed"
    
  • 在目前目錄中的專案中執行測試,並使用 trx 記錄器記錄在TestResults 資料夾中 testResults.trx

    dotnet test --logger "trx;logfilename=testResults.trx"
    

    由於已指定記錄檔名稱,因此在多目標專案的情況下,會針對每個目標架構使用相同的名稱。 每個目標架構的輸出都會覆寫先前目標架構的輸出。 檔案會建立在測試專案資料夾的 TestResults 資料夾中,因為相對路徑相對於該資料夾。 下列範例示範如何為每個目標架構產生個別的檔案。

  • 在目前目錄中的專案中執行測試,並使用 trx 記錄器記錄至 TestResults 資料夾中的檔案,以及每個目標架構唯一的檔案名:

    dotnet test --logger:"trx;LogFilePrefix=testResults"
    
  • 在目前目錄中的專案中執行測試,並使用 html 記錄器進行記錄,以在TestResults資料夾中testResults.html

    dotnet test --logger "html;logfilename=testResults.html"
    
  • 在目前目錄中的專案中執行測試,並報告測試主機損毀時進行中的測試:

    dotnet test --blame
    
  • 在專案中執行測試 test1 ,將 (二進位記錄檔) 引數提供給 -blmsbuild

    dotnet test ~/projects/test1/test1.csproj -bl  
    
  • 在專案中執行測試 test1 ,將 MSBuild DefineConstants 屬性設定為 DEV

    dotnet test ~/projects/test1/test1.csproj -p:DefineConstants="DEV"
    

篩選選項詳細資料

--filter <EXPRESSION>

<Expression> 的格式為 <property><operator><value>[|&<Expression>]

<property>Test Case 的屬性。 以下為熱門單元測試架構所支援的屬性:

測試架構 支援的屬性
MSTest
  • FullyQualifiedName
  • Name
  • ClassName
  • 優先順序
  • TestCategory
xUnit
  • FullyQualifiedName
  • DisplayName
  • 類別
NUnit
  • FullyQualifiedName
  • Name
  • TestCategory
  • 優先順序

<operator> 描述屬性和值之間的關聯性:

運算子 函式
= 完全相符
!= 不完全相符
~ 包含
!~ Not contains

<value> 為字串。 所有的查閱皆不區分大小寫。

沒有 <operator> 的運算式會自動被視為 FullyQualifiedName 屬性上的 contains (例如,dotnet test --filter xyz 等同於 dotnet test --filter FullyQualifiedName~xyz)。

運算式可以使用條件運算子聯結:

運算子 函式
| OR
& AND

使用條件運算子時,您可以使用括弧括住運算式 (例如,(Name~TestMethod1) | (Name~TestMethod2))。

如需如何使用選擇性單元測試篩選的詳細資訊及範例,請參閱執行選擇性單元測試

另請參閱