使用 .runsettings 檔案設定單元測試

發行項
03/29/2022

您可以使用 .runsettings 檔案來設定 Visual Studio 中的單元測試。例如，您可以變更執行測試的 .NET 版本、測試結果的所在目錄，或在測試回合期間所收集的資料。 .runsettings 檔案常見的用法是用來自訂程式碼涵蓋範圍分析。

您可以使用回合設定檔案來設定從命令列、IDE，或使用 Azure Test Plans 或 Team Foundation Server (TFS) 的組建工作流程中執行的測試。

回合設定檔為選擇性。如果您不需要任何特殊設定，就不需要 .runsettings 檔案。

建立執行設定檔並加以自訂

將回合設定檔新增至方案。在 [方案總管] 中，在方案的快捷方式功能表上，選擇 [加入 > 新專案]，然後選取 [ XML 檔案]。使用 .runsettings 之類的名稱來儲存檔案。

提示

檔案名稱並不重要，只要使用的副檔名為 .runsettings 即可。
從範例 *. .runsettings檔案新增內容，然後根據您的需求進行自訂，如下列各節所述。
使用下列其中一種方法，指定您想要的 *. .runsettings 檔案：
- Visual Studio IDE
- 命令列
- 使用 Azure Test Plans 或 Team Foundation Server (TFS) 來建立工作流程。
執行單元測試，以使用自訂回合設定。

如果您想要在 IDE 中關閉和開啟自訂設定，請在 [測試 > 測試設定] 功能表中取消選取或選取檔案。

Visual Studio 2017 中具有自訂設定檔的測試設定功能表

如果您想要在 IDE 中關閉和開啟自訂設定，請取消選取或選取 [ 測試 ] 功能表上的檔案。

提示

您可以在方案中建立多個 .runsettings 檔案，然後視需要選取其中一個作為使用中測試設定檔。

在 IDE 中指定回合設定檔

可用的方法取決於您的 Visual Studio 版本。

若要在 IDE 中指定回合設定檔，請選取 [測試 > 測試] 設定 > 選取 [測試設定 檔]，然後選取 .runsettings 檔案。

在 Visual Studio 2017 中選取測試設定檔的功能表

檔案隨即出現在 [測試設定] 功能表中，且您可以選取或取消選取它。選取時，只要選取 [分析程式碼涵蓋範圍]，就會套用回合設定檔。

Visual Studio 2019 16.4 版和更新版本

有三種方式可以指定 Visual Studio 2019 16.4 版和更新版本中的回合設定檔。

自動偵測回合設定
手動設定回合設定
設定組建屬性

自動偵測回合設定檔

注意

這只適用于名為 .runsettings 的檔案。

若要自動偵測回合設定檔，請將它放在解決方案的根目錄中。

如果啟用回合設定檔案的自動偵測功能，則會在所有測試回合上套用此檔案中的設定。您可以使用兩種方法開啟自動偵測 .runsettings 檔案：

選取工具 > 選項 > 測試 > 自動偵測 .runsettings 檔案
選取測試 > 設定執行設定 > 自動偵測 .runsettings 檔案

以手動方式選取回合設定檔案

在 IDE 中，選取 [測試 > 設定執行] 設定 > 選取 [方案範圍 .runsettings 檔]，然後選取 .runsettings 檔案。

這個檔案會覆寫位於方案根目錄的 .runsettings 檔案（如果有的話），並套用到所有測試回合。
此檔案選取專案只會在本機保存。

選取 Visual Studio 中的 [測試整個解決方案的 .runsettings 檔] 功能表

設定組建屬性

透過專案檔或 .props 檔案，將組建屬性加入至專案。專案的回合設定檔是由屬性 RunSettingsFilePath 所指定。

目前支援 c #、VB、c + + 和 F # 專案中的 Project 層級執行設定。
為專案指定的檔案會覆寫解決方案中指定的任何其他回合設定檔案。
這些 MSBuild 屬性可以用來指定 .runsettings 檔的路徑。

為專案指定 .runsettings 檔案的範例：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <RunSettingsFilePath>$(MSBuildProjectDirectory)\example.runsettings</RunSettingsFilePath>
  </PropertyGroup>
  ...
