在 MTP 的上下文中, 功能 是指 执行特定操作或提供特定信息的可能性。 这是测试框架和扩展以声明其以某种方式运行或向请求者提供特定信息的能力的一种方式。
请求者 可以是测试会话中涉及的任何组件,例如平台、扩展或测试框架本身。
功能系统的主要目标是促进测试会话中涉及的组件之间的有效通信,使他们能够exchange信息并准确满足各自的需求。
引导式示例
让我们考虑一个假设示例来演示功能系统的必要性。
注意
此示例纯粹是为了说明目的,目前未在 MTP 或任何测试框架中实现。
假设你有一个扩展,该扩展要求测试框架一次执行不超过一个测试。 此外,每次测试后,扩展都需要知道该特定测试的 CPU 使用率。
若要适应上述方案,需要从测试框架查询以下情况:
- 它一次只能执行一个测试。
- 它可以提供有关每个测试使用的 CPU 量的信息。
扩展如何确定测试框架是否能够在此模式下运行,并为测试会话提供 CPU 使用情况信息? 在 MTP 中,此功能由 Microsoft.Testing.Platform.Capabilities.ICapability 接口的实现表示:
// Base capabilities contracts
public interface ICapability
{
}
public interface ICapabilities<TCapability>
where TCapability : ICapability
{
IReadOnlyCollection<TCapability> Capabilities { get; }
}
// Specific testing framework capabilities
public interface ITestFrameworkCapabilities : ICapabilities<ITestFrameworkCapability>
{
}
public interface ITestFrameworkCapability : ICapability
{
}
如你所看到的那样,ICapability 接口是一个标记接口,因为它可以表示任何功能,其实际实现取决于上下文。 你还将观察 ITestFrameworkCapability,它从 ICapability 继承以对功能进行分类。 功能系统的泛型性质允许按上下文方便地分组。
ITestFrameworkCapability 会对由测试框架实现的所有功能进行分组。
ICapabilities<TCapability> 接口显示扩展实现的所有功能的集合。 同样,对于基础版本,有一个特定于语境的测试框架名为 ITestFrameworkCapabilities。 在ITestFrameworkCapabilities过程中, 会提供给平台。
若要创建解决上述方案的功能,请按如下方式定义它:
public interface IDisableParallelismCapability : ITestFrameworkCapability
{
bool CanDisableParallelism { get; }
bool CanProvidePerTestCpuConsumption { get; }
void Enable();
}
如果测试框架在运行时实现此接口,可以查询以下内容:
- 验证测试框架是否能够关闭并行
CanDisableParallelism = true。 - 确定测试框架能否提供
CanProvidePerTestCPUConsumption = trueCPU 使用情况数据。 - 在测试会话开始之前调用
Enable()方法,请求测试适配器激活此模式。
扩展内的假设代码片段可能类似于:
IServiceProvider serviceProvider = null; // TODO: Get IServiceProvider.
var capabilities = serviceProvider.GetRequiredService<ITestFrameworkCapabilities>();
// Utilize the `GetCapability` API to search for the specific capability to query.
var capability = capabilities.GetCapability<IDisableParallelismCapability>();
if (capability is null)
{
// Capability not supported...
}
else
{
capability.Enable();
if (capability.CanDisableParallelism)
{
// Do something...
}
if (capability.CanProvidePerTestCpuConsumption)
{
// Do something...
}
}
前面的示例演示了功能基础结构如何启用强大的机制,以便在测试会话中涉及的组件之间进行通信能力。 虽然该示例演示了专为测试框架设计的一项功能,但任何组件都可以公开和实现继承自 ICapability的扩展。
很明显,并非所有细节都可以通过接口进行通信。 考虑到前面的示例,如果支持 CanProvidePerTestCpuConsumption,扩展应该有什么期望? 测试框架预计通过 IMessageBus 传输哪种类型的自定义信息? 解决方案是功能的文档。 功能所有者有责任尽可能清晰地设计、运送和记录它,以使用需要特定功能的扩展来协助想要有效地进行协作的实施者。
例如,TRX 报表扩展使测试框架能够实施必要的功能来准确生成 TRX 报表。 要注册的扩展包含在https://www.nuget.org/packages/Microsoft.Testing.Extensions.TrxReportNuGet 包中,但要实现的功能位于仅含协定的包中。
最后,让我们总结一下功能系统的主要方面:
- 它对于促进组件之间清晰稳定的通信至关重要。
- 所有功能都应继承自
ICapability或从中继承的接口,并通过具有ICapabilities接口的集合公开。 - 它有助于特征的演变,而不会造成重大更改。 如果某些功能不受支持,可以采取适当的措施。
- 设计、运输和记录功能使用情况的责任在于 功能所有者。 MTP 还可以像其他任何扩展一样 拥有 一项功能。
框架功能
平台公开了一个名为 ITestFrameworkCapability 的专用接口,该接口是所有针对测试框架公开功能的基础。
将测试框架注册到平台时,将提供这些功能。
IBannerMessageOwnerCapability
可选的 测试框架功能 允许测试框架向平台提供横幅消息。 如果消息为 null 或不具备该功能,平台将使用默认的横幅消息。
使用此功能实现,可以抽象化测试框架在决定是否显示横幅消息时可能需要考虑的各种条件。
平台公开 IPlatformInformation 服务,提供有关生成自定义横幅消息时可能有用的平台的一些信息。
ITrxReportCapability
若要向 TRX 报表扩展提供特定于框架的元数据,请实现 Microsoft.Testing.Extensions.TrxReport.Abstractions.ITrxReportCapability。 在你的框架中引用 Microsoft.Testing.Extensions.TrxReport.Abstractions 包。 测试应用程序还需要 Microsoft.Testing.Extensions.TrxReport 包用于创建报表。
此功能将支持与激活分开:
- 当框架可提供 TRX 元数据时,从
true返回IsSupported。 - 在
Enable()中,记录 TRX 报告程序请求了元数据。 启用 TRX 报告时,报告器在测试会话开始时调用此方法。 - 激活后,将 TRX 属性添加到你的框架所发布的测试节点。
以下功能存储激活状态。 示例项目面向.NET 10,并引用 MTP 2.5.1:
internal sealed class TrxCapability : ITrxReportCapability
{
public bool IsSupported => true;
public bool IsEnabled { get; private set; }
public void Enable() => IsEnabled = true;
}
Friend NotInheritable Class TrxCapability
Implements ITrxReportCapability
Public ReadOnly Property IsSupported As Boolean Implements ITrxReportCapability.IsSupported
Get
Return True
End Get
End Property
Public Property IsEnabled As Boolean
Get
Return _isEnabled
End Get
Private Set(value As Boolean)
_isEnabled = value
End Set
End Property
Private _isEnabled As Boolean
Public Sub Enable() Implements ITrxReportCapability.Enable
IsEnabled = True
End Sub
End Class
返回从 capabilitiesFactory 传递给 RegisterTestFramework 的功能。 为框架提供相同的 capability 实例,以便它可以观察 Enable()。 对于手动组合的测试应用程序,请在框架和其他扩展之后注册 TRX 提供程序:
var trxCapability = new TrxCapability();
var builder = await TestApplication.CreateBuilderAsync(args);
builder.RegisterTestFramework(
_ => new TestFrameworkCapabilities(trxCapability),
(_, _) => new ReportFramework(trxCapability));
builder.AddTrxReportProvider();
Dim trxCapability As New TrxCapability()
Dim builder = Await TestApplication.CreateBuilderAsync(args)
builder.RegisterTestFramework(
Function(services) New TestFrameworkCapabilities(trxCapability),
Function(capabilities, services) New ReportFramework(trxCapability))
builder.AddTrxReportProvider()
所需的测试节点数据
若要报告测试结果,请发布包含以下数据的 TestNodeUpdateMessage:
- 设置必需
TestNode.Uid成员和TestNode.DisplayName成员。 - 仅包括一个最终状态属性:
PassedTestNodeStateProperty、ErrorTestNodeStateProperty、FailedTestNodeStateProperty、TimeoutTestNodeStateProperty或SkippedTestNodeStateProperty。 - 若要为 UID 创建测试定义,请在
TestNode.Properties中包含TrxFullyQualifiedTypeNameProperty或TestMethodIdentifierProperty。
报告程序会忽略没有状态的更新、DiscoveredTestNodeStateProperty 或 InProgressTestNodeStateProperty。 在最终更新本身中包含标识和报告元数据。 报告工具不会沿用发现或进行中更新中的元数据。
对于 TestMethod/@className,报告器更倾向于 TrxFullyQualifiedTypeNameProperty。 否则,它将来自 TestMethodIdentifierProperty 的命名空间和类型名称组合起来。 对于 TestMethod/@name,它使用方法标识符的方法名称,或者 DisplayName 当不存在方法标识符时。 报告程序不会查找匹配的源文件、类或方法。 对于没有.NET方法的测试,请提供一个稳定的类标签。TrxFullyQualifiedTypeNameProperty
Important
在当前报告程序中,不具有任何一个标识属性的新测试定义会在生成报表期间导致一个 InvalidOperationException。 既不DisplayName也不TestFileLocationProperty替换所需的类标识。
可选报表属性
下表中的所有属性都是可选的。 这些 Trx* 属性来自 TRX 抽象包;其他属性来自 MTP。
| Property | Purpose |
|---|---|
TimingProperty |
通过 GlobalTiming 提供每项测试的开始时间、结束时间和持续时间。 |
TrxCategoriesProperty |
将类别添加到共享测试定义。 |
TrxExceptionProperty |
提供结果的错误消息和堆栈跟踪。 失败、错误和超时状态仍会生成失败的结果,但缺少错误详细信息。 |
TrxMessagesProperty |
包含StandardErrorTrxMessage、StandardOutputTrxMessage和DebugOrTraceTrxMessage条目,它们映射到结果的StdOut、StdErr和DebugTrace元素。 |
TrxTestDefinitionName |
设置 TestDefinitions/UnitTest/@name。 省略时,默认为 DisplayName。 |
TrxWorkItemsProperty |
将工作项标识符添加到共享测试定义。 |
TestMetadataProperty |
Priority、Description和Owner映射到相应的测试定义字段。 优先级必须解析为不等于 int.MaxValue 的整数。 其他键将成为 Properties/Property 包含 Key 子元素和 Value 子元素的条目。 |
FileArtifactProperty |
将每个测试的附件文件复制到结果布局中,并从 UnitTestResult/ResultFiles 引用它们。 文件未嵌入到 TRX XML 中。 |
如果没有 TimingProperty,则结果的持续时间为 00:00:00,并且生成 startTime 结果 XML 时使用 endTime 当前 UTC 时间。 报告器不会重建执行时序。
通过 TrxMessagesProperty 容器添加消息。 消息对象,如 StandardOutputTrxMessage 不实现 IProperty ,不能直接添加到 TestNode.Properties。
除了 FileArtifactProperty 和 TestMetadataProperty 外,在节点上,此处描述的每个属性最多只能提供一个实例。 对多个消息、类别或工作项标识符使用相应的容器集合。 报告器拒绝重复的单例属性。
当 UID 重复时,报告器将保留第一个测试定义。 如果任何出现项提供 TrxTestDefinitionName,则每个匹配项的有效定义名称(无论是显式名称还是 DisplayName 回退值)都必须一致。 否则,报表生成将引发一个 InvalidOperationException。 如果所有匹配项都省略该属性,则允许不同的显示名称。
例如,在框架确定测试结果后,提供所需的类标识和可选扩充:
if (trxCapability.IsEnabled)
{
testNode.Properties.Add(
new TrxFullyQualifiedTypeNameProperty("Contoso.CalculatorTests"));
testNode.Properties.Add(new TrxCategoriesProperty(["Unit"]));
testNode.Properties.Add(new TrxMessagesProperty(
[new StandardOutputTrxMessage($"Captured output for {test.Name}.")]));
if (failure is not null)
{
testNode.Properties.Add(
new TrxExceptionProperty(failure.Message, failure.StackTrace));
}
}
If _trxCapability.IsEnabled Then
testNode.Properties.Add(
New TrxFullyQualifiedTypeNameProperty("Contoso.CalculatorTests"))
testNode.Properties.Add(New TrxCategoriesProperty({"Unit"}))
testNode.Properties.Add(New TrxMessagesProperty(
{New StandardOutputTrxMessage($"Captured output for {test.Name}.")}))
If failure IsNot Nothing Then
testNode.Properties.Add(
New TrxExceptionProperty(failure.Message, failure.StackTrace))
End If
End If
TRX 不使用平台的 StandardOutputProperty 和 StandardErrorProperty。 若要在终端输出和 TRX 中包含捕获的文本,请提供平台输出属性和 TRX 消息容器。
完整示例包含一个通过的测试,一个有意失败的测试。 使用 --report-trx 时,它将结果和扩充的元数据都写入 TRX 文件,然后返回退出代码 2。 若要仅运行通过的测试,请添加 --filter-uid trx.pass。
如果该功能不存在,或者 IsSupported 为 false,TRX 报告器会警告该框架不支持 TRX 增强。 如果最终测试节点包含所需的标识数据,则报告器仍然可以创建报告。 警告不会免除这些要求。 除非框架提供相应的元数据,否则不要声明支持。
IGracefulStopTestExecutionCapability
若要在自定义测试框架中支持 --maximum-failed-tests ,请实现 Microsoft.Testing.Platform.Capabilities.TestFramework.IGracefulStopTestExecutionCapability。 该功能是 Microsoft.Testing.Platform 包的一部分,从 MTP 1.5 开始可用。 使用已支持该选项的框架的测试作者无需实现该功能。
接口定义 Task StopTestExecutionAsync(CancellationToken cancellationToken)。 当失败计数达到请求的最大值时,MTP 将调用此方法。 你的实现必须告知框架停止安排新测试,同时允许已经开始的测试完成、运行清理并发布其结果。
Important
该功能与 AddMaximumFailedTestsService 帮助程序是实验性 API,会产生编译器诊断 TPEXP。 其合同可以更改或删除。 示例项目显式抑制 TPEXP。
实现该功能时,请遵循以下要求:
- 在能力与框架的测试调度程序之间共享停止状态。 仅返回已完成的任务不会停止测试。
- 使停止请求线程安全且幂等。 多个平台组件可以请求停止。
- 在发出停止信号后返回。 不要等待整个运行或消息总线完成:MTP 可以在处理测试结果时调用该方法,因此该等待可能导致死锁。
- 将正常停止状态与请求取消分开。 不要为实施正常停止而终止进程或取消结果发布。 如果停止操作需要异步工作,请响应该方法的取消令牌。
- 在活动测试完成后,完成正常的请求生命周期,包括结果发布、清理和调用
ExecuteRequestContext.Complete()。
以下实现使用线程安全标志。 在框架中,在安排每项测试之前,检查IsStopRequested,并当标志为true时停止接收新工作。
public sealed class GracefulStopCapability : IGracefulStopTestExecutionCapability
{
private int _stopRequested;
public bool IsStopRequested => Volatile.Read(ref _stopRequested) != 0;
public Task StopTestExecutionAsync(CancellationToken cancellationToken)
{
cancellationToken.ThrowIfCancellationRequested();
Interlocked.Exchange(ref _stopRequested, 1);
return Task.CompletedTask;
}
}
Public NotInheritable Class GracefulStopCapability
Implements IGracefulStopTestExecutionCapability
Private _stopRequested As Integer
Public ReadOnly Property IsStopRequested As Boolean
Get
Return Volatile.Read(_stopRequested) <> 0
End Get
End Property
Public Function StopTestExecutionAsync(cancellationToken As CancellationToken) As Task _
Implements IGracefulStopTestExecutionCapability.StopTestExecutionAsync
cancellationToken.ThrowIfCancellationRequested()
Interlocked.Exchange(_stopRequested, 1)
Return Task.CompletedTask
End Function
End Class
通过 ITestFrameworkCapabilities.Capabilities 公开功能。 注册示例使用 MTP 的 TestFrameworkCapabilities 集合。
在 测试框架注册 期间,将注册的功能实例传递给您的框架。 以下帮助程序接受您的框架工厂和一个拥有命令行选项的 IExtension。 它还从AddMaximumFailedTestsService命名空间调用Microsoft.Testing.Platform.Helpers以注册--maximum-failed-tests选项提供程序。 没有该提供程序,MTP 将无法识别该选项。
public static void Register(
ITestApplicationBuilder builder,
IExtension owner,
Func<GracefulStopCapability, ITestFramework> createFramework)
{
builder.RegisterTestFramework(
_ => new TestFrameworkCapabilities(new GracefulStopCapability()),
(capabilities, _) => createFramework(
capabilities.Capabilities.OfType<GracefulStopCapability>().Single()));
builder.AddMaximumFailedTestsService(owner);
}
Public Sub Register(
builder As ITestApplicationBuilder,
owner As IExtension,
createFramework As Func(Of GracefulStopCapability, ITestFramework))
builder.RegisterTestFramework(
Function(services) New TestFrameworkCapabilities(New GracefulStopCapability()),
Function(capabilities, services) createFramework(
capabilities.Capabilities.OfType(Of GracefulStopCapability)().Single()))
builder.AddMaximumFailedTestsService(owner)
End Sub
功能工厂创建全新的停止状态,框架工厂检索同一实例。 不要在您的框架中创建第二个断开连接的功能。 对于支持多个运行请求的框架,请保持停止状态的范围限定为相应的执行。 执行开始时,不要清除已接受的停止请求。
如果已注册选项提供程序,但框架未暴露此能力,MTP 会在命令行验证期间拒绝 --maximum-failed-tests。 当失败阈值触发停止时,MTP 返回 退出代码 13。 最终失败计数可能超过阈值,因为结果处理是异步的,并且测试可能已经在进行中。
有关接口协定,请参阅 IGracefulStopTestExecutionCapability 源。