服务器模式

MTP 服务器模式允许编辑器、IDE、自定义测试 UI 或其他测试工具通过 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>

该示例在以下情况下返回 0:每个选中的 UID 都有最终结果,且每个未被取代的最终结果都报告 passed 或 skipped;如果存在不成功或缺失的最终结果,则返回 2;当发现阶段没有返回任何测试时,则返回 8。 这些决策属于示例客户端。 已完成 RunTestsAsync 的任务意味着协议请求已完成,而不是测试通过。 MtpRunResult.Artifacts 包含运行产物,而不是通过/失败的判定。 使用 test-node 更新来确定测试结果。

多个结果可以共享 UID。 该示例仅当 为 时,才会忽略先前的重试尝试;仅凭 UID 相等并不能确定为重试。 后续通过或跳过的结果无法消除先前未被取代的失败。

使用更新和元数据

在发现或执行之前,先订阅 TestNodesUpdated。 从每个更新中读取 Changes,并通过 Uid 标识节点。 客户端提供便利属性,例如DisplayName,ExecutionStateErrorMessage和DurationInMilliseconds。 请阅读 Node 字典以了解其他序列化字段,包括 traits 和特定于框架的属性。

MSTest 会将测试类别和自定义的 TestProperty 值作为特征发布。 元数据可用性取决于测试框架及其在发现过程中发布的内容。 任意属性和内存中的 IProperty 实现不会自动跨越进程边界。 若要发布可移植键值元数据,请使用公共 TestMetadataProperty 类型。 平台层和兼容层可以提供其他可序列化字段;它们的内部属性类型不属于是扩展 API。 有关详细信息,请参阅 Test-node 属性。

不要期望 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 开始,设置可为 null 的 MtpServerClientOptions.IsStateful 选项以描述客户端如何使用测试节点更新:

Value 声明
true 客户端保留会话的可寻址测试节点集,并保持每个节点的最后已知状态,直到后续更新将其更改,就像 IDE 测试资源管理器可能做的那样。
false 客户端使用更新而不保留该测试节点状态。
null(默认值) 客户端不声明该能力。 初始化握手省略字段。

客户端通过实验 capabilities.testing.isStateful 协议功能发送显式布尔值。 有状态性独立于连接生命周期以及服务器的 MultiRequestSupport 功能。 客户端不会仅仅因为通过同一连接发送多个请求而变得有状态。

MTP 2.4.0 使用默认值为 false 的非 null 布尔选项。 若要保留未声明的功能,请使用 MTP 2.4.1 或更高版本。

在框架或扩展内,使用实验性的 IClientInfo 服务 来检查声明。 读取 clientInfo.Capabilities.IsStateful 以获取保守的布尔结果,即当功能未声明时为 false。 在 MTP 2.4.1 或更高版本中, ClientCapabilitiesExtensions.GetIsStateful() 保留未声明、显式无状态和有状态客户端之间的区别。

协商协议兼容性

从 MTP 2.4 开始,服务器模式协议协商独立于 MTP NuGet 包版本。 客户端声明它支持的协议版本,服务器选择一个通用版本。 当没有共同支持的版本时,测试应用程序会以 ProtocolError 退出代码 (12) 退出,而不是继续使用不兼容的通信协议约定。

使用带版本号的 server-mode 1.0 JSON 架构 来验证消息。 System.Text.Json 和 Jsonite 序列化程序遵循相同的架构和错误信封。

另见