Kemampuan Microsoft.Testing.Platform (MTP)

Dalam konteks MTP, kemampuan mengacu pada potensi untuk melakukan tindakan tertentu atau memberikan informasi tertentu. Ini adalah sarana bagi kerangka kerja pengujian dan ekstensi untuk menyatakan kemampuan mereka untuk beroperasi dengan cara tertentu atau memberikan informasi khusus kepada pemohon .

Pemohon dapat menjadi komponen apa pun yang terlibat dalam sesi pengujian, seperti platform, ekstensi, atau kerangka kerja pengujian itu sendiri.

Tujuan utama sistem kemampuan adalah untuk memfasilitasi komunikasi yang efektif di antara komponen yang terlibat dalam sesi pengujian, memungkinkan mereka untuk exchange informasi dan memenuhi kebutuhan masing-masing secara akurat.

Contoh terpandu

Mari kita pertimbangkan contoh hipotetis untuk menunjukkan kebutuhan sistem kemampuan.

Nota

Contoh ini murni untuk tujuan ilustrasi dan saat ini tidak diimplementasikan dalam MTP atau kerangka kerja pengujian apa pun.

Bayangkan situasi di mana Anda memiliki ekstensi yang memerlukan kerangka kerja pengujian untuk menjalankan tidak lebih dari satu pengujian pada satu waktu. Selain itu, setelah setiap pengujian, ekstensi perlu mengetahui penggunaan CPU untuk pengujian tertentu tersebut.

Untuk mengakomodasi skenario sebelumnya, Anda perlu menanyakan dari kerangka kerja pengujian jika:

  1. Ini memiliki kemampuan untuk menjalankan hanya satu pengujian pada satu waktu.
  2. Ini dapat memberikan informasi mengenai jumlah CPU yang dikonsumsi oleh setiap pengujian.

Bagaimana ekstensi dapat menentukan apakah kerangka kerja pengujian memiliki kemampuan untuk beroperasi dalam mode ini dan memberikan informasi penggunaan CPU untuk sesi pengujian? Dalam MTP, kemampuan ini diwakili oleh implementasi antarmuka 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
{
}

Seperti yang Anda lihat, antarmuka ICapability adalah penanda antarmuka karena dapat mewakili kemampuan apa pun, dan implementasi aktual akan bergantung pada konteks. Anda juga akan mengamati ITestFrameworkCapability, yang mewarisi dari ICapability untuk mengklasifikasikan kemampuan. Sifat generik sistem kemampuan memungkinkan pengelompokan yang nyaman berdasarkan konteks. ITestFrameworkCapability mengelompokkan semua kemampuan yang diterapkan oleh kerangka kerja pengujian . Antarmuka ICapabilities<TCapability> memperlihatkan set dari semua kemampuan yang diterapkan oleh ekstensi. Demikian pula, untuk yang dasarnya, ada kerangka kerja pengujian khusus konteks yang disebut ITestFrameworkCapabilities. ITestFrameworkCapabilities disediakan untuk platform selama proses pendaftaran kerangka kerja pengujian.

Untuk membuat kemampuan yang membahas skenario yang disebutkan di atas, Anda mendefinisikannya sebagai berikut:

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

Jika kerangka kerja pengujian mengimplementasikan antarmuka ini, pada saat runtime, hal berikut ini dapat dikueri:

  • Verifikasi apakah kerangka kerja pengujian memiliki kemampuan untuk menonaktifkan paralelisme CanDisableParallelism = true.
  • Tentukan apakah kerangka kerja pengujian dapat menyediakan data penggunaan CPU CanProvidePerTestCPUConsumption = true.
  • Minta adaptor pengujian untuk mengaktifkan mode ini dengan memanggil metode Enable() sebelum sesi pengujian dimulai.

Fragmen kode hipotetis di dalam ekstensi bisa menjadi sesuatu seperti:

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

Contoh sebelumnya menggambarkan bagaimana infrastruktur kemampuan memungkinkan mekanisme yang kuat untuk mengkomunikasikan kemampuan antara komponen yang terlibat dalam sesi pengujian. Meskipun sampel menunjukkan kemampuan yang dirancang khusus untuk kerangka kerja pengujian, komponen apa pun dapat mengekspos dan menerapkan ekstensi yang mewarisi dari ICapability.

Terbukti bahwa tidak semua detail dapat dikomunikasikan melalui antarmuka. Mempertimbangkan contoh sebelumnya, apa yang harus diharapkan ekstensi jika CanProvidePerTestCpuConsumption didukung? Jenis informasi kustom apa yang diharapkan untuk ditransmisikan melalui IMessageBus oleh kerangka kerja pengujian? Solusinya adalah dokumentasi kemampuan. Ini adalah tanggung jawab pemilik kemampuan untuk merancang, meluncurkan, dan mendokumentasikannya dengan sangat jelas guna membantu pelaksana yang ingin secara efektif berkolaborasi dengan ekstensi perangkat lunak yang membutuhkan kemampuan khusus tersebut.

