Microsoft. Testing.Platform (MTP) özellikleri

MTP bağlamında, bir özellikbelirli bir eylemi gerçekleştirme veya belirli bilgiler sağlama olasılığını ifade eder. Test çerçevesinin ve uzantıların belirli bir şekilde çalışma veya istekte bulunanlara belirli bilgiler sağlama becerilerinibildirmesi için bir araçtır.

İstekte bulunanlar platform, uzantı veya test çerçevesi gibi bir test oturumunda yer alan herhangi bir bileşen olabilir.

Yetenek sisteminin birincil amacı, bir test oturumunda yer alan bileşenler arasında etkili iletişimi kolaylaştırarak bilgileri exchange ve ilgili ihtiyaçlarını doğru bir şekilde karşılamalarını sağlamaktır.

Kılavuzlu örnek

Yetenek sisteminin gerekliliğini göstermek için varsayımsal bir örneği ele alalım.

Uyarı

Bu örnek yalnızca gösterim amaçlıdır ve şu anda MTP veya herhangi bir test çerçevesi içinde uygulanmaz.

Test çerçevesinin aynı anda birden fazla test yürütmesini gerektiren bir uzantıya sahip olduğunuzu düşünün. Ayrıca, her test sonrasında uzantının belirli bir test için CPU kullanımını bilmesi gerekir.

Önceki senaryoya uyum sağlamak için aşağıdaki durumlarda test çerçevesinden sorgulamanız gerekir:

1. Aynı anda yalnızca bir test yürütme özelliğine sahiptir.
2. Her test tarafından tüketilen CPU miktarıyla ilgili bilgi sağlayabilir.

Uzantı, test çerçevesinin bu modda çalışıp çalışmadığını ve bir test oturumu için CPU kullanım bilgileri sağlayıp sağlamadığını nasıl belirleyebilir? MTP'de bu özellik, Microsoft.Testing.Platform.Capabilities.ICapability arabiriminin bir uygulamasıyla temsil edilir:

// 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
{
}

Gördüğünüz gibi, ICapability arabirim herhangi bir özelliği temsil ettiğinden bir işaretçi arabirimidir ve gerçek uygulama bağlama bağımlı olacaktır. Ayrıca, özelliği sınıflandırmak için ITestFrameworkCapability öğesinden devralan ICapability öğesini de gözlemleyeceksiniz. Yetenek sisteminin genel yapısı, bağlama göre kolay gruplandırma sağlar. , ITestFrameworkCapabilitytest çerçevesi tarafından uygulanan tüm özellikleri gruplandırıyor. Arabirim, ICapabilities<TCapability> bir uzantı tarafından uygulanan tüm özelliklerin kümesini gösterir. Benzer şekilde, temel için bağlama özgü bir test çerçevesi olan ITestFrameworkCapabilities vardır. , ITestFrameworkCapabilitiestest çerçevesi kayıt işlemi sırasında platforma sağlanır.

Yukarıda belirtilen senaryoyu ele alan bir özellik oluşturmak için bunu aşağıdaki gibi tanımlarsınız:

public interface IDisableParallelismCapability : ITestFrameworkCapability
{
    bool CanDisableParallelism { get; }
    bool CanProvidePerTestCpuConsumption { get; }
    void Enable();
}

Test çerçevesi bu arabirimi uygularsa çalışma zamanında aşağıdakiler sorgulanabilir:

• Test çerçevesinin paralelliği CanDisableParallelism = truekapatma özelliğine sahip olup olmadığını doğrulayın.
• Test çerçevesinin CPU kullanım verilerini CanProvidePerTestCPUConsumption = truesağlayabildiğini belirleyin.
• Test oturumu başlamadan önce Enable() yöntemini çağırarak test bağdaştırıcısından bu modu etkinleştirmesini talep edin.

Uzantının içindeki varsayımsal kod parçası şöyle olabilir:

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...
    }
}

Yukarıdaki örnekte yetenek altyapısının, bir test oturumunda yer alan bileşenler arasında yetenekleri iletmek için güçlü bir mekanizmaya nasıl olanak sağladığı gösterilmektedir. Örnek, test çerçevesi için özel olarak tasarlanmış bir özelliği gösterse de, herhangi bir bileşen öğesinden ICapabilitydevralan uzantıları kullanıma açabilir ve uygulayabilir.

Tüm ayrıntıların bir arabirim üzerinden iletilmediği açıktır. Önceki örneği göz önünde bulundurarak, CanProvidePerTestCpuConsumption etiketi desteklenirse uzantının ne beklemesi gerekir? Test çerçevesi tarafından IMessageBus aracılığıyla hangi tür özel bilgilerin iletilmesi beklenir? Çözüm, kabiliyetin belgelenmesidir. Belirli bir özelliği gerektiren uzantıyla etkili bir şekilde işbirliği yapmak isteyen uygulayıcılara yardımcı olmak, mümkün olduğunca net bir şekilde tasarlamak, göndermek ve belgelendirmek yetenek sahibinin sorumluluğundadır.

