dotnet 測試 VSTest

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

名稱

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

概要

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>]
    [--disable-build-servers]
    [-f|--framework <FRAMEWORK>]
    [-e|--environment <NAME="VALUE">]
    [--filter <EXPRESSION>]
    [--interactive]
    [-l|--logger <LOGGER>]
    [--no-build]
    [--no-dependencies]
    [--nologo]
    [--no-restore]
    [-o|--output <OUTPUT_DIRECTORY>]
    [--os <OS>]
    [--results-directory <RESULTS_DIR>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [-s|--settings <SETTINGS_FILE>]
    [-t|--list-tests]
    [--tl:[auto|on|off]]
    [-v|--verbosity <LEVEL>]
    [<args>...]
    [[--] <RunSettings arguments>]

dotnet test -h|--help

Description

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

備註

dotnet test 原本設計為僅 VSTest支持以為基礎的測試專案。測試框架的最新版本開始新增對 Microsoft測試平台（MTP）的支援。此替代測試平臺比使用不同命令行選項支援VSTest更輕量且更快dotnet test。更多資訊請參閱 dotnet 測試與 MTP 的連結。

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

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

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

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

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.10.1" />
    <PackageReference Include="xunit" Version="2.9.3" />
    <PackageReference Include="xunit.runner.visualstudio" Version="4.0.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 選項。

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

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

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

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

Arguments

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>

通往測試用的自訂轉接器路徑。

簡短表-a 在 SDK 版本 7 之前.NET提供。
-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 起即可取得。
--blame

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

這個選項不會產生記憶體傾印，也不會在測試當機時幫不上忙。
--blame-crash（自 .NET 5.0 SDK 起可用）

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

對於受管理程式碼中的例外，轉儲會自動在 .NET 5.0 及更新版本中被收集。它會為 testhost 或任何同樣在 .NET 5.0 上執行且當機的子程序產生一個 dump。機器碼損毀不會產生傾印。這個選項適用於 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，此逾時會用於所有測試案例。此選項支援搭載 netcoreapp2.1 及以上版本的 Windows，Linux 支援 netcoreapp3.1 及以上版本，macOS 則支援 net5.0 或更新版本。隱含 --blame 與 --blame-hang 。

你也可以在 .runsettings 檔案中設定 blame，並用 --settings傳遞。該 .runsettings 檔案支援相同的責備行為，以及額外鍵數，這些鍵不會被揭露為頂層 dotnet test 交換器，例如 CollectDumpOnTestSessionHang 和 MonitorPostmortemDebugger。欲了解更多資訊，請參閱 Blame data collector。

<RunSettings>
  <DataCollectionRunSettings>
    <DataCollectors>
      <DataCollector friendlyName="blame" enabled="true">
        <Configuration>
          <CollectDump CollectAlways="true" DumpType="full" />
          <CollectDumpOnTestSessionHang TestTimeout="30min" HangDumpType="full" />
          <MonitorPostmortemDebugger DumpDirectoryPath="C:\Dumps" />
        </Configuration>
      </DataCollector>
    </DataCollectors>
  </DataCollectionRunSettings>
</RunSettings>

下表將責任選項映射到其 dotnet test 開關與 .runsettings 元件。完整的責備收集器參考，請參見責難資料收集器。

崩潰傾倒選項：

行為	`dotnet test` 切換	`.runsettings` 元素
收集緊急傾倒	`--blame-crash`	`<CollectDump />`
即使乾淨俐落地離開，也要收取	`--blame-crash-collect-always`	`<CollectDump CollectAlways="true" />`
傾倒類型（`mini`， `full`; 預設 `full`值）	`--blame-crash-dump-type`	`<CollectDump DumpType="full" />`

懸掛傾倒選項：

行為	`dotnet test` 切換	`.runsettings` 元素
收集一個廢棄垃圾	`--blame-hang`	`<CollectDumpOnTestSessionHang />`
掛掉前的超時（預設 `1h`）	`--blame-hang-timeout`	`<CollectDumpOnTestSessionHang TestTimeout="90m" />`
懸掛式傾倒類型（`mini`， `full`， `none`）	`--blame-hang-dump-type`	`<CollectDumpOnTestSessionHang HangDumpType="mini" />`

是為了 Microsoft。Testing.Platform （MTP）測試應用程式、--blame-*交換器和 blame data collection 都不適用。 MTP 使用 --crashdump、 --hangdump、 --hangdump-timeout 以及和套件。Microsoft.Testing.Extensions.CrashDumpMicrosoft.Testing.Extensions.HangDump 更多資訊請參閱 dotnet 測試與 MTP 的連結。

-c|--configuration <CONFIGURATION>

定義組建組態。大部分專案的預設值為 Debug，但您可以覆寫專案中的組建組態設定。
--collect <DATA_COLLECTOR_NAME>

啟用資料收集器以進行測試執行。欲了解更多資訊，包括事件日誌資料收集器及撰寫自有資料收集器的指引，請參閱「監控與分析測試運行」。

舉例來說，您可以使用 --collect "Code Coverage" 選項收集程式碼涵蓋範圍。欲了解更多資訊，請參閱 Use code coverage、Customize Code coverage analysis，以及 GitHub issue dotnet/docs#34479。

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

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

要設定追蹤等級，請在日誌檔名稱後加上 ;tracelevel=<LEVEL> ，例如 --diag log.txt;tracelevel=verbose。 tracelevel 的允許值為 off、error、warning、info 和 verbose。預設值為 verbose。
--disable-build-servers

強制命令忽略任何持續性組建伺服器。此選項提供一致的方式來停用所有建置快取的使用，以強制從頭開始建置。當快取可能因某些原因而損毀或不正確時，不依賴快取的組建很有用。自 .NET 7 SDK 起即可取得。
-e|--environment <NAME="VALUE">

設定環境變數的值。如果變數不存在，它會建立;如果存在，則覆蓋。使用此選項後會在隔離處理序中強制執行測試。您可以多次指定此選項，以提供多個變數。
-f|--framework <FRAMEWORK>

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

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

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

可讓命令停止，並等候使用者輸入或進行動作。例如完成驗證。
-l|--logger <LOGGER>

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

若要將命令列參數傳遞至記錄器：
- 請使用參數的完整名稱，而非縮寫格式 (例如使用 verbosity 而非 v)。
- 省略所有前置虛線。
- 以分號 ; 取代分隔每個參數的空格。
- 如果參數有值，請將該參數及其值之間的冒號分隔符號替換成等號 =。
例如，-v:detailed --consoleLoggerParameters:ErrorsOnly 會變成 verbosity=detailed;consoleLoggerParameters=ErrorsOnly。
--no-build

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

跳過專案間的參考。自 .NET 11 預覽版 6 起可取得。
--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，位於包含專案檔的目錄裡。

簡短表-r 在 SDK 版本 7 之前.NET提供。
-r|--runtime <RUNTIME_IDENTIFIER>

要測試的目標執行階段。

短表 -r 從 SDK 7 .NET 開始提供。
-s|--settings <SETTINGS_FILE>

用來執行測試的 .runsettings 檔案。 TargetPlatform 元素 (x86|x64) 對 dotnet test 沒有任何作用。要執行針對 x86 的測試，請安裝 x86 版本的 .NET Core。路徑上 dotnet.exe 的位元會用於執行測試。如需詳細資訊，請參閱下列資源：
- 使用 .runsettings 檔案設定單元測試。
- 設定測試回合
-t|--list-tests

列出探索到的測試，而非執行測試。
--tl:[auto|on|off]

指定是否應該將 「終端機記錄器 」用於建置輸出。預設值為 auto，這會先驗證環境，再啟用終端記錄。環境檢查會驗證終端是否能夠使用新式輸出功能，而且在啟用新的記錄器之前，不會使用重新導向的標準輸出。 on 略過環境檢查並啟用終端記錄。 off 略過環境檢查並使用預設控制台記錄器。

終端機記錄器會顯示還原階段，然後是建置階段。在每個階段，目前建置的專案會出現在終端底部。建置的每個專案都會輸出目前建置的 MSBuild 目標，以及花費在該目標上的時間量。您可以搜尋此資訊以深入了解組建。當專案完成建置時，撰寫了單一「已完成建置」區段來擷取：
- 所建置專案的名稱。
- 目標架構 (如果為多目標)。
- 該組建的狀態。
- 該組建的主要輸出 (已有超連結)。
- 任何針對該專案產生的診斷。
此選項自 .NET 8 開始可用。
-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

從 .NET 5 SDK 開始，你也可以從命令列設定TestRunParameters，例如： dotnet test -- TestRunParameters.Parameter(name="myParam", value="value")。 RunSettings 參數優先於檔案中的 .runsettings 值。

更多資訊請參閱透過命令列傳遞 RunTSettings 參數。

範例

執行目前目錄之專案中的測試：
```
dotnet test
```

執行 test1 專案中的測試︰

dotnet test ~/projects/test1/test1.csproj

使用 test1.dll 組件執行測試：

dotnet test ~/projects/test1/bin/debug/test1.dll

在當前目錄內的專案中執行測試，並產生 trx 格式的測試結果檔案：
```
dotnet test --logger trx
```
在目前目錄中執行專案中的測試，並使用 Microsoft Code Coverage 產生程式碼覆蓋檔：
```
dotnet test --collect "Code Coverage"
```
在目前目錄中的項目中執行測試，並使用 Coverlet 產生程式代碼涵蓋範圍檔案（安裝 Coverlet 收集器整合之後）：
```
dotnet test --collect:"XPlat 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 名稱課程名稱 Priority TestCategory
xUnit	FullyQualifiedName 顯示名稱特徵
NUnit	FullyQualifiedName 名稱 Priority TestCategory 類別 Property

對於 xUnit，定義於的 [Trait("key", "value")] 特徵會依其鍵值過濾（例如， [Trait("Category", "bvt")] 與匹配 --filter Category=bvt）。對於 NUnit，和 TestCategoryCategory 是等價的，且定義的 [Property("key", "value")] 屬性會被其鍵過濾。

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

Operator	功能
`=`	完全相符
`!=`	不完全相符
`~`	包含
`!~`	不包含

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

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

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

Operator	功能
`\|`	OR
`&`	和

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

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

出口代碼

當你透過 VSTest 路徑執行測試時，會 dotnet test 以兩種退出碼之一回報結果：

退出代碼	Meaning
`0`	成功。所請求的操作已完成，測試運行時所有執行的測試都通過了。
`1`	蹉。例如，一個或多個測試失敗、執行錯誤被報告、命令列無效、測試來源無法載入，或執行中止或取消。

底層 vstest.console 程序從未回傳其他值。

當發現過程中找不到匹配的測試時，執行會印出警告而非錯誤，且預設仍會回傳 0 。若要執行發現或選擇零測試的執行，則改為返回1，並在檔案中RunConfiguration.TreatNoTestsAsError設定true為.runsettings。

另請參閱

架構與目標
.NET 執行時識別碼（RID）目錄
透過命令列傳遞 RunSettings 引數
VSTest environment variables （microsoft/vstest）
dotnet 測試
使用 MTP dotnet 測試

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-12