Microsoft.Testing.Platform Services

Test platformu hem test çerçevesine hem de uzantı noktalarına değerli hizmetler sunar. Bu hizmetler yapılandırmaya erişme, komut satırı bağımsız değişkenlerini ayrıştırma ve alma, günlüğe kaydetme fabrikasını edinme ve günlüğe kaydetme sistemine erişme gibi yaygın gereksinimleri karşılar. IServiceProvider, test platformu için hizmet bulucu düzeni uygular.

IServiceProvider doğrudan temel sınıf kitaplığından türetilir.

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

Test platformu, iyi bilinen servis nesnelerine erişim sağlamak için kullanışlı uzantı yöntemleri sunar. Tüm bu yöntemler Microsoft.Testing.Platform.Services ad alanı içindeki statik bir sınıfta barındırılır.

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
}

Uzantı noktaları tarafından kullanıma sunulan kayıt fabrikalarının çoğu IServiceProvider için erişim sağlar: Örneğin, test çerçevesini kaydettiğinizde, IServiceProvider fabrika yöntemine parametre olarak geçirilir.

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

Önceki kodda, hem capabilitiesFactory hem de adapterFactoryIServiceProvider'yi bir parametre olarak sağlar.

IConfiguration hizmeti

IConfiguration arabirimi IServiceProvider kullanılarak alınabilir ve test çerçevesi ve tüm uzantı noktaları için yapılandırma ayarlarına access sağlar. Varsayılan olarak, bu yapılandırmalar şunlardan yüklenir:

• Ortam değişkenleri
• Giriş noktası derlemesinin yakınında bulunan [assemblyName].testingplatformconfig.json adlı bir JSON dosyası.

Öncelik sırası korunur, yani ortam değişkenlerinde bir yapılandırma bulunursa JSON dosyası işlenmez.

Arabirim, dizelerin basit bir anahtar-değer çiftidir:

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

JSON yapılandırma dosyası

JSON dosyası hiyerarşik bir yapıyı izler. Alt özelliklere erişmek için : ayırıcısını kullanmanız gerekir. Örneğin, aşağıdaki gibi olası bir test çerçevesi için yapılandırmayı göz önünde bulundurun:

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

Kod parçacığı şuna benzer olacaktır:

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

var configuration = serviceProvider.GetConfiguration();

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

Dizi söz konusu olduğunda, örneğin:

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

İlk öğeye ("ThreadPool") erişmek için kullanılacak söz dizimi şöyledir:

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

var configuration = serviceProvider.GetConfiguration();

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

Ortam değişkenleri

: ayırıcısı tüm platformlarda ortam değişkeni hiyerarşik anahtarlarla çalışmaz. __, çift alt çizgi, şudur:

• Tüm platformlar tarafından desteklenir. Örneğin, : ayırıcısı Bashtarafından desteklenmez, ancak __ desteklenir.
• Otomatik olarak bir : ile değiştirilir

Örneğin, ortam değişkeni aşağıdaki gibi ayarlanabilir (Bu örnek Windows için geçerlidir):

setx CustomTestingFramework__DisableParallelism=True

ITestApplicationBuilderoluştururken ortam değişkeni yapılandırma kaynağını kullanmamayı seçebilirsiniz:

var options = new TestApplicationOptions();

options.Configuration.ConfigurationSources.RegisterEnvironmentVariablesConfigurationSource = false;

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

ICommandLineOptions hizmeti

ICommandLineOptions hizmeti, platformun ayrıştırdığı komut satırı seçenekleriyle ilgili ayrıntıları getirmek için kullanılır. Kullanılabilir API'ler şunlardır:

public interface ICommandLineOptions
{
    bool IsOptionSet(string optionName);

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

ICommandLineOptions, ICommandLineOptionsProvidergibi belirli API'ler aracılığıyla elde edilebilir veya IServiceProvider üzerinden serviceProvider.GetCommandLineOptions()uzantı yöntemi ile onun bir örneğini alabilirsiniz.

ICommandLineOptions.IsOptionSet(string optionName): Bu yöntem belirli bir seçeneğin belirtilip belirtilmediğinden emin olmanıza olanak tanır. optionName'yı belirtirken -- önekini atlayın. Örneğin, kullanıcı --myOptiongirdiyse myOptiongeçirmeniz yeterlidir.

ICommandLineOptions.TryGetOptionArgumentList(string optionName, out string[]? arguments): Bu yöntem, belirli bir seçeneğin ayarlanıp ayarlanmadığını denetlemenizi ve ayarlıysa karşılık gelen değeri veya değerleri (arity birden fazlaysa) almanızı sağlar. Önceki duruma benzer şekilde, optionName-- ön eki olmadan sağlanmalıdır.

ILoggerFactory hizmeti

Test platformu, log dosyası oluşturan entegre bir kayıt sistemiyle birlikte gelir. --help komutunu çalıştırarak günlük seçeneklerini görüntüleyebilirsiniz. Aralarından seçim yapabileceğiniz seçenekler şunlardır:

--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'

Kodlama açısından bilgileri günlüğe kaydetmek için ILoggerFactory'ı, IServiceProvider'den almanız gerekir. ILoggerFactory API aşağıdaki gibidir:

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

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

Günlükleyici fabrikası, ILogger API'sini kullanarak bir CreateLogger nesnesi oluşturmanıza olanak tanır. Ayrıca, kategori adı olarak kullanılacak genel bir bağımsız değişkeni kabul eden kullanışlı bir API de vardır.

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);
}