</Project>

Visual Studio 2019 16.3 版及更早版本

若要在 IDE 中指定回合設定檔，請選取 [測試 > 選取設定 檔案]。瀏覽並選取 .runsettings 檔案。

在 Visual Studio 2019 中選取測試設定檔的功能表

檔案會出現在 [測試] 功能表中，您可以選取或取消選取它。選取時，只要選取 [分析程式碼涵蓋範圍]，就會套用回合設定檔。

從命令列指定回合設定檔案

若要從命令列執行測試，請使用 vstest.console.exe，然後使用 /設定 參數指定設定檔案。

開啟Visual Studio 的開發人員命令提示字元。

輸入與下列類似的命令：

vstest.console.exe MyTestAssembly.dll /EnableCodeCoverage /Settings:CodeCoverage.runsettings

或

vstest.console.exe --settings:test.runsettings test.dll

如需詳細資訊，請參閱 VSTest.Console.exe 命令列選項。

*. .Runsettings 檔案

*. .Runsettings 檔案是 XML 檔案，其中包含 .runsettings 元素內的不同設定元素。接下來的各節會詳細說明不同的元素。如需完整範例，請參閱範例 * .runsettings檔案。

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <!-- configuration elements -->
</RunSettings>

每個設定元素都是選擇性的，因為它有預設值。

RunConfiguration 元素

<RunConfiguration>
    <MaxCpuCount>1</MaxCpuCount>
    <ResultsDirectory>.\TestResults</ResultsDirectory>
    <TargetPlatform>x86</TargetPlatform>
    <TargetFrameworkVersion>net6.0</TargetFrameworkVersion>
    <TestAdaptersPaths>%SystemDrive%\Temp\foo;%SystemDrive%\Temp\bar</TestAdaptersPaths>
    <TestSessionTimeout>10000</TestSessionTimeout>
    <TreatNoTestsAsError>true</TreatNoTestsAsError>
</RunConfiguration>

RunConfiguration 項目可以包括下列項目：

