Bagikan melalui

Microsoft.Testing.Platform Services

Platform pengujian menawarkan layanan berharga untuk kerangka kerja pengujian dan titik ekstensi. Layanan ini memenuhi kebutuhan umum seperti mengakses konfigurasi, mengurai dan mengambil argumen baris perintah, mendapatkan fasilitas pencatatan, dan mengakses sistem logging, antara lain. IServiceProvider menerapkan pola pencari layanan untuk platform pengujian.

IServiceProvider berasal langsung dari pustaka kelas dasar.

namespace System
{
    public interface IServiceProvider
    {
        object? GetService(Type serviceType);
    }
}

Platform pengujian menawarkan metode ekstensi yang berguna untuk mengakses objek layanan yang terkenal. Semua metode ini ditempatkan dalam kelas statis dalam namespace Microsoft.Testing.Platform.Services.

public static class ServiceProviderExtensions
{
    public static TService GetRequiredService<TService>(
        this IServiceProvider provider)

    public static TService? GetService<TService>(
        this IServiceProvider provider)

    public static IMessageBus GetMessageBus(
        this IServiceProvider serviceProvider)

    public static IConfiguration GetConfiguration(
        this IServiceProvider serviceProvider)

    public static ICommandLineOptions GetCommandLineOptions(
        this IServiceProvider serviceProvider)

    public static ILoggerFactory GetLoggerFactory(
        this IServiceProvider serviceProvider)

    public static IOutputDevice GetOutputDevice(
        this IServiceProvider serviceProvider)

    // ... and more
}

Sebagian besar pabrik pendaftaran yang diekspos oleh titik ekstensi memberikan akses ke IServiceProvider: Misalnya, ketika mendaftarkan kerangka kerja pengujian, IServiceProvider diteruskan sebagai parameter ke metode pabrik.

ITestApplicationBuilder RegisterTestFramework(
    Func<IServiceProvider, ITestFrameworkCapabilities> capabilitiesFactory,
    Func<ITestFrameworkCapabilities, IServiceProvider, ITestFramework> adapterFactory);

Dalam kode sebelumnya, baik capabilitiesFactory dan adapterFactory menyediakan IServiceProvider sebagai parameter.

Layanan IConfiguration

Antarmuka IConfiguration dapat diambil menggunakan IServiceProvider dan menyediakan akses ke pengaturan konfigurasi untuk kerangka kerja pengujian serta berbagai titik ekstensi. Secara default, konfigurasi ini dimuat dari:

  • Variabel lingkungan
  • File JSON bernama [assemblyName].testingplatformconfig.json terletak di dekat rakitan titik masuk.

Urutan prioritas dipertahankan, yang berarti bahwa jika konfigurasi ditemukan dalam variabel lingkungan, file JSON tidak akan diproses.

Antarmukanya adalah pasangan kunci-nilai string yang sederhana.

public interface IConfiguration
{
    string? this[string key] { get; }
}

File konfigurasi JSON

File JSON mengikuti struktur hierarkis. Untuk mengakses properti anak, Anda perlu menggunakan pemisah :. Misalnya, pertimbangkan konfigurasi untuk kerangka kerja pengujian potensial seperti:

{
  "CustomTestingFramework": {
    "DisableParallelism": true
  }
}

Cuplikan kode akan terlihat seperti ini:

IServiceProvider serviceProvider = null; // Get the service provider...

var configuration = serviceProvider.GetConfiguration();

if (bool.TryParse(configuration["CustomTestingFramework:DisableParallelism"], out var value) && value is true)
{
    // ...
}

Dalam kasus sebuah array, seperti:

{
  "CustomTestingFramework": {
    "Engine": [
      "ThreadPool",
      "CustomThread"
    ]
  }
}

Sintaks untuk mengakses elemen pertama ("ThreadPool") adalah:

IServiceProvider serviceProvider = null; // Get the service provider...

var configuration = serviceProvider.GetConfiguration();

var fistElement = configuration["CustomTestingFramework:Engine:0"];

Variabel lingkungan