Örneğin TRX rapor uzantısı, test çerçevesinin bir TRX raporunu doğru bir şekilde oluşturmak için gerekli özelliği uygulamasına olanak tanır. Kaydetme uzantısı NuGet paketine https://www.nuget.org/packages/Microsoft.Testing.Extensions.TrxReport dahil edilir, ancak uygulama özelliği yalnızca sözleşme paketinde bulunur.

Sonuç olarak, yetenek sisteminin birincil yönlerini özetleyelim:

• Bileşenler arasındaki net ve kararlı iletişimi kolaylaştırmak için gereklidir.
• Tüm yetenekler, ICapability'den veya ondan devralan bir arabirimden devralmalıdır ve ICapabilities arabirimine sahip bir koleksiyon aracılığıyla kullanıma sunulmalıdır.
• Özelliklerin, büyük değişikliklere yol açmadan evrimleşmesine yardımcı olur. Belirli bir özellik desteklenmiyorsa uygun işlem yapılabilir.
• Bir özelliğin tasarlanması, teslimi ve kullanımını belgeleme sorumluluğu, yetenek sahibine aittir. MTP, diğer uzantılarda olduğu gibi bir özelliğe de sahip olabilir.

Çerçeve özellikleri

Platform, test çerçeveleri için kullanıma sunulan tüm özelliklerin temeli olan adlı ITestFrameworkCapability özel bir arabirim sunar. Bu özellikler , test çerçevesi platforma kaydedilirken sağlanır.

IBannerMessageOwnerCapability

İsteğe bağlı bir test çerçevesi özelliği, test çerçevesinin platforma başlık iletisi sağlamasına olanak tanır. İleti null ise veya özellik mevcut değilse, platform varsayılan banner iletisini kullanır.

Bu özellik uygulaması, başlık iletisinin görüntülenip görüntülenmeyeceğine karar verirken test çerçevesinin dikkate alması gerekebilecek çeşitli koşulları soyutlamanızı sağlar.

Platform, özel başlık iletinizi oluştururken yararlı olabilecek platform hakkında bazı bilgiler sağlamak için hizmeti kullanıma sunarIPlatformInformation.

ITrxReportCapability

TRX rapor uzantısına çerçeveye özgü meta veriler sağlamak için Microsoft.Testing.Extensions.TrxReport.Abstractions.ITrxReportCapability öğesini uygulayın. Çerçevenizden Microsoft.Testing.Extensions.TrxReport.Abstractions paketine başvurun. Test uygulamasının rapor oluşturmak için Microsoft.Testing.Extensions.TrxReport paketine de ihtiyacı vardır.

Bu özellik, destek ile etkinleştirmeyi birbirinden ayırır:

• Çerçeveniz TRX meta verilerini sağlayabildiğinde, true içinden IsSupported döndürün.
• Enable() içinde, TRX muhabirinin meta verileri istediğini kaydedin. TRX raporları etkinleştirildiğinde, reporter bir test oturumunun başında bu yöntemi çağırır.
• Etkinleştirmeden sonra, TRX özelliklerini çerçevenizin yayımladığı test düğümlerine ekleyin.

Aşağıdaki özellik etkinleştirme durumunu depolar. Örnek projeler .NET 10'u hedefler ve MTP 2.5.1'i referans alır:

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 öğesine geçirdiğiniz capabilitiesFactory içindeki özelliği döndürebilirsiniz. Çerçeveye aynı yetenek örneğini verin, böylece Enable() öğesini gözlemleyebilir. El ile oluşturulmuş bir test uygulaması için, altyapınızdan ve diğer uzantılardan sonra TRX sağlayıcısını kaydedin:

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()

Soyutlama paketi, TestNode.Properties için tipli özellikler sağlar:

Property	Purpose
TrxFullyQualifiedTypeNameProperty	Tam nitelikli test sınıfı adını sağlar.
TrxCategoriesProperty	Testin kategorilerini sağlar.
TrxExceptionProperty	Hata iletisini ve yığın izlemesini sağlar.
TrxMessagesProperty	StandardOutputTrxMessage, StandardErrorTrxMessageve DebugOrTraceTrxMessage girdilerini taşır.
TrxTestDefinitionName	Raporda test tanımı adının üzerine yazar.
TrxWorkItemsProperty	İş öğesi tanımlayıcılarını sağlar.

Örneğin, çerçeveniz test sonucunu belirledikten sonra bir sonucu zenginleştirin:

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

Bu özellikler gerekli test düğümü durumunu tamamlar; onun yerini almazlar. TRX'e özgü iletiler de platformun StandardErrorProperty ve StandardOutputProperty yerini almaz.

Tam örnek, bir başarılı test ve kasıtlı olarak başarısız olan bir test içerir. --report-trx ile hem sonuçları hem de zenginleştirilmiş meta verileri bir TRX dosyasına yazar, ardından çıkış kodunu 2 döndürür. Yalnızca başarılı testi çalıştırmak için --filter-uid trx.pass ekleyin.