節點	預設	值
MaxCpuCount	1	選項名稱有區分大小寫，而且很容易拼錯為 MaxCPUCount。這項設定會控制進程層級的平行處理原則層級。使用0可啟用最大程式層級的平行處理原則。這項設定會決定可以平行執行的測試 Dll 或其他測試容器數目上限。每個 DLL 將會在自己的 testhost 進程中執行，並且會在進程層級與其他測試 Dll 中的測試隔離。這項設定不會強制每個測試 DLL 中的測試平行執行。線上程層級) 的 DLL (內控制平行執行是由測試架構（例如 MSTest、XUnit 或 NUnit）所組成。預設值為 `1` ，表示每次只會執行一個 testhost。如果電腦具有具有多執行緒) 的6個實體核心，則特殊值 `0` 可讓您有多個 testhosts 的邏輯處理器 (例如6）（沒有多執行緒的電腦）或12個實體核心。即將啟動的實際 testhosts 數目取決於執行中的相異 Dll 量。
ResultsDirectory		放置測試結果的目錄。路徑是相對於包含 .runsettings 檔案的目錄。
TargetFrameworkVersion	net40 或 netcoreapp 1。0	省略此整個標記以自動偵測。此設定會定義要用來執行測試的 framework 版本或架構系列。接受的值為任何架構的標記，例如 `net48` 、 `net472` 、 `net6.0` 、 `net5.0` 、 `netcoreapp3.1` `uap10.0` 或任何有效的完整架構名稱 `.NETFramework,Version=v4.7.2` ，例如或 `.NETCoreApp,Version=v6.0.0` 。為了回溯相容性 `Framework35` ，會接受、 `Framework45` `FrameworkUap10` `FrameworkCore10` 、和分別) (`net35` 、 `net40` 、 `netcoreapp1.0` `net45` 和 `uap10.0` 。 `Framework40` 所有值都不區分大小寫。提供的值會用來判斷要使用的測試回合時間提供者。每個測試回合時間提供者都必須遵守要使用的 framework 系列，但可能不會遵守確切的 framework 版本：若為 .NET Framework 4.5.1-4.8，則會使用以指定的精確版本建立的 testhost。若為該範圍以外的值，則會使用 .NET Framework 4.5.1 testhost。針對 .NET，實際的版本取決於測試專案的 `<TargetFramework>` (或更精確 `runtimeconfig.json` 的) 。針對 UWP，測試專案應用程式本身是一種 testhost，會決定所使用 UWP 的實際版本。 `TargetFrameworkVersion`從 .runsettings 檔案中省略專案，以從建立的二進位檔自動判斷架構版本。自動偵測時，所有目標 framework 都會整合到單一的通用架構中。找到相同目標 framework 系列的不同版本時，會選擇較新的版本 (例如 net452、net472、net48 = net48) 。針對 Visual Studio 中的 .NET Framework 執行器 (或開發人員命令列中的 vstest.console.exe) 常見的目標 Framework 是 net40。針對 .NET 執行器 (dotnet 測試 + Dll) ，通用目標 framework 會設定為 netcoreapp 1.0。
TargetPlatform	x86	省略此整個標記以自動偵測。此設定會定義用來執行測試的架構。可能的值為 `x86` 、 `ARM` `x64` 、、 `ARM64` 、 `S390x` 。自動偵測時，AnyCPU Dll 的架構可能會根據執行器而有所不同。針對 Visual Studio 中的 .NET Framework 執行器 (或開發人員命令列) 中的 vstest.console.exe，預設值為 x86。針對 .NET 執行器 (dotnet 測試) ，預設為目前的進程架構。
TreatTestAdapterErrorsAsWarnings	false	false、true
TestAdaptersPaths		TestAdapters 所在目錄的一或多個路徑
TestSessionTimeout		當測試工作階段超過指定的逾時之時，允許使用者終止測試工作階段。設定逾時可確保資源能被充分取用，且可將測試工作階段限制在設定的時間內。 Visual Studio 2017 15.5 版和更新版本提供這項設定。
DotnetHostPath		指定用來執行 testhost 之 dotnet 主機的自訂路徑。當您建立自己的 dotnet 時（例如，在建立 dotnet/執行時間存放庫時），這會很有用。指定此選項會略過尋找 testhost.exe，且一律會使用 testhost.dll。
TreatNoTestsAsError	false	true 或 false 指定布林值，此值會定義未探索到任何測試時的結束代碼。如果值為 `true` 且未探索到任何測試，則會傳回非零的結束代碼。否則會傳回零。

DataCollectors 元素 (診斷資料配接器)

DataCollectors 項目指定診斷資料配接器的設定。診斷資料配接器會收集有關環境與待測應用程式的其他資訊。每個配接器都有預設設定，如果您不想要使用預設值，您只需提供設定值即可。

<DataCollectionRunSettings>
  <DataCollectors>
    <!-- data collectors -->
  </DataCollectors>
</DataCollectionRunSettings>

CodeCoverage 資料收集器

程式碼涵蓋範圍資料收集器會建立測試中已執行過之應用程式程式碼部分的記錄。如需自訂程式碼涵蓋範圍設定的詳細資訊，請參閱自訂程式碼涵蓋範圍分析。

<DataCollector friendlyName="Code Coverage" uri="datacollector://Microsoft/CodeCoverage/2.0" assemblyQualifiedName="Microsoft.VisualStudio.Coverage.DynamicCoverageDataCollector, Microsoft.VisualStudio.TraceCollector, Version=11.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
  <Configuration>
    <CodeCoverage>
      <ModulePaths>
        <Exclude>
          <ModulePath>.*CPPUnitTestFramework.*</ModulePath>
        </Exclude>
      </ModulePaths>

      <UseVerifiableInstrumentation>True</UseVerifiableInstrumentation>
      <AllowLowIntegrityProcesses>True</AllowLowIntegrityProcesses>
      <CollectFromChildProcesses>True</CollectFromChildProcesses>
      <CollectAspDotNet>False</CollectAspDotNet>
    </CodeCoverage>
  </Configuration>
</DataCollector>

VideoRecorder 資料收集器

測試執行時，視訊資料收集器會擷取螢幕錄製。這份錄製可用於 UI 測試的疑難排解。視訊資料收集器在 Visual Studio 2017 15.5 版 和更新版本中提供。如需設定此資料收集器的範例，請參閱範例 *. .runsettings檔案。

若要自訂任何其他類型的診斷資料配接器，請使用測試設定檔。

現象資料收集器

這個選項可協助您找出導致測試主機損毀的有問題的測試。執行收集器會在 TestResults 中建立輸出檔 (Sequence.xml) ，以在損毀之前捕捉測試的執行順序。

<DataCollector friendlyName="blame" enabled="True">
</DataCollector>

TestRunParameters

<TestRunParameters>
    <Parameter name="webAppUrl" value="http://localhost" />
    <Parameter name="docsUrl" value="https://docs.microsoft.com" />
</TestRunParameters>

測試回合參數提供一種方法，可定義在執行時間可供測試使用的變數和值。使用 MSTest TestContext.Properties 屬性 (或 NUnit TestCoNtext) 來存取參數：

private string _appUrl;
public TestContext TestContext { get; set; }

[TestMethod] // [Test] for NUnit
public void HomePageTest()
{
    string _appURL = TestContext.Properties["webAppUrl"];
}

若要使用測試回合參數，請在您的測試類別中加入公用 TestContext 屬性。

LoggerRunSettings 元素

LoggerRunSettings區段會定義要用於測試回合的一或多個記錄器。最常見的記錄器為主控台、Visual Studio 測試結果檔 (.trx) 和 html。

<LoggerRunSettings>
    <Loggers>
      <Logger friendlyName="console" enabled="True">
        <Configuration>
            <Verbosity>quiet</Verbosity>
        </Configuration>
      </Logger>
      <Logger friendlyName="trx" enabled="True">
        <Configuration>
          <LogFileName>foo.trx</LogFileName>
        </Configuration>
      </Logger>
      <Logger friendlyName="html" enabled="True">
        <Configuration>
          <LogFileName>foo.html</LogFileName>
        </Configuration>
      </Logger>
    </Loggers>
  </LoggerRunSettings>

MSTest 元素

這些是執行具有 TestMethodAttribute 屬性之測試方法的測試配接器專屬的設定。

<MSTest>
    <MapInconclusiveToFailed>True</MapInconclusiveToFailed>
    <CaptureTraceOutput>false</CaptureTraceOutput>
    <DeleteDeploymentDirectoryAfterTestRunIsComplete>False</DeleteDeploymentDirectoryAfterTestRunIsComplete>
    <DeploymentEnabled>False</DeploymentEnabled>
    <AssemblyResolution>
      <Directory path="D:\myfolder\bin\" includeSubDirectories="false"/>
    </AssemblyResolution>
</MSTest>

組態	預設	值
ForcedLegacyMode	false	Visual Studio 2012 中的 MSTest 配接器已進行過最佳化，因此更快速且更具延展性。某些行為 (例如測試執行順序) 可能與舊版 Visual Studio 稍有出入。將此值設定為 true，以使用較舊的測試配接器。例如，如果您為單元測試指定 app.config 檔案，則可以使用此設定。建議您考慮重構測試，以便使用較新的配接器。
IgnoreTestImpact	false	「測試影響」功能會將受最新變更影響的測試（當在 MSTest 中執行時），或 Visual Studio 2017) 中 Microsoft Test Manager (淘汰的測試排定優先順序。這項設定會停用該功能。如需詳細資訊，請參閱自從上次建置以來應該要執行哪些測試？。
SettingsFile		您可以指定與此處的 MS 測試配接器一起使用的測試設定檔。您也可以從設定功能表指定測試設定檔。如果您指定這個值，也必須將 ForcedLegacyMode 設定為 true。 `<ForcedLegacyMode>true</ForcedLegacyMode>`
KeepExecutorAliveAfterLegacyRun	false	測試回合完成後，會關閉 MSTest。所有在測試過程中啟動的處理序也都會終止。如果您要讓測試執行程式保持運作，請將此值設定為 true。例如，您可以使用此設定讓瀏覽器在不同的自動程式碼 UI 測試之間保持執行。
DeploymentEnabled	true	如果您將此值設定為 false，就不會將您在測試方法中指定的部署項目複製到部署目錄中。
CaptureTraceOutput	true	您可以使用 Trace.WriteLine 從測試方法寫入偵錯追蹤。
DeleteDeploymentDirectoryAfterTestRunIsComplete	true	若要在測試回合之後保留部署目錄，請將此值設定為 false。
MapInconclusiveToFailed	false	如果測試完成，但狀態結果不明，則通常對應至 [測試總管] 中的已略過狀態。如果您要讓結果不明的測試顯示為 [失敗]，請將此值設定為 true。
InProcMode	false	如果您要在 MSTest 配接器的相同處理序中執行測試，請將此值設定為 true。這個設定提供較小效能。但如果測試因例外狀況而結束，則不會執行其餘測試。
AssemblyResolution	false	您可以在求解及執行單元測試時，指定其他組件的路徑。例如，您可以針對與測試組件位於不同目錄的相依性組件，使用這些路徑。若要指定路徑，請使用目錄路徑項目。路徑可以包括環境變數。 `<AssemblyResolution> <Directory path="D:\myfolder\bin\" includeSubDirectories="false"/> </AssemblyResolution>`

.Runsettings 檔案範例

下列 XML 顯示一般 .runsettings 檔案的內容。複製此程式碼，並根據需求編輯。

檔案的每個項目都有預設值，因此為選擇性。

<?xml version="1.0" encoding="utf-8"?>
<RunSettings>
  <!-- Configurations that affect the Test Framework -->
  <RunConfiguration>
    <!-- Use 0 for maximum process-level parallelization. This does not force parallelization within the test DLL (on the thread-level). You can also change it from the Test menu; choose "Run tests in parallel". Unchecked = 1 (only 1), checked = 0 (max). -->
    <MaxCpuCount>1</MaxCpuCount>
    <!-- Path relative to directory that contains .runsettings file-->
    <ResultsDirectory>.\TestResults</ResultsDirectory>

    <!-- Omit the whole tag for auto-detection. -->
    <!-- [x86] or x64, ARM, ARM64, s390x  -->
    <!-- You can also change it from the Test menu; choose "Processor Architecture for AnyCPU Projects" -->
    <TargetPlatform>x86</TargetPlatform>

    <!-- Any TargetFramework moniker or omit the whole tag for auto-detection. -->
    <!-- net48, [net40], net6.0, net5.0, netcoreapp3.1, uap10.0 etc. -->
    <TargetFrameworkVersion>net40</TargetFrameworkVersion>

    <!-- Path to Test Adapters -->
    <TestAdaptersPaths>%SystemDrive%\Temp\foo;%SystemDrive%\Temp\bar</TestAdaptersPaths>

    <!-- TestSessionTimeout was introduced in Visual Studio 2017 version 15.5 -->
    <!-- Specify timeout in milliseconds. A valid value should be greater than 0 -->
    <TestSessionTimeout>10000</TestSessionTimeout>

    <!-- true or false -->
    <!-- Value that specifies the exit code when no tests are discovered -->
    <TreatNoTestsAsError>true</TreatNoTestsAsError>
  </RunConfiguration>

  <!-- Configurations for data collectors -->
  <DataCollectionRunSettings>
    <DataCollectors>
      <DataCollector friendlyName="Code Coverage" uri="datacollector://Microsoft/CodeCoverage/2.0" assemblyQualifiedName="Microsoft.VisualStudio.Coverage.DynamicCoverageDataCollector, Microsoft.VisualStudio.TraceCollector, Version=11.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
        <Configuration>
          <CodeCoverage>
            <ModulePaths>
              <Exclude>
                <ModulePath>.*CPPUnitTestFramework.*</ModulePath>
              </Exclude>
            </ModulePaths>

            <!-- We recommend you do not change the following values: -->
            <UseVerifiableInstrumentation>True</UseVerifiableInstrumentation>
            <AllowLowIntegrityProcesses>True</AllowLowIntegrityProcesses>
            <CollectFromChildProcesses>True</CollectFromChildProcesses>
            <CollectAspDotNet>False</CollectAspDotNet>

          </CodeCoverage>
        </Configuration>
      </DataCollector>

      <DataCollector uri="datacollector://microsoft/VideoRecorder/1.0" assemblyQualifiedName="Microsoft.VisualStudio.TestTools.DataCollection.VideoRecorder.VideoRecorderDataCollector, Microsoft.VisualStudio.TestTools.DataCollection.VideoRecorder, Version=15.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" friendlyName="Screen and Voice Recorder">
        <!--Video data collector was introduced in Visual Studio 2017 version 15.5 -->
        <Configuration>
          <!-- Set "sendRecordedMediaForPassedTestCase" to "false" to add video attachments to failed tests only -->
          <MediaRecorder sendRecordedMediaForPassedTestCase="true"  xmlns="">           
            <ScreenCaptureVideo bitRate="512" frameRate="2" quality="20" />
          </MediaRecorder>
        </Configuration>
      </DataCollector>

      <!-- Configuration for blame data collector -->
      <DataCollector friendlyName="blame" enabled="True">
      </DataCollector>

    </DataCollectors>
  </DataCollectionRunSettings>

  <!-- Parameters used by tests at run time -->
  <TestRunParameters>
    <Parameter name="webAppUrl" value="http://localhost" />
    <Parameter name="webAppUserName" value="Admin" />
    <Parameter name="webAppPassword" value="Password" />
  </TestRunParameters>

  <!-- Configuration for loggers -->
  <LoggerRunSettings>
    <Loggers>
      <Logger friendlyName="console" enabled="True">
        <Configuration>
            <Verbosity>quiet</Verbosity>
        </Configuration>
      </Logger>
      <Logger friendlyName="trx" enabled="True">
        <Configuration>
          <LogFileName>foo.trx</LogFileName>
        </Configuration>
      </Logger>
      <Logger friendlyName="html" enabled="True">
        <Configuration>
          <LogFileName>foo.html</LogFileName>
        </Configuration>
      </Logger>
      <Logger friendlyName="blame" enabled="True" />
    </Loggers>
  </LoggerRunSettings>

  <!-- Adapter Specific sections -->

  <!-- MSTest adapter -->
  <MSTest>
    <MapInconclusiveToFailed>True</MapInconclusiveToFailed>
    <CaptureTraceOutput>false</CaptureTraceOutput>
    <DeleteDeploymentDirectoryAfterTestRunIsComplete>False</DeleteDeploymentDirectoryAfterTestRunIsComplete>
    <DeploymentEnabled>False</DeploymentEnabled>
    <AssemblyResolution>
      <Directory path="D:\myfolder\bin\" includeSubDirectories="false"/>
    </AssemblyResolution>
  </MSTest>

</RunSettings>

在 .runsettings 檔案中指定環境變數

您可以在 .runsettings 檔案中設定環境變數，以便直接與測試主機互動。需要在 .runsettings 檔案中指定環境變數，才能支援需要設定環境變數（例如 DOTNET_ROOT）的重要專案。這些變數會在產生測試主機進程時設定，並可在主機中使用。

範例

下列程式碼是傳遞環境變數的 .runsettings 檔案：

<?xml version="1.0" encoding="utf-8"?>
<!-- File name extension must be .runsettings -->
<RunSettings>
  <RunConfiguration>
    <EnvironmentVariables>
      <!-- List of environment variables we want to set-->
      <DOTNET_ROOT>C:\ProgramFiles\dotnet</DOTNET_ROOT>
      <SDK_PATH>C:\Codebase\Sdk</SDK_PATH>
    </EnvironmentVariables>
  </RunConfiguration>
</RunSettings>

RunConfiguration 節點應包含 EnvironmentVariables 節點。您可以將環境變數指定為專案名稱和其值。

注意

因為這些環境變數應該一律在測試主機啟動時設定，所以測試應該一律在個別的進程中執行。如此一來，當有環境變數時，就會設定 /InIsolation 旗標，讓測試主機一律會被叫用。