Misalnya, ekstensi laporan TRX memungkinkan kerangka kerja pengujian untuk mengimplementasikan kemampuan yang diperlukan untuk menghasilkan laporan TRX secara akurat. Ekstensi untuk mendaftar disertakan dalam https://www.nuget.org/packages/Microsoft.Testing.Extensions.TrxReport paket NuGet, tetapi kemampuan untuk menerapkan ditemukan dalam paket khusus kontrak.

Sebagai kesimpulan, mari kita ringkas aspek utama sistem kemampuan:

  • Sangat penting untuk memfasilitasi komunikasi yang jelas dan stabil antar komponen.
  • Semua kemampuan harus mewarisi dari ICapability atau antarmuka yang mewarisinya, dan diekspos melalui koleksi dengan antarmuka ICapabilities.
  • Ini membantu dalam evolusi fitur tanpa menyebabkan perubahan yang merusak. Jika kemampuan tertentu tidak didukung, tindakan yang sesuai dapat diambil.
  • Tanggung jawab merancang, mengirim, dan mendokumentasikan penggunaan kemampuan terletak pada pemilik kemampuan . MTP juga dapat memiliki kemampuan dengan cara yang sama seperti ekstensi lainnya.

Kemampuan kerangka kerja

Platform ini mengekspos antarmuka khusus bernama ITestFrameworkCapability yang merupakan dasar dari semua kemampuan yang diekspos untuk kerangka kerja pengujian. Kemampuan ini disediakan ketika mendaftarkan kerangka kerja pengujian ke platform.

IBannerMessageOwnerCapability

Kemampuan kerangka kerja pengujian opsional memungkinkan kerangka kerja pengujian untuk memberikan pesan banner ke platform. Jika pesannya adalah null atau kapabilitasnya tidak tersedia, platform menggunakan pesan banner default.

Implementasi kemampuan ini memungkinkan Anda untuk mengabstraksi berbagai kondisi yang mungkin perlu dipertimbangkan kerangka kerja pengujian saat memutuskan apakah pesan banner harus ditampilkan atau tidak.

Platform ini mengekspos layanan IPlatformInformation untuk memberikan beberapa informasi tentang platform yang dapat berguna saat membangun pesan banner kustom Anda.

ITrxReportCapability

Untuk menyediakan metadata khusus kerangka kerja ke ekstensi laporan TRX, terapkan Microsoft.Testing.Extensions.TrxReport.Abstractions.ITrxReportCapability. Referensikan Microsoft.Testing.Extensions.TrxReport.Abstractions dari kerangka kerja Anda. Aplikasi pengujian juga membutuhkan paket Microsoft.Testing.Extensions.TrxReport untuk membuat laporan.

Kemampuan ini membedakan dukungan dari aktivasi:

  • Kembalikan true dari IsSupported saat kerangka kerja Anda dapat menyediakan metadata TRX.
  • Dalam Enable(), catat bahwa pelapor TRX meminta metadata. Pelapor memanggil metode ini pada awal sesi pengujian ketika laporan TRX diaktifkan.
  • Setelah aktivasi, tambahkan properti TRX ke simpul pengujian yang diterbitkan kerangka kerja Anda.

Kemampuan berikut menyimpan status aktivasi. Contoh proyek menargetkan .NET 10 dan referensi 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

Kembalikan kapabilitas dari capabilitiesFactory yang Anda teruskan ke RegisterTestFramework. Berikan kerangka kerja instance capability yang sama sehingga dapat mengamati Enable(). Untuk aplikasi pengujian yang disusun secara manual, daftarkan penyedia TRX setelah kerangka kerja Anda dan ekstensi lainnya:

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

Paket abstraksi menyediakan properti yang diketik untuk TestNode.Properties:

Property Purpose
TrxFullyQualifiedTypeNameProperty Menyediakan nama kelas pengujian yang berkualifikasi lengkap.
TrxCategoriesProperty Menyediakan kategori tes.
TrxExceptionProperty Menyediakan pesan kegagalan dan jejak tumpukan.
TrxMessagesProperty Berisi entri StandardOutputTrxMessage, StandardErrorTrxMessage, dan DebugOrTraceTrxMessage.
TrxTestDefinitionName Mengganti nama definisi pengujian di laporan.
TrxWorkItemsProperty Menyediakan pengidentifikasi item kerja.

Misalnya, perkaya hasil setelah kerangka kerja Anda menentukan hasil pengujian:

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

Properti ini melengkapi status test-node yang diperlukan; mereka tidak menggantinya. Pesan khusus TRX juga tidak menggantikan placeholder milik platform StandardOutputProperty dan StandardErrorProperty.