Pemisah : tidak berfungsi dengan kunci hierarki variabel lingkungan di semua platform. __, garis bawah ganda, adalah:

  • Didukung oleh semua platform. Misalnya, pemisah : tidak didukung oleh Bash, tetapi __.
  • Digantikan secara otomatis oleh :

Misalnya, variabel lingkungan dapat diatur sebagai berikut (Contoh ini berlaku untuk Windows):

setx CustomTestingFramework__DisableParallelism=True

Anda dapat memilih untuk tidak menggunakan sumber konfigurasi variabel lingkungan saat membuat ITestApplicationBuilder:

var options = new TestApplicationOptions();

options.Configuration.ConfigurationSources.RegisterEnvironmentVariablesConfigurationSource = false;

var builder = await TestApplication.CreateBuilderAsync(args, options);

Layanan ICommandLineOptions

Layanan ICommandLineOptions digunakan untuk mengambil detail mengenai opsi baris perintah yang telah diurai platform. API yang tersedia meliputi:

public interface ICommandLineOptions
{
    bool IsOptionSet(string optionName);

    bool TryGetOptionArgumentList(
        string optionName, 
        out string[]? arguments);
}

ICommandLineOptions dapat diperoleh melalui API tertentu, contoh ICommandLineOptionsProvider, atau Anda dapat mengambil instans tersebut dari IServiceProvider dengan menggunakan metode ekstensi serviceProvider.GetCommandLineOptions().

ICommandLineOptions.IsOptionSet(string optionName): Metode ini memungkinkan Anda memverifikasi apakah opsi tertentu telah ditentukan. Saat menentukan optionName, hilangkan awalan --. Misalnya, jika pengguna memasukkan --myOption, Anda cukup meneruskan myOption.

ICommandLineOptions.TryGetOptionArgumentList(string optionName, out string[]? arguments): Metode ini memungkinkan Anda untuk memeriksa apakah opsi tertentu telah diatur dan, jika demikian, ambil nilai atau nilai yang sesuai (jika aritasnya lebih dari satu). Mirip dengan kasus sebelumnya, optionName harus disediakan tanpa awalan --.

Layanan ILoggerFactory

Platform pengujian dilengkapi dengan sistem pengelogan terintegrasi yang menghasilkan file log. Anda dapat melihat opsi pengelogan dengan menjalankan perintah --help. Opsi yang dapat Anda pilih meliputi:

--diagnostic                             Enable the diagnostic logging. The default log level is 'Trace'. The file will be written in the output directory with the name log_[MMddHHssfff].diag
--diagnostic-synchronous-write Force the built-in file logger to write the log synchronously. Useful for scenario where you don't want to lose any log (i.e. in case of crash). Note that this is slowing down the test execution.
--diagnostic-output-directory            Output directory of the diagnostic logging, if not specified the file will be generated inside the default 'TestResults' directory.
--diagnostic-file-prefix           Prefix for the log file name that will replace '[log]_.'
--diagnostic-verbosity                   Define the level of the verbosity for the --diagnostic. The available values are 'Trace', 'Debug', 'Information', 'Warning', 'Error', and 'Critical'

Dari sudut pandang pemrograman, untuk mencatat informasi, Anda perlu mendapatkan ILoggerFactory dari IServiceProvider. API ILoggerFactory adalah sebagai berikut:

public interface ILoggerFactory
{
    ILogger CreateLogger(string categoryName);
}

public static class LoggerFactoryExtensions
{
    public static ILogger<TCategoryName> CreateLogger<TCategoryName>(this ILoggerFactory factory);
}

Pabrik pencatat memungkinkan Anda membuat objek ILogger menggunakan API CreateLogger. Ada juga API nyaman yang menerima argumen generik, yang akan digunakan sebagai nama kategori.

public interface ILogger
{
    Task LogAsync<TState>(
        LogLevel logLevel, 
        TState state, 
        Exception? exception, 
        Func<TState, Exception?, string> formatter);

    void Log<TState>(
        LogLevel logLevel,
        TState state, 
        Exception? exception, 
        Func<TState, Exception?, string> formatter);

    bool IsEnabled(LogLevel logLevel);
}

public interface ILogger<out TCategoryName> : ILogger
{
}

