dotnet test with Microsoft.Testing.Platform （MTP）

本文適用於： ✔️ .NET 10 SDK 及後續版本

名稱

dotnet test - .NET 測試驅動程式，用於執行 MTP 單元測試。

概要

dotnet test
    [<PROJECT_OR_TRAVERSAL_PATH>]
    [--project <PROJECT_PATH>]
    [--solution <SOLUTION_PATH>]
    [--test-modules <EXPRESSION>]
    [--root-directory <ROOT_PATH>]
    [--max-parallel-test-modules <NUMBER>]
    [--config-file <CONFIG_FILE>]
    [--results-directory <RESULTS_DIRECTORY>]
    [--results-directory-layout <flat|per-module>]
    [--diagnostic-output-directory <DIAGNOSTIC_OUTPUT_DIRECTORY>]
    [--minimum-expected-tests <NUMBER>]
    [--maximum-failed-tests <NUMBER>]
    [--timeout <DURATION>]
    [-e|--environment <NAME="VALUE">]
    [-a|--arch <ARCHITECTURE>]
    [--artifacts-path <ARTIFACTS_DIR>]
    [-c|--configuration <CONFIGURATION>]
    [-f|--framework <FRAMEWORK>]
    [--os <OS>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [--use-current-runtime|--ucr]
    [-v|--verbosity <LEVEL>]
    [--no-build]
    [--no-dependencies]
    [--no-restore]
    [--nologo|--no-logo|--no-banner]
    [--no-ansi]
    [--no-progress]
    [--no-artifact-post-processing]
    [--output <VERBOSITY_LEVEL>]
    [--show-test-results <OUTCOME>]
    [--list-tests [text|json]]
    [--no-launch-profile]
    [--no-launch-profile-arguments]
    [--device <DEVICE_ID>]
    [--list-devices]
    [--collect-test-map]
    [--affected-tests]
    [<args>...]

dotnet test -h|--help

Description

使用 MTP 時， dotnet test 運作速度比 VSTest 快。 與測試相關的參數不再固定，因為它們與測試project中註冊的擴展綁定。 此外，MTP 在執行測試時支援 Globbing 篩選。 欲了解更多資訊，請參閱MTP。

Important

擴充專屬選項並非內建於 MTP 中。 每個目標測試應用程式必須註冊提供選項的擴充功能。 直接新增擴充套件的 NuGet 套件，或使用包含該套件的測試 SDK 設定或設定檔。 否則，測試執行會以退出代碼 5 失敗，因為該選項無法被識別。 跑去 dotnet test --help 看看所選測試應用程式可用的選項，並查看 各場景的擴充選項 ，找到該選項的套件。

警告

當 MTP 透過 選擇加入 global.json時 dotnet test ，期望所有測試專案都使用 MTP。 如果任何測試專案使用 VSTest，就會發生錯誤。

版本需求

MTP 模式dotnet test需要 .NET 10 SDK 及 MTP 1.7 或更新版本。 .NET 10 之後新增的選項，在以下章節中會針對個別的 SDK 版本要求。 有些選項還需要更新的 MTP 套件，因為 SDK 負責協調整個執行，而每個測試應用程式則實作相應功能。

隱含還原

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

指令在某些明確還原有意義的情境下仍然有用，例如Azure DevOps Services的 持續整合建置，或需要明確控制還原時間的建置系統。

若要了解如何管理 NuGet 套件源，請參閱 dotnet restore 文件。

Important

當你執行專案或解決方案 --no-restore時，請同時保留還原產生的專案狀態 obj 在資料夾中，以及對應的全域套件資料夾。 測試框架與平台套件匯入會設定用於識別 MTP 測試應用程式的 MSBuild 屬性 dotnet test 。 該 --no-build 選項同時也意味著 --no-restore。 如果測試環境包含已建置的測試應用程式但沒有專案還原狀態，請改用 --test-modules 。 如需詳細資訊，請參閱No test projects were found。

選項

備註

你一次只能使用以下選項之一：--project、--solution，或 --test-modules。 無法合併這些選項。 此外，當你使用 --test-modules時，無法指定 --arch、 --configuration、 --framework--device、 --runtime--list-devices--os--use-current-runtime或 。 這些選項需要專案評估，或與已建構模組無關。

  • PROJECT_OR_TRAVERSAL_PATH

    指定要執行的專案或遍歷專案。 從 .NET 11 Preview 7 開始，支援 dotnet testMicrosoft.Build.Traversal專案，dirs.proj如 ，並可遞迴執行其參考的測試專案。

    從 .NET 12 預覽版開始，參數也能識別基於 C# 檔案的 MTP 測試應用程式。 基於檔案的測試應用程式不支援 --device。

  • --project <PROJECT_PATH>

    指定要執行的 project 檔案路徑（資料夾名稱或完整路徑）。 如果未指定，則會預設為目前目錄。

  • --solution <SOLUTION_PATH>

    指定要執行的解決方案檔案路徑 （資料夾名稱或完整路徑）。 如果未指定，則會預設為目前目錄。

  • --test-modules <EXPRESSION>

    過濾器會用檔案整合來測試模組。 只有屬於這些測試模組的測試才會執行。 因為這個選項不會評估專案，當專案還原狀態無法使用時，可以用它來執行已建置好的測試應用程式。 從 .NET 11 預覽版 6 開始，在圖案前加上 以!排除匹配模組。 用分號分隔多個模式;每個圖案周圍的空白會被忽略。

  • --root-directory <ROOT_PATH>

    指定 --test-modules 選項的根目錄。 它只能與 [--test-modules] 選項搭配使用。

  • --max-parallel-test-modules <NUMBER>

    指定可以平行執行的測試模組數目上限。 預設值為 Environment.ProcessorCount。

  • --config-file <CONFIG_FILE>

    指定用於測試執行的設定檔。 如果提供了相對路徑，則會根據目前目錄將其轉換成絕對路徑。 欲了解更多關於設定檔設定的資訊，請參見 testconfig.json。

  • --results-directory <RESULTS_DIRECTORY>

    指定儲存測試結果的目錄。 如果目錄不存在，它就會被建立。 如果提供了相對路徑，則會根據目前目錄將其轉換成絕對路徑。

  • --results-directory-layout <flat|per-module>

    規定多模組執行如何組織結果目錄下的檔案。 預設 flat值 ，會將所有結果寫入同一個目錄。 per-module 將每個模組的結果寫入 <project>/<target-framework>_<runtime-or-architecture>，防止相同檔名的報告互相覆寫。

    可從 .NET 11 RC 1 開始使用。

  • --diagnostic-output-directory <DIAGNOSTIC_OUTPUT_DIRECTORY>

    指定診斷輸出儲存的目錄。 如果目錄不存在，它就會被建立。 如果提供了相對路徑，則會根據目前目錄將其轉換成絕對路徑。

  • --minimum-expected-tests <NUMBER>

    規定整個跑程中測試的正最低數量。 若總測試數量低於指定最小值，測試執行即以出口代碼9失敗。 全球計數包含跳過的檢測。 欲了解更多出口代碼資訊，請參閱 MTP出口代碼。

    因為這個選項出現在前面 --，所以是一個全域（全域）選項。 如果要要求每個測驗模組至少有最低要求，請先在之後 -- 通過這個選項，這樣它就會被轉發到每個測驗模組。 欲了解更多資訊，請參閱 全程運行及每個模組最小值。

    備註

    全域最低要求需要 .NET 10 SDK（10.0.100）或更新版本。

  • --maximum-failed-tests <NUMBER>

    當測試失敗、錯誤、逾時或取消次數達到指定數量後，停止整個執行。 這趟行程以代碼13結束。

    從 .NET 11 預覽版 7 開始可用，且需要 MTP 2.4 或更新版本。

  • --timeout <DURATION>

    在指定時間結束後，至少有一個測試應用程式在執行時停止整個執行。 指定一個正數後接一個單位，例如 500ms、 90s、 10m、 2h或 1d。 超時跑車會以代碼3離開。

    從 .NET 11 預覽版 7 開始可用，且需要 MTP 2.4 或更新版本。

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

    為測試程序設定一個環境變數。 多次指定設定多個變數的選項。 命令列值會覆蓋發射設定檔的值。

    當沒有啟動設定檔或你指定--no-launch-profile時，請使用 .NET SDK 10.0.110 或更新版本;早期的 .NET 10 SDK 版本在這些情況下可以忽略變數。 從 .NET 11 Preview 7 開始，變數也會流向能力感知建置、裝置選擇、部署及執行參數目標。

  • -a|--arch <ARCHITECTURE>

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

  • --artifacts-path <ARTIFACTS_DIR>

    執行命令的所有建置輸出檔案都會位於指定路徑下的子資料夾中，並以專案分隔。 如需詳細資訊，請參閱 成品輸出配置。 此選項及所提供的值必須在任何依賴其他dotnet指令輸出的指令中明確串dotnet接，例如使用 dotnet build --no-restore 和 dotnet publish --no-build時。 自 .NET 8 SDK 起即可取得。

    從 .NET 11 開始支援 MTP 模式。

  • -c|--configuration <CONFIGURATION>

    定義組建組態。 大多數專案的預設是 Debug，但你可以在project中覆寫建置設定。

  • -f|--framework <FRAMEWORK>

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

  • --os <OS>

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

  • -r|--runtime <RUNTIME_IDENTIFIER>

    要測試的目標執行階段。

    短表 -r 從 SDK 7 .NET 開始提供。

    備註

    不支援對具有全域 RuntimeIdentifier 性質的解執行測試（明確或透過 --arch、 --runtime、 --os或 ）。 改設RuntimeIdentifier在個別project層級。

  • --use-current-runtime|--ucr

    在還原與建置時，使用目前的執行環境作為目標執行時。

    自 .NET 11 預覽版 6 起可取得。 你無法將此選項與 --test-modules結合。

  • -v|--verbosity <LEVEL>

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

  • --no-build

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

  • --no-dependencies

    跳過專案間的參考。

    自 .NET 11 預覽版 6 起可取得。

  • --no-restore

    指定在執行 命令時不會執行隱含還原。

  • --nologo|--no-logo|--no-banner

    抑制 .NET 和 MTP 啟動橫幅。 -nologo同時也支援 and /nologo forms 和環境DOTNET_NOLOGO變數。

    從 .NET 11 預覽版 7 起可支援 MTP 模式。

  • --no-ansi

    停用將 ANSI 逸出字元輸出到畫面。

  • --no-progress

    停用報告進度至畫面。

  • --no-artifact-post-processing

    在多模組執行後，會停用相容工件的後處理。 從 .NET 11 RC 1 和 MTP 2.4 開始，註冊的產出後處理器可以合併相容的報表，例如 TRX 結果。 若後處理失敗，SDK 會保留原始產物及測試出口碼。

  • --output <VERBOSITY_LEVEL>

    指定測試結果的輸出冗長度。 有效值為 Minimal、Normal和 Detailed。 預設值為 Normal。 Minimal 需要 MTP 2.4 預覽版。

  • --show-test-results <OUTCOME>

    依結果選擇結果區塊。 在 MTP 2.4 預覽版中，請使用 passed、 failed、 skipped、 allnone或 。 failed該數值也包含錯誤、逾時和取消次數。

    將 、 、 skipped 與逗號、空格或重複--show-test-results選項結合passed。 failed 不要合併 all 或 none 和其他數值一起。 這個明確選項會覆蓋預設， --output 無論選項順序如何。

  • --list-tests [text|json]

    列表發現測試卻未執行。 省略該值或指定 text 為人類可讀輸出。 從 .NET 11 預覽版 7 開始，指定json一份版本化的 JSON 文件，依組合語言、目標框架和架構分組測試，並包含可用的識別碼、來源位置、方法、參數與特徵。

  • --no-launch-profile

    不要嘗試用 launchSettings.json 來設定應用程式。 預設會使用 ， launchSettings.json 其可將環境變數和命令行自變數套用至測試可執行檔。

  • --no-launch-profile-arguments

    不要用啟動設定檔中 commandLineArgs 指定的參數來執行應用程式。

  • --device <DEVICE_ID>

    在 Android 或 iOS 測試專案中，為每個目標框架選擇裝置、模擬器或模擬器。 MTP 路徑也支援 macOS 與 Mac Catalyst 測試專案。 若輸入是互動式且有多個裝置可用， dotnet test 系統會提示你選擇其中一台。

    自 .NET 11 預覽版 6 起可取得。 多目標專案建議使用 .NET 11 RC 2 或更新版本，讓裝置發現能正確評估每個目標框架。 瀏覽器的 WebAssembly 測試專案不支援此選項。

  • --list-devices

    列出專案可用設備，無需執行測試。 指定一個專案，而不是解決方案。

    自 .NET 11 預覽版 7 起可購買。

  • --collect-test-map 與 --affected-tests

    收集儲存庫測試地圖或執行受變更影響的測試。 這些實驗方案需要獨立分散式的擴展與 DOTNET_CLI_ENABLE_AFFECTED_TESTS=1 環境變數。 你不能把這兩個選項合併。 受影響測試工作流程也不支援裝置測試、平行測試模組或最低測試政策。

    可從 .NET 11 RC 1 開始使用。

  • --property:<NAME>=<VALUE>

    設定一個或多個 MSBuild 屬性。 重複選項來指定多個屬性：

    --property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>

    縮寫形式 -p 可用於 --property。 同樣適用於 /property:property=value 及其簡短形式 /p。 關於可用參數的更多資訊，請參閱 dotnet msbuild 文件。

  • -?|-h|--help

    輸出有關如何使用命令的說明。

  • args

    指定要傳遞至測試應用程式的額外自變數。 使用空格來分隔多個引數。 欲了解更多資訊及通過範例，請參閱 MTP概述 及 MTP特色。

    小提示

    若要指定特定項目的額外自變數，請使用 TestingPlatformCommandLineArguments MSBuild 屬性。 當你的解決方案混合測試框架（例如 MSTest 和 xUnit.net）或只有部分專案參考特定擴充功能時，這個特性特別有用。 欲了解更多資訊，請參閱 混合測試框架或擴充套件的解決方案。

備註

若要啟用檔案的追蹤記錄，請使用環境變數 DOTNET_CLI_TEST_TRACEFILE 提供追蹤檔案的路徑。

從 .NET 11 RC 1 開始，dotnet test -bl使用一個 MSBuild 會話進行多專案、多目標及裝置執行，因此二進位日誌包含完整的建置。

輸出與抵銷行為

從 .NET 11 預覽版 6 開始，互動式 ANSI 輸出會顯示目前正在執行的測試並報告每個組件的測試次數。 當輸出被重新導向、ANSI 或進度輸出被關閉，或環境不再互動時，進度顯示仍是關閉的。

從 .NET 11 Preview 6 開始，第一個 Ctrl+C 停止排程新的測試應用程式並請求協作取消。 再次按 Ctrl+C 即可立即終止子程序。 一次中止的任務以代碼3離開。

即時測試主機輸出需要支援協定 1.1 或更新版本的 MTP 主機。 舊主機會保留輸出，並在模組失敗時重播。 從 .NET 11 預覽版 7 開始，故障摘要會截斷超過 40 行的標準輸出，截斷前 30 行及最後 10 行;診斷日誌保留完整輸出。

多模組執行時，dotnet test從 .NET 11 預覽 7 開始，評估整個完整測試的零測試結果。 若有其他模組成功執行測試，若模組沒有測試，則不會失敗，除非有明確的最低測試策略要求更多測試。

結果與遺跡

當啟用 SDK 產物輸出版面時，.NET 11 RC 1 及後續版本預設會將 MTP 報告、覆蓋檔案及診斷資料置於下方<ArtifactsPath>/test/<project>/<pivot>。 明確--results-directory--results-directory-layout或優先。

從 .NET 11 RC 1 和 MTP 2.4 開始，相容的擴充套件可以後處理多模組執行中的產物。 例如，TRX 擴充功能可以在保留每個模組報告的同時建立合併報告。 關於延期及報告要求，請參閱 MTP 測試報告。

將參數前送至測試應用

dotnet test 將任何不識別的標記轉發給測試應用程式。 當一個已識別的選項出現在未識別的選項名稱與其值之間時，移除該已識別的選項可能會改變剩餘標記與測試應用程式中選項的綁定方式。 為避免此模糊，測試應用參數應置於字面值 --： 之後：

dotnet test --results-directory TestResults -- --report-trx --report-trx-filename A.trx

前述範例需要該 Microsoft.Testing.Extensions.TrxReport 套件，無論是作為直接的套件參考，或透過包含該套件的測試 SDK 配置。

同樣的解析器行為也適用於 dotnet run 和 dotnet build。 詳細範例請參見參考文獻中的dotnet run參數」。

全程與每個模組最小值

對於 --minimum-expected-tests，分隔子決定 -- 了期權的範圍：

  • 之前--的爭論是全球性的。 編曲者 dotnet test 會全程詮釋這些聲音。
  • 之後--的爭論是局部的。 dotnet test 會將這些資料轉發到每個測試模組，因此每個模組獨立套用它們。

因為 --minimum-expected-tests 兩種範圍都有，你可以要求整個流程、每個模組或兩者都有最低要求：

dotnet test --minimum-expected-tests 5 -- --minimum-expected-tests 2

前述指令要求整個流程至少有 5 次測試，每個測試模組至少有 2 次。

兩種範圍對跳過測試的計算方式不同：

Scope 跳過的測驗算進最低標準嗎？
全球 Yes. 總計數 dotnet test 包含跳過的測驗。
每個模組 No. MTP 將跳過的測試從執行的測試數量中排除。

從 .NET 11 SDK 開始，整個測試的零測試結果會從彙整結果中一次性決定。 例如，若模組因 或 --test-modules 全域 --filter不匹配，則以代碼 8 （）ZeroTests 結束，但該代碼在結果彙總前已正規化為成功。 因此，單一空模組不會整趟運行失敗，雖然模組會 Exit code: 8 將診斷資料保留在輸出中以便顯示。

MTP 4.3.0 及更新版本提供 --zero-tests-policy <allow-skipped|strict>。 預設值 allow-skipped，讓全模組跳過時成功。 該 strict 值將跳過的測試視為未執行，因此所有跳過的模組會以代碼 8 退出。 之後 -- 再傳遞選項，轉發給每個測試模組：

dotnet test -- --zero-tests-policy strict

當你沒有設定全域最低值時，.NET 11 SDK 會獨立決定整個執行的零測試判定。 全跳過的整個執行會以代碼 8 退出，不論每個模組 --zero-tests-policy 值為何。

當你指定 --minimum-expected-tests 且未達到最低值時，執行會失敗，並以退出代碼 9（MinimumExpectedTestsPolicyViolation）。 此碼與 8 不同，因此更嚴格的全域或每個模組最小值不會與空模組混淆。 若每個模組執行零測試時至少回傳代碼 9，測試模組必須使用 MTP 4.4.0 或更新版本。

備註

--minimum-expected-tests 0 無效。 要抑制零測試的退出碼，請使用 --ignore-exit-code 8。

從 .NET 11 預覽版 6、 --tl、 --terminallogger開始--tlp，這些資料會被轉發到 MSBuild，而非測試應用程式。 從 .NET 12 預覽版 1 開始，已識別-mt的-multiThreaded表單也會轉發給 MSBuild。 要通過使用這些名稱之一的申請選項，請將其置於 後方 --。

直接將執行模式選項 --help 如 和 --list-tests 傳遞給 dotnet test。 從 .NET 11 預覽版 6 開始，SDK 會驗證與測試應用程式協商的執行模式。 如果啟動設定檔或 TestingPlatformCommandLineArguments 注入這些選項之一，請求的 SDK 操作與應用程式操作不符，執行時診斷失敗。

範例

  • 在目前目錄中的 project 或解決方案中執行測試：

    dotnet test

  • 在 TestProject project 中執行測試：

    dotnet test --project ./TestProject/TestProject.csproj

  • 在 TestProjects 解決方案中執行測試：

    dotnet test --solution ./TestProjects/TestProjects.sln

  • 使用 TestProject.dll 組件執行測試：

    dotnet test --test-modules "**/bin/**/Debug/net10.0/TestProject.dll"

  • 使用 TestProject.dll 元件與根目錄來執行測試：

    dotnet test --test-modules "**/bin/**/Debug/net10.0/TestProject.dll" --root-directory "c:\code"

  • 執行所有由遍歷專案參考的測試專案，使用 .NET 11 Preview 7 或更新版本：

    dotnet test dirs.proj

  • 將測試列為 JSON 與 .NET 11 預覽版 7 或更新版本：

    dotnet test --list-tests json

  • 執行一個基於 C# 檔案的 MTP 測試應用程式，搭配 .NET 12 預覽版 1 或更新版本：

    dotnet test App.Tests.cs

  • 在目前的目錄中使用 Microsoft Code Coverage 擴充功能執行測試。 測試應用程式必須直接或透過包含該配置的測試 SDK 配置來參考 Microsoft.Testing.Extensions.CodeCoverage：

    dotnet test --coverage

  • 執行測試並將結果儲存在特定目錄中：

    dotnet test --results-directory ./TestResults

  • 在特定目錄中執行診斷輸出測試：

    dotnet test --diagnostic-output-directory ./Diagnostics

  • 執行測試以確保至少執行 10 項測試：

    dotnet test --minimum-expected-tests 10

  • 整個測試流程至少要求 5 次，每個測試模組至少 2 次：

    dotnet test --minimum-expected-tests 5 -- --minimum-expected-tests 2

  • 在 TestProject project 中執行測試，並向 -bl 提供 msbuild（二進位日誌）參數：

    dotnet test --project ./TestProject/TestProject.csproj -bl

  • 在 TestProject project 執行測試，並將 MSBuild DefineConstants 屬性設為 DEV：

    dotnet test --project ./TestProject/TestProject.csproj -p:DefineConstants="DEV"

另請參閱

  • Last updated on