dotnet test

  • 發行項

本文適用於： ✔️ .NET Core 3.1 SDK 與更新版本

名稱

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

概要

dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
    [--test-adapter-path <ADAPTER_PATH>]
    [-a|--arch <ARCHITECTURE>]
    [--artifacts-path <ARTIFACTS_DIR>]
    [--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>]
    [-e|--environment <NAME="VALUE">]
    [--filter <EXPRESSION>]
    [--interactive]
    [-l|--logger <LOGGER>]
    [--no-build]
    [--nologo]
    [--no-restore]
    [-o|--output <OUTPUT_DIRECTORY>]
    [--os <OS>]
    [--results-directory <RESULTS_DIR>]
    [-r|--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。

針對多目標專案，每個目標 Framework 都會執行測試。 測試主機和單元測試架構會封裝為 NuGet 套件，並還原為專案的一般相依性。 從 .NET 9 SDK 開始，這些測試預設會以平行方式執行。 若要停用平行執行，請將 TestTfmsInParallel MSBuild 屬性設定為 false。 如需詳細資訊，請參閱本文稍後的平行執行測試和範例命令行。

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

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

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
    <PackageReference Include="xunit" Version="2.8.0" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.0" />
  </ItemGroup>

</Project>

若 Microsoft.NET.Test.Sdk 為測試主機，測試架構便為 xunit。 測試配接器則是 xunit.runner.visualstudio，可協助 xUnit 架構與測試主機搭配運作。

隱含還原

您不必執行 dotnet restore，因為其會由需要進行還原的所有命令隱含執行，例如 dotnet new、dotnet build、dotnet run、dotnet test、dotnet publish 和 dotnet pack。 若要停用隱含還原，請使用 --no-restore 選項。

dotnet restore 命令在適合進行明確還原的特定案例中仍可派上用場，例如 Azure DevOps Services 中的持續整合組建，或在需要明確控制何時進行還原的組建系統中。

如需了解如何管理 NuGet 摘要，請參閱 dotnet restore 文件。

工作負載資訊清單下載作業

執行此命令會啟動工作負載公告資訊清單的非同步背景下載。 若此命令完成時下載仍在執行，則會停止下載。 如需詳細資訊，請參閱廣告資訊清單。

引數

  • PROJECT | SOLUTION | DIRECTORY | DLL | EXE

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

    在未指定的情況下，效果會與使用 DIRECTORY 引數指定當前目錄相同。

選項。

警告

選項的中斷性變更：

  • 從 .NET 7 開始: 將 -a 切換為別名 --arch，而非 --test-adapter-path
  • 從 .NET 7 開始: 將 -r 切換為別名 --runtime，而非 --results-directory

  • --test-adapter-path <ADAPTER_PATH>

    要搜尋其他測試配接器的目錄路徑。 系統僅會檢查尾碼 .TestAdapter.dll 為 .dll 的檔案。 在未指定的情況下，則會搜尋測試 .dll 的目錄。

    版本早於 7 的 .NET SDK 可使用簡短形式 -a。

  • --arch <ARCHITECTURE>

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

  • --artifacts-path <ARTIFACTS_DIR>

    執行命令的所有建置輸出檔案都會位於指定路徑下的子資料夾中，並以專案分隔。 如需詳細資訊，請參閱 成品輸出配置。 自 .NET 8 SDK 起提供。

  • --blame

    在歸責模式下執行測試。 這個選項可協助隔離導致測試主機損毀的問題測試。 偵測到當機時，此選項會在 TestResults/<Guid>/<Guid>_Sequence.xml 中建立序列檔案，以擷取損毀之前執行的測試順序。

    此選項不會建立記憶體傾印，在測試無回應時也派不上用場。

  • --blame-crash (自 .NET 5.0 SDK 起提供)

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

    針對受控程式碼的例外狀況，系統會自動收集 .NET 5.0 和更新版本的傾印。 其會針對測試主機或在 .NET 5.0 上執行且損毀的任何子處理序，產生傾印。 機器碼損毀不會產生傾印。 此選項適用於 Windows、macOS 與 Linux。

    機器碼或使用 .NET Core 3.1 或更早版本時產生的損毀傾印，只能使用 Procdump 在 Windows 上收集。 包含 procdump.exe 與 procdump64.exe 的目錄必須位於 PATH 或 PROCDUMP_PATH 環境變數中。 下載工具。 隱含 --blame。

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

  • --blame-crash-dump-type <DUMP_TYPE> (自 .NET 5.0 SDK 起提供)

    要收集的損毀傾印類型。 支援的傾印類型為 full (預設) 與 mini。 隱含 --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 起提供)

    要收集的損毀傾印類型。 應為 full、mini 或 none。 在 none 已指定的情況下，測試主機會在逾時後終止，但不會收集任何傾印。 隱含 --blame-hang。

  • --blame-hang-timeout <TIMESPAN> (自 .NET 5.0 SDK 起提供)

    每個測試逾時，在此之後會觸發無回應傾印，且測試主機處理序及其所有子處理序都會傾印並終止。 逾時值會以下列其中一種格式指定：

    • 1.5h、1.5hour、1.5hours
    • 90m、90min、90minute、90minutes
    • 5400s、5400sec、5400second、5400seconds
    • 5400000ms、5400000mil、5400000millisecond、5400000milliseconds

    未使用任何單位 (例如 5400000) 時，此值會假設單位為毫秒。 搭配資料驅動測試使用時，逾時行為會因使用的測試配接器而異。 針對 xUnit、NUnit。 與 MSTest 2.2.4 以上版本，每個測試案例過後逾時都會更新。 針對 2.2.4 版之前的 MSTest，此逾時會用於所有測試案例。 此選項在 Windows 上支援 netcoreapp2.1 和更新版本，在 Linux 上支援 netcoreapp3.1 和更新版本，在 macOS 上支援 net5.0 或更新版本。 隱含 --blame 與 --blame-hang 。

  • -c|--configuration <CONFIGURATION>

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

  • --collect <DATA_COLLECTOR_NAME>

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

    舉例來說，您可以使用 --collect "Code Coverage" 選項收集程式碼涵蓋範圍。 如需詳細資訊，請參閱使用程式碼涵蓋範圍、自訂程式碼涵蓋範圍分析，以及 GitHub 問題 dotnet/docs#34479。

    若要收集程式碼涵蓋範圍，您也可以透過 選項使用 Coverlet--collect "XPlat Code Coverage"。

  • -d|--diag <LOG_FILE>

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

  • -e|--environment <NAME="VALUE">

    設定環境變數的值。 如果變數不存在，請加以覆寫。 使用此選項後會在隔離處理序中強制執行測試。 您可以多次指定此選項，以提供多個變數。

  • -f|--framework <FRAMEWORK>

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

  • --filter <EXPRESSION>

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

  • -?|-h|--help

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

  • --interactive

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

  • -l|--logger <LOGGER>

    指定測試結果的記錄器，並選擇性切換記錄器。 多次指定此參數可以啟用多個記錄器。 如需詳細資訊，請參閱回報測試結果、記錄器的參數，以及本文稍後提供的範例。

    若要將命令列參數傳遞至記錄器：

    • 請使用參數的完整名稱，而非縮寫格式 (例如使用 verbosity 而非 v)。
    • 省略所有前置虛線。
    • 以分號 ; 取代分隔每個參數的空格。
    • 如果參數有值，請將該參數及其值之間的冒號分隔符號替換成等號 =。

    例如，-v:detailed --consoleLoggerParameters:ErrorsOnly 會變成 verbosity=detailed;consoleLoggerParameters=ErrorsOnly。

  • --no-build

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

  • --nologo

    執行測試，但不顯示 Microsoft Testplatform 橫幅。 自 .NET Core 3.0 SDK 起提供使用。

  • --no-restore

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

  • -o|--output <OUTPUT_DIRECTORY>

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

    • .NET 7.0.200 SDK 和更新版本

      如果您在解決方案上執行此命令時指定 --output 選項，則 CLI 將會因輸出路徑語意不清楚而發出警告 (7.0.200 中的錯誤)。 不允許 --output 選項，因為所有已建置專案的所有輸出都會複製至指定的目錄，而這與多目標專案以及具有不同直接和可轉移相依性版本的專案都不相容。 如需詳細資訊，請參閱解決方案層級的 --output 選項不再適用組建相關命令。

  • --os <OS>

    指定目標作業系統 (OS)。 這是用於設定執行階段識別碼 (RID) 的速記語法，其中提供的值會與預設 RID 合併。 例如在 win-x64 機器上，指定 --os linux 將 RID 設定為 linux-x64。 若使用此選項，請勿使用 -r|--runtime 選項。 自 .NET 6 起提供。

  • --results-directory <RESULTS_DIR>

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

    版本早於 7 的 .NET SDK 可使用簡短形式 -r。

  • -r|--runtime <RUNTIME_IDENTIFIER>

    要測試的目標執行階段。

    自 .NET SDK 7 起可使用簡短形式 -r。

  • -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"

    由於已指定記錄檔名稱，多目標專案中的所有目標 Framework 會使用相同的名稱。 每個目標 Framework 的輸出都會覆寫先前目標 Framework 的輸出。 檔案會建立在測試專案資料夾的 TestResults 資料夾中，因為相對路徑與該資料夾相對。 以下範例說明如何為每個目標 Framework 產生獨立檔案。

  • 在當前目錄內的專案中執行測試，並使用 trx 記器記錄至 TestResults 資料夾中的檔案，且每個目標 Framework 的檔案名稱都不能重複：

    dotnet test --logger:"trx;LogFilePrefix=testResults"

  • 在當前目錄內的專案中執行測試，並使用 html 記器記錄至 TestResults 資料夾中的 testResults.html：

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

  • 在當前目錄內的專案中執行測試，並回報測試主機損毀時的進行中測試：

    dotnet test --blame

  • 在 test1 專案中執行測試，將 -bl (二進位記錄檔) 引數提供給 msbuild：

    dotnet test ~/projects/test1/test1.csproj -bl

  • 在 test1 專案中執行測試，將 MSBuild DefineConstants 屬性設定為 DEV：

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

  • 在 test1 專案中執行測試，將 MSBuild TestTfmsInParallel 屬性設定為 false：

    dotnet test ~/projects/test1/test1.csproj -p:TestTfmsInParallel=false

篩選選項詳細資料

--filter <EXPRESSION>

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

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

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

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

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

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

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

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

運算子 函式
| OR
& 且

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

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

另請參閱