public static class LoggingExtensions
{
    public static Task LogCriticalAsync(this ILogger logger, string message);
    public static Task LogDebugAsync(this ILogger logger, string message);
    public static Task LogErrorAsync(this ILogger logger, Exception ex);
    public static Task LogErrorAsync(this ILogger logger, string message, Exception ex);
    public static Task LogErrorAsync(this ILogger logger, string message);
    public static Task LogInformationAsync(this ILogger logger, string message);
    public static Task LogTraceAsync(this ILogger logger, string message);
    public static Task LogWarningAsync(this ILogger logger, string message);
    public static void LogCritical(this ILogger logger, string message);
    public static void LogDebug(this ILogger logger, string message);
    public static void LogError(this ILogger logger, Exception ex);
    public static void LogError(this ILogger logger, string message, Exception ex);
    public static void LogError(this ILogger logger, string message);
    public static void LogInformation(this ILogger logger, string message);
    public static void LogTrace(this ILogger logger, string message);
    public static void LogWarning(this ILogger logger, string message);
}

Objek ILogger, yang dibuat oleh ILoggerFactory, menawarkan API untuk informasi pengelogan di berbagai tingkatan. Tingkatan pencatatan ini termasuk:

public enum LogLevel
{
    Trace,
    Debug,
    Information,
    Warning,
    Error,
    Critical,
    None,
}

Berikut adalah contoh bagaimana Anda dapat menggunakan API pengelogan:

...
IServiceProvider provider = null; // Get the service provider...

var factory = provider.GetLoggerFactory();

var logger = factory.CreateLogger<TestingFramework>();

// ...

if (logger.IsEnabled(LogLevel.Information))
{
    await logger.LogInformationAsync(
        $"Executing request of type '{context.Request}'");
}

// ...

Perlu diingat bahwa untuk mencegah alokasi yang tidak perlu, Anda harus memeriksa apakah tingkat diaktifkan menggunakan API ILogger.IsEnabled(LogLevel).

Layanan IMessageBus

Layanan bus pesan adalah mekanisme pusat yang memfasilitasi pertukaran informasi antara kerangka kerja pengujian dan ekstensinya.

Bus pesan platform pengujian menggunakan pola publish-subscribe .

Struktur menyeluruh bus bersama adalah sebagai berikut:

Gambar yang mewakili interaksi berbagai ekstensi dengan bus pesan.

Sebagai ilustrasi dalam diagram, yang mencakup kerangka kerja pengujian dan ekstensi, ada dua aksi potensial: mengirim informasi ke bus atau mengambil informasi dari bus.

IMessageBus memastikan tindakan pendorongan ke bus dan API-nya adalah:

public interface IMessageBus
{
    Task PublishAsync(
        IDataProducer dataProducer, 
        IData data);
}

public interface IDataProducer : IExtension
{
    Type[] DataTypesProduced { get; }
}

public interface IData
{
    string DisplayName { get; }
    string? Description { get; }
}

Pertimbangkan detail berikut tentang parameter:

  • IDataProducer: IDataProducer berkomunikasi dengan bus pesan mengenai Type informasi yang dapat disediakan dan menetapkan kepemilikan melalui pewarisan dari antarmuka dasar IExtension. Ini menyiratkan bahwa Anda tidak dapat secara sembarangan mendorong data ke bus pesan; Anda harus mendeklarasikan jenis data yang dihasilkan terlebih dahulu. Jika Anda memasukkan data yang tidak terduga, pengecualian akan dipicu.

  • IData: Antarmuka ini berfungsi sebagai tempat penampung di mana Anda hanya perlu memberikan detail deskriptif seperti nama dan deskripsi. Antarmuka tidak mengungkapkan banyak tentang sifat data, yang disengaja. Ini menyiratkan bahwa kerangka kerja dan ekstensi pengujian dapat mengirim semua jenis data ke bus, dan data ini dapat digunakan oleh ekstensi yang terdaftar atau oleh kerangka kerja pengujian itu sendiri.