ILoggertarafından oluşturulan ILoggerFactory nesnesi, çeşitli düzeylerde bilgileri günlüğe kaydetmek için API'ler sunar. Bu günlük düzeyleri şunlardır:

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

İşte günlüğe kaydetme API'sini nasıl kullanabileceğinize dair bir örnek:

...
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}'");
}

// ...

Gereksiz ayırmayı önlemek için, seviyenin olarak etkinleştirilip etkinleştirilmediğini kontrol etmek için ILogger.IsEnabled(LogLevel) API'sini kullanmanız gerektiğini unutmayın.

IMessageBus hizmeti

Mesajlaşma veri yolu hizmeti, test çerçevesi ile uzantıları arasında bilgi alışverişini kolaylaştıran merkezi bir mekanizmadır.

Test platformunun mesaj veriyolu yayınla-abone oldesenini kullanır.

Paylaşılan veri yolunun ana yapısı aşağıdaki gibidir:

Uzantılar ve test çerçevesi içeren diyagramda gösterildiği gibi iki olası eylem vardır: verileri veri yolu'na gönderme veya veri yolu bilgilerini kullanma.

IMessageBus, veri yolu gönderme eylemini karşılamış ve API şöyledir:

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

Parametrelerle ilgili aşağıdaki ayrıntıları göz önünde bulundurun:

• IDataProducer: IDataProducer, sağlayabildiği bilgilerin Type'sini mesaj veri yolu üzerinden iletir ve IExtension temel arabiriminden devralma yoluyla sahiplik oluşturur. Bu, verileri ayrımsız olarak ileti veri yolu'na gönderememenizi ifade eder; oluşturulan veri türünü önceden bildirmeniz gerekir. Beklenmeyen veriler göndermeniz durumunda bir özel durum tetiklenir.

• IData: Bu arabirim, yalnızca ad ve açıklama gibi açıklayıcı ayrıntıları sağlamanız gereken bir yer tutucu görevi görür. Arabirim, verilerin doğası hakkında çok fazla bilgi vermez ve bu da kasıtlı olarak gerçekleştirilen bir işlemdir. Test çerçevesinin ve uzantıların veri yolu için herhangi bir veri türünü gönderebildiğini ve bu verilerin herhangi bir kayıtlı uzantı veya test çerçevesi tarafından tüketilebileceği anlamına gelir.

Bu yaklaşım, bilgi alışverişi sürecinin evrimini kolaylaştırarak uzantının yeni verilere aşina olmaması durumunda bozulmalara yol açabilecek değişiklikleri önler. Uzantıların ve test çerçevesinin farklı sürümlerinin, karşılıklı anlamagöre uyum içinde çalışmasına izin verir.

Veri yolunun karşı ucu, belirli bir veri türüne abone olan ve bu nedenle bunu tüketebilen bir tüketici olarak adlandırılır.

Önemli

Her zaman bekleyin. Aksi takdirde, IData test platformu ve uzantıları tarafından doğru şekilde işlenmeyebilir ve bu da küçük hatalara yol açabilir. Yalnızca await döndükten sonra, IData'nin ileti veri yolu üzerinde işlenmek üzere kuyruğa alındığını doğrulayabilirsiniz. Üzerinde çalıştığınız uzantı noktasından bağımsız olarak, uzantıdan çıkmadan önce tüm PublishAsync çağrılarını beklediğinize emin olun. Örneğin, testing frameworkuyguluyorsanız, belirli bir istek için tüm Complete çağrılarını beklemeden isteklerinde PublishAsync çağırmamalısınız.

IOutputDevice hizmeti

Test platformu, birçıkış cihazı fikrini kapsüller ve test çerçevesinin ve uzantıların, kullanılan görüntüleme sistemine herhangi bir veri türünü ileterek bilgileri sunmasına olanak sağlar.

çıkış cihazı en geleneksel örneği konsol çıkışıdır.

Dikkat

Test platformu, özelçıkış cihazlarını destekleyecek şekilde tasarlanmış olsa da, şu anda bu uzantı noktası kullanılamaz.

çıkış cihazına veri aktarmak için IOutputDeviceIServiceProvideredinmelisiniz.

API şunlardan oluşur:

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

public interface IOutputDeviceDataProducer : IExtension
{
}

public interface IOutputDeviceData
{
}

IOutputDeviceDataProducer IExtension genişletir ve gönderen hakkındaki bilgileri çıkış cihazınasağlar.

IOutputDeviceData geçici bir arayüz görevi görür. IOutputDevice ardındaki kavram, yalnızca renkli metinlerden daha karmaşık bilgiler barındırmaktır. Örneğin, grafik olarak temsil edilebilen karmaşık bir nesne olabilir.

Test platformu varsayılan olarak IOutputDeviceData nesnesi için geleneksel renkli bir metin modeli sunar:

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

Renkli metni etkin çıkış cihazıyla nasıl kullanabileceğinize ilişkin bir örnek aşağıda verilmişti:

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
        }
    });

Renkli metinlerin standart kullanımının ötesinde, IOutputDevice ve IOutputDeviceData temel avantajı şudur ki, çıkış cihazı tamamen bağımsızdır ve kullanıcı tarafından bilinmez. Bu, karmaşık kullanıcı arabirimlerinin geliştirilmesine olanak tanır. Örneğin, testlerin ilerleme durumunu görüntüleyen bir gerçek zamanlı web uygulaması uygulamak tamamen mümkündür.

IPlatformInformation hizmeti

Platform hakkında ad, sürüm, işleme karması ve derleme tarihi gibi bilgiler sağlar.