Sampel lengkap berisi satu pengujian lulus dan satu pengujian yang sengaja gagal. Dengan --report-trx, ia menulis hasil dan metadata yang diperkaya ke file TRX, lalu mengembalikan kode keluar 2. Untuk menjalankan hanya pengujian yang lolos, tambahkan --filter-uid trx.pass.

Jika kemampuan tidak ada atau IsSupported adalah false, pelapor TRX memperingatkan bahwa kerangka kerja tidak mendukung pengayaan TRX. Pelapor masih dapat membuat laporan dari data yang tersedia, tetapi detail khusus kerangka kerja mungkin hilang. Jangan mengiklankan dukungan kecuali kerangka kerja Anda menyediakan metadata yang sesuai.

IGracefulStopTestExecutionCapability

Untuk mendukung --maximum-failed-tests dalam kerangka kerja pengujian kustom, terapkan Microsoft.Testing.Platform.Capabilities.TestFramework.IGracefulStopTestExecutionCapability. Fitur ini adalah bagian dari paket Microsoft.Testing.Platform dan tersedia mulai MTP 1.5. Penulis pengujian yang menggunakan kerangka kerja yang sudah mendukung opsi tersebut tidak perlu menerapkan kapabilitas.

Antarmuka mendefinisikan Task StopTestExecutionAsync(CancellationToken cancellationToken). Ketika jumlah kegagalan mencapai maksimum yang diminta, MTP memanggil metode ini. Implementasi Anda harus memberi tahu kerangka kerja untuk berhenti menjadwalkan pengujian baru sambil mengizinkan pengujian yang sudah dimulai untuk selesai, menjalankan pembersihan, dan menerbitkan hasilnya.

Important

Kemampuan dan helper AddMaximumFailedTestsService adalah API eksperimental yang menghasilkan diagnostik kompilator TPEXP. Kontrak mereka dapat berubah atau dihapus. Contoh proyek ditangguhkan TPEXP secara eksplisit.

Ikuti persyaratan ini saat Anda menerapkan kapabilitas:

  • Gunakan status stop yang sama antara kemampuan dan penjadwal pengujian kerangka kerja. Hanya mengembalikan nilai dari tugas yang selesai tidak menghentikan pengujian.
  • Buat permintaan penghentian menjadi thread-safe dan idempoten. Lebih dari satu komponen platform dapat meminta penghentian.
  • Lanjutkan setelah Anda memberi tanda untuk berhenti. Jangan menunggu seluruh eksekusi atau bus pesan selesai: MTP dapat memanggil metode saat memproses hasil pengujian, sehingga penantian itu dapat menyebabkan deadlock.
  • Jaga agar status graceful stop terpisah dari pembatalan permintaan. Jangan akhiri proses atau batalkan publikasi hasil untuk menerapkan penghentian aman. Patuhi token pembatalan metode jika operasi penghentian Anda memerlukan pemrosesan asinkron.
  • Setelah pengujian aktif selesai, selesaikan siklus hidup permintaan normal, termasuk publikasi hasil, pembersihan, dan panggilan ke ExecuteRequestContext.Complete().

Implementasi berikut menggunakan flag yang aman untuk thread. Dalam framework Anda, periksa IsStopRequested sebelum Anda menjadwalkan setiap pengujian dan berhenti mengambil pekerjaan baru saat bendera adalah 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

Mengekspos kemampuan melalui ITestFrameworkCapabilities.Capabilities. Contoh pendaftaran menggunakan koleksi TestFrameworkCapabilities milik MTP.

Selama pendaftaran kerangka kerja pengujian, berikan instans kemampuan terdaftar ke kerangka kerja Anda. Fungsi pembantu berikut menerima pabrik kerangka kerja Anda dan IExtension yang memiliki opsi baris perintah. Ini juga memanggil AddMaximumFailedTestsService dari namespace Microsoft.Testing.Platform.Helpers untuk mendaftarkan penyedia opsi --maximum-failed-tests. Tanpa penyedia itu, MTP tidak mengenali opsi .

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

Factory kapabilitas menciptakan status stop baru, dan factory framework mengambil instans yang sama. Jangan membuat kapabilitas kedua yang terputus dalam kerangka kerja Anda. Untuk kerangka kerja yang mendukung beberapa permintaan eksekusi, pertahankan cakupan status stop pada eksekusi yang sesuai. Jangan batalkan permintaan berhenti yang diterima saat eksekusi dimulai.

MTP menolak --maximum-failed-tests selama validasi baris perintah jika penyedia opsi terdaftar tetapi kerangka kerja tidak mengekspos kemampuan ini. Saat ambang kegagalan memicu pemberhentian, MTP mengembalikan kode 13keluar . Jumlah kegagalan akhir dapat melebihi ambang batas karena pemrosesan hasil bersifat asinkron dan pengujian mungkin sudah berlangsung.

Untuk kontrak antarmuka, lihat IGracefulStopTestExecutionCapability sumbernya.

  • Terakhir diperbarui pada