Özellik yoksa veya IsSupportedfalse ise, TRX raporlayıcısı çerçevenin TRX zenginleştirmesini desteklemediği konusunda uyarır. Raporlayıcı kullanılabilir verilerden rapor oluşturmaya devam edebilir, ancak çerçeveye özgü ayrıntılar eksik olabilir. Çerçeveniz ilgili meta verileri sağlamadığı sürece destek sunduğunuzu belirtmeyin.

IGracefulStopTestExecutionCapability

--maximum-failed-tests öğesini özel bir test çerçevesinde desteklemek için Microsoft.Testing.Platform.Capabilities.TestFramework.IGracefulStopTestExecutionCapability uygulayın. Bu özellik, Microsoft.Testing.Platform paketinin bir parçasıdır ve MTP 1.5 ile birlikte kullanılabilir. Seçeneği zaten destekleyen bir çerçeve kullanan test yazarlarının bu özelliği uygulaması gerekmez.

Arabirim Task StopTestExecutionAsync(CancellationToken cancellationToken) tanımlar. Hata sayısı istenen üst sınıra ulaştığında, MTP bu yöntemi çağırır. Uygulamanız, çerçeveye yeni testleri zamanlamayı durdurmasını, ancak zaten başlamış olan testlerin tamamlanmasına, temizliğin çalıştırılmasına ve sonuçlarının yayımlanmasına izin vermesi gerektiğini belirtmelidir.

Important

AddMaximumFailedTestsService yardımcısı ve özellik, derleyici tanılama TPEXP üreten deneysel API'lerdir. Sözleşmeleri değişebilir veya kaldırılabilir. Örnek projeler TPEXP açıkça bastırır.

Özelliği uygularken şu gereksinimleri izleyin:

• Yetenek ve çerçevenin test zamanlayıcısı arasında durdurma durumunu paylaşın. Yalnızca tamamlanmış bir görevin döndürülmesi testleri durdurmaz.
• Durdurma isteklerini iş parçacığı açısından güvenli ve idempotent hale getirin. Birden fazla platform bileşeni durdurma isteğinde bulunabilir.
• Durdurma sinyali verdikten sonra geri gelin. Çalıştırmanın tamamının veya ileti veri yolunun tamamlanmasını beklemeyin: MTP, bir test sonucunu işlerken yöntemi çağırabilir, bu nedenle bu bekleme kilitlenebilir.
• graceful-stop durumunu istek iptalinden ayrı tutun. Düzgün bir durdurma uygulamak için işlemi sonlandırmayın veya sonuç yayınını iptal etmeyin. Durdurma işleminiz zaman uyumsuz çalışma gerektiriyorsa yöntemin iptal simgesini kabul edin.
• Etkin testler tamamlandıktan sonra sonuç yayını, temizleme ve ExecuteRequestContext.Complete() çağrısı dahil olmak üzere normal istek yaşam döngüsünü tamamlayın.

Aşağıdaki uygulama, iş parçacığı açısından güvenli bir bayrak kullanır. Çerçevenizde, her testi zamanlamadan önce IsStopRequested denetleyin ve bayrak true olduğunda yeni iş almayı durdurun.

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

Bu yeteneği ITestFrameworkCapabilities.Capabilities aracılığıyla kullanıma sunun. Kayıt örneği MTP'nin TestFrameworkCapabilities koleksiyonunu kullanır.

Test çerçevesi kaydı sırasında, kayıtlı özellik örneğini çerçevenize geçirin. Aşağıdaki yardımcı, çerçeve fabrikanızı ve komut satırı seçeneğinin sahibi olan bir IExtension kabul eder. AddMaximumFailedTestsService seçenek sağlayıcısını kaydetmek için --maximum-failed-tests ad alanından Microsoft.Testing.Platform.Helpers öğesini de çağırır. O sağlayıcı olmadan MTP seçeneği tanımaz.

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

Yetenek fabrikası yeni durdurulmuş durum oluşturur ve çerçeve fabrikası aynı örneği alır. Çerçevenizde ikinci ve bağlantısı kesilmiş bir yetenek oluşturmayın. Birden çok çalıştırma isteğini destekleyen çerçeveler için durdurma durumunu ilgili yürütmeyle sınırlı tutun. Yürütme başladığında kabul edilen durdurma isteğini temizlemeyin.

Seçenek sağlayıcısı kayıtlıysa ancak çerçeve bu özelliği kullanıma sunmazsa MTP, komut satırı doğrulaması sırasında --maximum-failed-tests öğesini reddeder. Hata eşiği bir durdurmayı tetiklediğinde, MTP bir çıkış kodu 13döndürür. Sonuç işleme eşzamansız olduğundan ve testler devam ediyor olabileceğinden son hata sayısı eşiği aşabilir.

Arabirim sözleşmesi için IGracefulStopTestExecutionCapabilitykaynağa bakın.