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> 인터페이스는 확장에서 구현하는 모든 기능의 집합을 표시합니다. 마찬가지로 기본 1의 경우 ITestFrameworkCapabilities라는 컨텍스트별 테스트 프레임워크가 있습니다.
ITestFrameworkCapabilities
테스트 프레임워크 등록 프로세스 중에 플랫폼에 제공됩니다.
앞서 언급한 시나리오를 해결하는 기능을 만들려면 다음과 같이 정의합니다.
public interface IDisableParallelismCapability : ITestFrameworkCapability
{
bool CanDisableParallelism { get; }
bool CanProvidePerTestCpuConsumption { get; }
void Enable();
}
테스트 프레임워크에서 이 인터페이스를 구현하는 경우 런타임에 다음을 쿼리할 수 있습니다.
- 테스트 프레임워크에 병렬 처리
CanDisableParallelism = true해제할 수 있는지 확인합니다. - 테스트 프레임워크에서 CPU 사용량 현황 데이터
CanProvidePerTestCPUConsumption = true제공할 수 있는지 확인합니다. - 테스트 세션이 시작되기 전에
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 보고서를 정확하게 생성하는 데 필요한 기능을 구현할 수 있습니다. 등록할 확장은 NuGet 패키지에 https://www.nuget.org/packages/Microsoft.Testing.Extensions.TrxReport 포함되지만 구현하는 기능은 계약 전용 패키지에 있습니다.
결론적으로 기능 시스템의 주요 측면을 요약해 보겠습니다.
- 구성 요소 간의 명확하고 안정적인 통신을 용이하게 하는 데 필수적입니다.
- 모든 기능은
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 메타데이터를 제공할 수 있으면
IsSupported에서true을 반환합니다. -
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
RegisterTestFramework에 전달하는 capabilitiesFactory에서 기능을 반환합니다. 프레임워크가 Enable()를 관찰할 수 있도록 동일한 capability 인스턴스를 제공합니다. 수동으로 구성된 테스트 애플리케이션의 경우 프레임워크 및 기타 확장 후에 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,FailedTestNodeStateProperty,ErrorTestNodeStateProperty,TimeoutTestNodeStateProperty또는SkippedTestNodeStateProperty. - UID에 대한 테스트 정의를 만들려면
TestNode.Properties에TrxFullyQualifiedTypeNameProperty또는TestMethodIdentifierProperty를 포함하여 작성합니다.
리포터는 상태가 없거나 DiscoveredTestNodeStateProperty, 또는 InProgressTestNodeStateProperty인 업데이트를 무시합니다. 최종 업데이트 자체에 ID 및 보고서 메타데이터를 포함합니다. 리포터는 검색 단계 또는 진행 중인 업데이트에서 메타데이터를 전달하지 않습니다.
TestMethod/@className의 경우 reporter는 TrxFullyQualifiedTypeNameProperty를 선호합니다. 그렇지 않으면 TestMethodIdentifierProperty의 네임스페이스와 형식 이름을 결합합니다.
TestMethod/@name의 경우 메서드 식별자의 메서드 이름을 사용하거나, 메서드 식별자가 없으면 DisplayName을(를) 사용합니다. 리포터는 일치하는 소스 파일, 클래스 또는 메서드를 조회하지 않습니다. .NET 메서드가 없는 테스트의 경우 안정적인 클래스 레이블을 제공하세요 TrxFullyQualifiedTypeNameProperty.
Important
현재 리포터에서 두 ID 속성 중 어느 것도 없는 새 테스트 정의는 보고서 생성 중에 InvalidOperationException를 발생시킵니다.
DisplayName도 TestFileLocationProperty도 필수 클래스 ID를 대체하지 않습니다.
선택 사항 보고서 속성
다음 표의 모든 속성은 선택 사항입니다. 속성은 Trx* TRX 추상화 패키지에서 가져옵니다. 다른 속성은 MTP에서 가져옵니다.
| Property | Purpose |
|---|---|
TimingProperty |
테스트별 시작 시간, 종료 시간 및 기간을 제공합니다 GlobalTiming. |
TrxCategoriesProperty |
공유 테스트 정의에 범주를 추가합니다. |
TrxExceptionProperty |
결과의 오류 메시지와 스택 추적을 제공합니다. 실패, 오류 및 시간 제한 상태는 이 속성 없이 실패한 결과를 생성하지만 오류 세부 정보는 없습니다. |
TrxMessagesProperty |
StandardOutputTrxMessage, StandardErrorTrxMessage, 및 StdOut 항목을 포함하며, 이는 결과의 StdErr, DebugOrTraceTrxMessage, 및 DebugTrace 요소에 매핑됩니다. |
TrxTestDefinitionName |
TestDefinitions/UnitTest/@name을 설정합니다. 생략하면 DisplayName가 기본값으로 사용됩니다. |
TrxWorkItemsProperty |
공유 테스트 정의에 작업 항목 식별자를 추가합니다. |
TestMetadataProperty |
Priority, Description 및 Owner를 해당 테스트 정의 필드에 매핑합니다. 우선 순위는 int.MaxValue가 아닌 정수로 구문 분석되어야 합니다. 다른 키는 Key 및 Properties/Property 자식 요소가 있는 Value 항목이 됩니다. |
FileArtifactProperty |
테스트별 첨부 파일을 결과 레이아웃에 복사하고 UnitTestResult/ResultFiles에서 참조합니다. 파일은 TRX XML에 포함되지 않습니다. |
TimingProperty 없으면 결과의 기간은 00:00:00이며, startTime 및 endTime는 결과 XML이 생성될 때 현재 UTC 시간을 사용합니다. 리포터는 실행 타이밍을 재구성하지 않습니다.
메시지는 TrxMessagesProperty 컨테이너를 통해 추가합니다. 메시지 객체(IProperty 등)는 TestNode.Properties를 구현하지 않으며 StandardOutputTrxMessage에 직접 추가할 수 없습니다.
TestMetadataProperty와 FileArtifactProperty를 제외하고, 노드에는 여기서 설명한 각 속성을 최대 하나씩만 제공하세요. 여러 메시지, 범주 또는 작업 항목 식별자에는 해당 컨테이너의 컬렉션을 사용합니다. 리포터는 중복된 싱글톤 속성을 거부합니다.
UID가 반복되면 리포터는 첫 번째 테스트 정의를 유지합니다. 어떤 항목에서든 TrxTestDefinitionName이 제공되면 명시적 정의 이름이든 DisplayName 대체 이름이든 관계없이 모든 항목의 유효 정의 이름이 일치해야 합니다. 그렇지 않으면 보고서 생성 시 InvalidOperationException예외를 throw합니다. 모든 항목이 속성을 생략하면 다른 표시 이름이 허용됩니다.
예를 들어 프레임워크에서 테스트 결과를 결정한 후 필수 클래스 ID 및 선택적 보강을 제공하세요.
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 메시지 컨테이너를 제공하세요.
전체 샘플에는 통과 테스트 1개와 의도적으로 실패한 테스트 하나가 포함되어 있습니다.
--report-trx를 사용하면 결과와 보강된 메타데이터를 모두 TRX 파일에 쓴 다음 종료 코드 2를 반환합니다. 통과한 테스트만 실행하려면 --filter-uid trx.pass를 추가합니다.
기능이 없거나 IsSupported이 false인 경우 TRX 리포터는 프레임워크가 TRX 보강을 지원하지 않는다고 경고합니다. 최종 테스트 노드에 필요한 ID 데이터가 포함된 경우에도 보고자는 보고서를 만들 수 있습니다. 경고가 이러한 요구 사항을 면제하지는 않습니다. 프레임워크에서 해당 메타데이터를 제공하지 않는 한 지원한다고 알리지 마세요.
IGracefulStopTestExecutionCapability
사용자 지정 테스트 프레임워크에서 Microsoft.Testing.Platform.Capabilities.TestFramework.IGracefulStopTestExecutionCapability을(를) 지원하려면 --maximum-failed-tests을(를) 구현하세요. 이 기능은 Microsoft.Testing.Platform 패키지의 일부이며 MTP 1.5부터 사용할 수 있습니다. 이미 이 옵션을 지원하는 프레임워크를 사용하는 테스트 작성자는 기능을 구현할 필요가 없습니다.
인터페이스는 Task StopTestExecutionAsync(CancellationToken cancellationToken)를 정의합니다. 오류 수가 요청된 최대값에 도달하면 MTP는 이 메서드를 호출합니다. 구현은 이미 시작된 테스트가 완료되고 정리를 실행하고 결과를 게시할 수 있도록 하는 동안 프레임워크에 새 테스트 예약을 중지하도록 지시해야 합니다.
Important
기능 및 AddMaximumFailedTestsService 도우미는 컴파일러 진단 TPEXP을 생성하는 실험적 API입니다. 해당 계약은 변경되거나 제거될 수 있습니다. 예제 프로젝트는 TPEXP를 명시적으로 억제합니다.
기능을 구현할 때 다음 요구 사항을 따릅니다.
- 기능과 프레임워크의 테스트 스케줄러 간에 중지 상태를 공유합니다. 완료된 작업을 반환하기만 해도 테스트가 중지되지는 않습니다.
- 중지 요청을 스레드 안전하고 멱등하게 만듭니다. 둘 이상의 플랫폼 구성 요소가 중지를 요청할 수 있습니다.
- 중지 신호를 보낸 후 돌아오세요. 전체 실행 또는 메시지 버스가 완료될 때까지 기다리지 마세요. MTP는 테스트 결과를 처리하는 동안 메서드를 호출할 수 있으므로, 그 대기는 교착 상태를 일으킬 수 있습니다.
- graceful-stop 상태를 요청 취소와 별도로 유지합니다. 정상 중지를 위해 프로세스를 종료하거나 결과 게시를 취소하지 마세요. 중지 작업에 비동기 작업이 필요한 경우 메서드의 취소 토큰을 준수하세요.
- 활성 테스트가 완료되면 결과 게시, 정리 및
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
capability 팩터리는 새 중지 상태를 만들고 프레임워크 팩터리는 동일한 인스턴스를 가져옵니다. 프레임워크에서 분리된 두 번째 기능을 만들지 마세요. 여러 실행 요청을 지원하는 프레임워크의 경우 중지 상태를 해당 실행에 한정되도록 유지합니다. 실행이 시작될 때 수락된 중지 요청을 지우지 마세요.
옵션 공급자가 등록되어 있지만 프레임워크가 이 기능을 노출하지 않는 경우, MTP는 명령줄 유효성 검사 중에 --maximum-failed-tests를 거부합니다. 실패 임계값이 중지를 트리거하면 MTP는 종료 코드를 13반환합니다. 결과 처리가 비동기적이며 테스트가 이미 진행 중일 수 있으므로 최종 오류 수가 임계값을 초과할 수 있습니다.
인터페이스 계약의 경우 IGracefulStopTestExecutionCapability 소스를 참조하세요.
.NET