Pendekatan ini memfasilitasi evolusi proses pertukaran informasi, mencegah perubahan yang merusak bila ekstensi tidak mengenali data baru. Ini memungkinkan berbagai versi ekstensi dan kerangka kerja pengujian beroperasi secara harmonis, berdasarkan pemahaman bersama mereka.

Ujung bus yang berlawanan disebut sebagai consumer, yang berlangganan jenis data tertentu dan dengan demikian dapat mengonsumsinya.

Penting

Selalu gunakan menunggu panggilan ke PublishAsync. Jika tidak, IData mungkin tidak akan diproses dengan benar oleh platform pengujian dan ekstensi, yang dapat menyebabkan bug yang sulit dideteksi. Hanya setelah Anda kembali dari menunggu di, Anda dapat yakin bahwa IData telah diantrekan untuk diproses di message bus. Terlepas dari titik ekstensi yang sedang Anda kerjakan, pastikan Anda telah menunggu semua panggilan PublishAsync sebelum keluar dari titik ekstensi. Misalnya, jika Anda menerapkan testing framework, Anda tidak boleh memanggil Complete pada permintaan hingga Anda menunggu semua panggilan PublishAsync untuk permintaan tertentu tersebut.

Layanan IOutputDevice

Platform pengujian merangkum gagasan perangkat output , memungkinkan kerangka kerja pengujian dan ekstensi untuk menyajikan informasi dengan mengirimkan segala jenis data ke sistem tampilan yang saat ini digunakan.

Contoh paling tradisional dari perangkat output adalah output konsol.

Nota

Meskipun platform pengujian direkayasa untuk mendukung perangkat output kustom, saat ini, titik ekstensi ini tidak tersedia.

Untuk mengirimkan data ke perangkat output , Anda harus mendapatkan IOutputDevice dari IServiceProvider.

API terdiri dari:

public interface IOutputDevice
{
    Task DisplayAsync(
        IOutputDeviceDataProducer producer, 
        IOutputDeviceData data);
}

public interface IOutputDeviceDataProducer : IExtension
{
}

public interface IOutputDeviceData
{
}

IOutputDeviceDataProducer memperluas IExtension dan memberikan informasi tentang pengirim ke perangkat output .

IOutputDeviceData berfungsi sebagai antarmuka tempat penampung. Konsep di balik IOutputDevice adalah mengakomodasi informasi yang lebih rumit daripada hanya teks berwarna. Misalnya, itu bisa menjadi objek kompleks yang dapat diwakili secara grafis.

Platform pengujian, secara default, menawarkan model teks berwarna tradisional untuk objek IOutputDeviceData:

public class TextOutputDeviceData : IOutputDeviceData
{
    public TextOutputDeviceData(string text)
    public string Text { get; }
}

public sealed class FormattedTextOutputDeviceData : TextOutputDeviceData
{
    public FormattedTextOutputDeviceData(string text)
    public IColor? ForegroundColor { get; init; }
    public IColor? BackgroundColor { get; init; }
}

public sealed class SystemConsoleColor : IColor
{
    public ConsoleColor ConsoleColor { get; init; }
}

Berikut adalah contoh bagaimana Anda dapat menggunakan teks berwarna dengan perangkat aktif output:

IServiceProvider provider = null; // Get the service provider...

var outputDevice = provider.GetOutputDevice();

await outputDevice.DisplayAsync(
    this, 
    new FormattedTextOutputDeviceData($"TestingFramework version '{Version}' running tests with parallelism of {_dopValue}")
    {
        ForegroundColor = new SystemConsoleColor
        {
            ConsoleColor = ConsoleColor.Green
        }
    });

Di luar penggunaan standar teks berwarna, keuntungan utama IOutputDevice dan IOutputDeviceData adalah bahwa perangkat output sepenuhnya independen dan tidak diketahui oleh pengguna. Ini memungkinkan pengembangan antarmuka pengguna yang kompleks. Misalnya, sepenuhnya layak untuk mengimplementasikan aplikasi web real-time yang menampilkan kemajuan pengujian.

Layanan IPlatformInformation

Menyediakan informasi tentang platform seperti: nama, versi, commit hash, dan tanggal pembuatan.

  • Last updated on