MTP 伺服器模式允許編輯器、IDE、自訂測試介面或其他測試工具啟動測試應用程式,並透過 JSON-RPC 推動發現與執行。 當你的工具需要測試元資料、選取測試執行、進度更新或結果產出,且不想解析終端輸出時,請使用伺服器模式。 對於一般的命令列與 CI 執行,請直接執行測試應用程式或使用 dotnet test。
若要進行無持續連線的單次發現,請使用 --list-tests json。 對於現有的 VSTest 用戶端,請參見 程式化測試的發現與執行。
使用 --server jsonrpc 或 --server 啟動公開的 JSON-RPC 伺服器。
Important
.NET SDK 透過 --server dotnettestcli 使用獨立的內部二進位通訊協定。 不要自行傳遞該值。
dotnet test 配置傳輸與協定參數。
使用純源碼用戶端
MTP 2.4 提供一個標準的 JSON-RPC 用戶端。 新增 Microsoft.Testing.Platform.ServerMode.Client.Sources 套件。 這個套件會把 C# 原始碼注入你的專案,而不是直接加入執行時的組合語言。
純源設計提供:
- 沒有執行時的 DLL 或額外的部署依賴。
- 原生 AOT 相容、無反射序列化。
- 協定類型與序列化程式碼來自與 MTP 伺服器相同的儲存庫。
注入的 MtpServerClient、 IMtpServerClient和 協定類型可以初始化連線、發現測試、執行測試、請求伺服器退出,以及回報測試節點更新。 所有注入型態仍留 internal 在消費組件中。 用戶端負責程序啟動、傳輸、訊息框架與序列化;你不需要自己實作 JSON-RPC。
該套件會編譯 C# 原始碼。 若要從 Visual Basic 或其他 .NET 語言使用此用戶端,請參考一個 C# 類別函式庫,該函式庫會圍繞注入型別公開你自己的 API,如下列範例所示。
探索並執行 .NET 測試
此範例使用僅含原始碼的用戶端套件版本 2.5.2,目標為 .NET 10。 先建置一個支援 MTP 的測試應用程式,然後將其已建置的 .dll 或可執行檔路徑傳遞給用戶端。
共享的 C# 輔助程式會發現測試,列印每個節點可序列化的元資料,並透過 UID 執行發現的測試。 要執行子集,從發現更新中選擇所需的 UID,並只將這些 UID 傳給 RunTestsAsync。 不要用顯示名稱作為測試識別。
using System.Text.Json;
using Microsoft.Testing.Platform.ServerMode.Client;
namespace TestClientSample;
public static class TestClient
{
public static async Task<int> DiscoverAndRunAsync(
string testApplicationPath,
CancellationToken cancellationToken = default)
{
string path = Path.GetFullPath(testApplicationPath);
var testUids = new HashSet<string>(StringComparer.Ordinal);
using (IMtpServerClient client = await MtpServerClient.LaunchAsync(
path, cancellationToken: cancellationToken))
{
try
{
MtpServerCapabilities capabilities =
await client.InitializeAsync(cancellationToken);
if (capabilities.MultiConnectionProvider)
{
throw new NotSupportedException("A passive controller connection can't discover or run tests.");
}
if (!capabilities.SupportsDiscovery)
{
throw new NotSupportedException("The test application doesn't support discovery.");
}
client.LogReceived += (_, log) => Console.Error.WriteLine(log.Message);
client.TestNodesUpdated += (_, update) =>
{
foreach (MtpTestNodeUpdate change in update.Changes)
{
Console.WriteLine(JsonSerializer.Serialize(change.Node));
if (change.NodeType != "group"
&& change.ExecutionState == "discovered"
&& change.Uid is string uid)
{
testUids.Add(uid);
}
}
};
await client.DiscoverTestsAsync(cancellationToken);
await client.ExitAsync(cancellationToken);
}
finally
{
await client.ShutdownAsync();
}
}
if (testUids.Count == 0)
{
Console.Error.WriteLine("No tests were discovered.");
return 8;
}
var completedUids = new HashSet<string>(StringComparer.Ordinal);
bool hasUnsuccessfulResult = false;
using IMtpServerClient runClient = await MtpServerClient.LaunchAsync(
path, cancellationToken: cancellationToken);
try
{
MtpServerCapabilities capabilities =
await runClient.InitializeAsync(cancellationToken);
if (capabilities.MultiConnectionProvider)
{
throw new NotSupportedException("A passive controller connection can't discover or run tests.");
}
runClient.LogReceived += (_, log) => Console.Error.WriteLine(log.Message);
runClient.TestNodesUpdated += (_, update) =>
{
foreach (MtpTestNodeUpdate change in update.Changes)
{
Console.WriteLine(JsonSerializer.Serialize(change.Node));
if (change.Uid is string uid
&& testUids.Contains(uid)
&& change.ExecutionState is string state
&& state is not ("discovered" or "in-progress")
&& (!change.Node.TryGetValue("retry.is-superseded", out object? superseded)
|| superseded is not true))
{
completedUids.Add(uid);
hasUnsuccessfulResult |= state is not ("passed" or "skipped");
}
}
};
MtpRunResult result = await runClient.RunTestsAsync(testUids, cancellationToken);
foreach (MtpAttachment artifact in result.Artifacts)
{
Console.WriteLine($"Artifact: {artifact.Uri}");
}
await runClient.ExitAsync(cancellationToken);
if (hasUnsuccessfulResult || !testUids.All(completedUids.Contains))
{
Console.Error.WriteLine("A selected test failed or didn't report a final result.");
return 2;
}
return 0;
}
finally
{
await runClient.ShutdownAsync();
}
}
}
助手會啟動一個獨立的測試程序來進行發現與執行,因此不需要 MtpServerCapabilities.MultiRequestSupport。 要重複使用一個程序,請在 InitializeAsync 之後再發出多個請求前先檢查該功能。 在申請證據披露前也請先確認 SupportsDiscovery 。
Important
僅限來源用戶端的啟動輔助工具會管理一個 JSON-RPC 連線。 在 2.5.2 版本中,他們不再接受並路由由控制器支援的擴充功能所使用的額外連線。 例如,Windows 上的 TRX 記錄可以啟動一個控制器,其被動連線比主動測試主機還早抵達。 將 MultiConnectionProvider 設為 true 的連線只會推送更新和產物;不要向它傳送探索或執行要求。 這個範例拒絕該連線。
對於由控制器支援的報告,請透過 CLI 或 dotnet test 執行測試應用程式,或使用可處理該協定額外連線的工具用戶端。 單一連線的用戶端仍可接收目前啟用的測試主機發佈的成品。
C# 和 Visual Basic 的主控台專案都參考了 C# 輔助專案:
using TestClientSample;
if (args.Length != 1)
{
Console.Error.WriteLine("Usage: DiscoverAndRun <test-application-path>");
return 1;
}
return await TestClient.DiscoverAndRunAsync(args[0]);
執行任一主控台專案,並以測試應用程式路徑作為參數:
dotnet run --project <client-project> -- <test-application-path>
當每個選取的 UID 都有最終結果,且每個未被取代的最終結果都回報 skipped 或 2 時,該範例會回傳 passed;若最終結果未成功或缺失,則回傳 0;當探索未傳回任何測試時,則回傳 8。 這些決策屬於範例客戶。 已完成的 RunTestsAsync 任務是指協定請求已完成,而非測試通過。
MtpRunResult.Artifacts 包含執行產物,而非通過/不通過的判定。 利用 test-node 更新來判斷測試結果。
多個結果可能會共用一個 UID。 僅當 retry.is-superseded 為 true 時,範例才會忽略先前較早的重試嘗試;僅有 UID 相等並不代表有重試。 後來通過或跳過的結果無法抹去之前未被取代的失敗。
取用更新與中繼資料
在發現或執行前訂閱TestNodesUpdated。 從每次更新讀取 Changes ,並以 Uid來識別節點。 客戶端提供便利屬性,如 DisplayName、ExecutionState、ErrorMessage 及 DurationInMilliseconds。 閱讀 Node 字典以了解其他序列化欄位,包括 traits 和 框架特有的屬性。
MSTest 會將測試類別和自訂 TestProperty 值作為特性發佈。 元資料的可用性取決於測試框架及其在探索期間發布的內容。 任意屬性和記憶體中的 IProperty 實作不會自動跨越行程邊界。 若要發佈可攜式的鍵值元資料,請使用公開 TestMetadataProperty 型別。 平台層與相容層可提供其他可序列化欄位;它們的內部屬性類型不是擴充 API。 詳情請參見 測試節點屬性。
不要期待 JSON-RPC 節點字典會與 --list-tests json 文件 相符。 傳輸採用不同的欄位配置。 另外,不要假設每個框架都會輸出 VSTest 專屬 vstest.* 欄位。
用戶端會依序處理更新,並在發現或執行任務完成前呼叫相應的處理器。 你不需要延遲即可等待最終更新。 處理器在用戶端的讀取迴圈中同步執行,因此不要阻擋它們或同步等待下一個用戶端操作。 將昂貴的工作或 UI 更新派遣到適當的執行緒。
將取消標記傳遞給發現,或執行方法透過協定請求取消。 如果測試框架支援樹狀過濾器,可以使用 DiscoverTestsWithFilterAsync 或 RunTestsWithFilterAsync 搭配 MTP 樹狀過濾器表達式來選擇測試,而不必先建立 UID 集合。 這些方法不接受 VSTest --filter 表達式。
滿足客戶需求
使用 C# 12 或更新版本。 該套件會尊重你專案的語言版本設定。 如果你的目標框架預設是較早的 C# 版本,請將 LangVersion 設為 12.0 或更新版本。 此套件也提供 .NET Framework 4.6.2 及 netstandard2.0 的內部相容類型。
在新增套件前,請移除任何手寫的 MTP 用戶端副本,以避免內部類型重複。
選擇發射型號
若要啟動測試應用程式作為外部程序,請使用 MtpServerClient.LaunchAsync。 用戶端負責管理該子程序,並會在需要時於清理階段將其終止。
若要設定特定環境的外部測試應用程式,請在啟動前設定 MtpServerClientOptions.EnvironmentVariables 。 子程序繼承父程序的環境,並將所提供的值套用到子程序。 這些選項不會改變正在進行中的主機的環境。
每個用戶端控制一個測試應用程式。 對於多個測試應用程式,為每個應用程式建立一個客戶端,並在您的工具中彙整結果。
對於無法使用 Process.Start的嵌入式主機或 UI 執行緒環境,請使用 MtpServerClient.LaunchInProcessAsync。 此方法在當前程序中透過非同步回調執行測試應用程式。 不要封鎖啟動執行緒,因為回調和客戶端會共用流程。
兩款上市型號皆使用迴圈 TCP 傳輸。 瀏覽器 WebAssembly 無法建立所需的監聽器,因此啟動過程中會拋 PlatformNotSupportedException出 。 程序內啟動不提供替代的 WebAssembly 傳輸機制。
關閉客戶端
若要關閉客戶端及已啟動的應用程式而不阻擋呼叫執行緒,請呼叫 IMtpServerClient.ShutdownAsync()。 非同步方法避免了嵌入式主機中 UI 執行緒響應性及死鎖問題。
對於處理序內主機,MtpServerClientOptions.ServerShutdownTimeout 會控制用戶端關閉傳輸後,終止作業等待的時間。 預設值為 30 秒。 在關閉後讀取 ServerExitCode,以取得回呼的結束代碼。 該值在應用程式執行或失敗時保持不變 null ,而非回傳退出碼。
宣告用戶端有狀態性
從 MTP 2.4.1 開始,設定 nullable MtpServerClientOptions.IsStateful 選項以描述用戶端如何處理測試節點更新:
| Value | 聲明 |
|---|---|
true |
用戶端會保留工作階段的一組可尋址測試節點,並保留每個節點最後已知的狀態,直到另一個更新改變該狀態為止,就像 IDE 測試總管一樣。 |
false |
用戶端在不保留測試節點狀態的情況下接收更新。 |
null (預設值) |
客戶端未宣告這項能力。 初始化握手(initialize handshake)省略了欄位。 |
客戶端透過實驗 capabilities.testing.isStateful 協定功能傳送明確的布林值。 狀態性與連線壽命及伺服器 MultiRequestSupport 能力無關。 客戶端不會因為在同一連線上發送多個請求而變得有狀態。
MTP 2.4.0 使用一個不可空的布林值選項,預設值為 false。 若要保留未申報的能力,請使用 MTP 2.4.1 或更新版本。
在框架或擴充功能中,使用實驗 IClientInfo 服務 檢查宣告。 請閱讀 clientInfo.Capabilities.IsStateful 以取得保守的布林結果,當該能力尚未宣告時,結果為 false。 在 MTP 2.4.1 或更新版本中,ClientCapabilitiesExtensions.GetIsStateful() 保留了未宣告、明確無狀態及有狀態客戶端之間的區別。
協商協定相容性
從 MTP 2.4 起,伺服器模式協定協商獨立於 MTP NuGet 套件版本。 用戶端宣告其支援的協定版本,伺服器則選擇一個共用版本。 當沒有支援的版本重疊時,測試應用程式會以 ProtocolError 退出碼12()退出,而非繼續使用不相容的有線合約。
使用版本化 伺服器模式 1.0 JSON 架構 來驗證訊息。 System.Text.Json 與 Jsonite 序列化器遵循相同的結構與錯誤包絡。