Dela via

Microsoft.Testing.Platform Services

Testplattformen erbjuder värdefulla tjänster till både testramverket och tilläggspunkterna. Dessa tjänster tillgodoser vanliga behov, till exempel åtkomst till konfigurationen, parsning och hämtning av kommandoradsargument, hämtning av loggningsfabriken och åtkomst till loggningssystemet, bland annat. IServiceProvider implementerar tjänstlokaliserarmönster för testplattformen.

IServiceProvider härleds direkt från basklassbiblioteket.

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

Testplattformen erbjuder praktiska utökningar för att komma åt välkända serviceobjekt. Alla dessa metoder finns i en statisk klass i Microsoft.Testing.Platform.Services namnrymd.

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
}

De flesta av de registreringsfabriker som exponeras av tilläggspunkter ger tillgång till IServiceProvider. Till exempel, vid registrering av testramverket, skickas IServiceProvider som en parameter till fabriksmetoden.

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

I föregående kod anger både capabilitiesFactory och adapterFactoryIServiceProvider som en parameter.

Tjänsten IConfiguration

Gränssnittet IConfiguration kan hämtas med hjälp av IServiceProvider och tillhandahåller access till konfigurationsinställningarna för testramverket och eventuella tilläggspunkter. Som standard läses dessa konfigurationer in från:

  • Miljövariabler
  • En JSON-fil med namnet [assemblyName].testingplatformconfig.json som finns nära startpunktssammansättningen.

Prioritetsordningen bibehålls, vilket innebär att JSON-filen inte bearbetas om en konfiguration hittas i miljövariablerna.

Gränssnittet är ett enkelt nyckel/värde-par med strängar:

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

JSON-konfigurationsfil

JSON-filen följer en hierarkisk struktur. Om du vill få tillgång till underliggande egenskaper måste du använda avgränsaren :. Överväg till exempel en konfiguration för ett potentiellt testramverk som:

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

Kodfragmentet skulle se ut ungefär så här:

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

var configuration = serviceProvider.GetConfiguration();

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

När det gäller en matris, till exempel:

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

Syntaxen för att få åtkomst till det första elementet ("ThreadPool") är:

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

var configuration = serviceProvider.GetConfiguration();

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

Miljövariabler

Den : avgränsaren fungerar inte med hierarkiska nycklar för miljövariabler på alla plattformar. __, det dubbla understrecket, är:

  • Stöds av alla plattformar. Den : avgränsaren stöds till exempel inte av Bash, men __ är det.
  • Ersätts automatiskt av en :

Miljövariabeln kan till exempel anges på följande sätt (det här exemplet gäller för Windows):

setx CustomTestingFramework__DisableParallelism=True

Du kan välja att inte använda miljövariabelns konfigurationskälla när du skapar ITestApplicationBuilder:

var options = new TestApplicationOptions();

options.Configuration.ConfigurationSources.RegisterEnvironmentVariablesConfigurationSource = false;

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

Tjänsten ICommandLineOptions

Tjänsten ICommandLineOptions används för att hämta information om de kommandoradsalternativ som plattformen har parsat. De TILLGÄNGLIGA API:erna är:

public interface ICommandLineOptions
{
    bool IsOptionSet(string optionName);

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

ICommandLineOptions kan hämtas via vissa API:er, till exempel ICommandLineOptionsProvider, eller så kan du hämta en instans av den från IServiceProvider via tilläggsmetoden serviceProvider.GetCommandLineOptions().

ICommandLineOptions.IsOptionSet(string optionName): Med den här metoden kan du kontrollera om ett visst alternativ har angetts. När du anger optionNameutelämnar du prefixet --. Om användaren till exempel anger --myOptionbör du bara skicka myOption.

ICommandLineOptions.TryGetOptionArgumentList(string optionName, out string[]? arguments): Med den här metoden kan du kontrollera om ett visst alternativ har angetts och i så fall hämta motsvarande värde eller värden (om ariteten är mer än ett). På samma sätt som i föregående fall bör optionName anges utan prefixet --.

Tjänsten ILoggerFactory

Testplattformen levereras med ett integrerat loggningssystem som genererar en loggfil. Du kan visa loggningsalternativen genom att köra kommandot --help. De alternativ du kan välja mellan ä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'

För att logga information måste du först hämta ILoggerFactory från IServiceProvider. API:et ILoggerFactory är följande:

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

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

Med loggerfabriken kan du skapa ett ILogger objekt med hjälp av api:et CreateLogger. Det finns också ett praktiskt API som accepterar ett allmänt argument som används som kategorinamn.

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

Det ILogger objektet, som skapas av ILoggerFactory, erbjuder API:er för loggningsinformation på olika nivåer. Dessa loggningsnivåer omfattar:

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

Här är ett exempel på hur du kan använda loggnings-API:et:

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

// ...

Tänk på att för att förhindra onödig allokering bör du kontrollera om nivån är aktiverad med hjälp av ILogger.IsEnabled(LogLevel)-API:et.

Tjänsten IMessageBus

Meddelandebusstjänsten är den centrala mekanismen som underlättar information exchange mellan testramverket och dess tillägg.

Testplattformens meddelandebuss använder publicera-prenumerera-mönstret.

Den övergripande strukturen för den delade bussen är följande:

En bild som representerar interaktionerna mellan de olika tilläggen och meddelandebussen.

Som illustreras i diagrammet, som innehåller ett tillägg och ett testramverk, finns det två möjliga åtgärder: att skicka information till bussen eller använda information från bussen.

IMessageBus uppfyllde push-åtgärden till bussen och API:et är:

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

Överväg följande information om parametrarna:

  • IDataProducer: IDataProducer kommunicerar till meddelandebussen om Type av information som den kan tillhandahålla och fastställer ägarskap genom arv från basgränssnittet IExtension. Detta innebär att du inte urskillningslöst kan skicka data till meddelandebussen. du måste deklarera den datatyp som produceras i förväg. Om du skickar oväntade data utlöses ett undantag.

  • IData: Det här gränssnittet fungerar som en platshållare där du bara behöver ange beskrivande information, till exempel namnet och en beskrivning. Gränssnittet avslöjar inte mycket om datans natur, vilket är avsiktligt. Det innebär att testramverket och tilläggen kan skicka alla typer av data till bussen, och dessa data kan användas av alla registrerade tillägg eller själva testramverket.

Den här metoden underlättar utvecklingen av informationsutbytesprocessen, vilket förhindrar förändringar som bryts när ett tillägg inte känner igen ny data. Det gör att olika versioner av tillägg och testramverket kan fungera i harmoni, baserat på deras ömsesidiga förståelse.

Den motsatta änden av bussen kallas för en consumer, som prenumererar på en viss typ av data och därmed kan använda den.

Viktig

Använd alltid vänta på anropet till PublishAsync. Om du inte gör det kanske IData inte bearbetas korrekt av testplattformen och tilläggen, vilket kan leda till subtila buggar. Det är först efter att du har återvänt från att vänta på vid som du kan vara säker på att IData har placerats i kö för bearbetning på meddelandebussen. Oavsett vilken tilläggspunkt du arbetar med, säkerställ att du har väntat på alla PublishAsync-anrop innan du avslutar tillägget. Om du till exempel implementerar testing frameworkbör du inte anropa Complete på begäranden förrän du har väntat på alla PublishAsync anrop för den specifika begäran.

Tjänsten IOutputDevice

Testplattformen kapslar in idén om en utdataenhet, vilket gör att testramverket och tilläggen kan presentera information genom att överföra alla typer av data till det aktuella visningssystemet.

Det mest traditionella exemplet på en utdataenhet är konsolutdata.

Anmärkning

Testplattformen har utformats för att stödja anpassade utdataenheter, men den här tilläggspunkten är för närvarande inte tillgänglig.

Om du vill överföra data till utdataenhetmåste du hämta IOutputDevice från IServiceProvider.

API:et består av:

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

public interface IOutputDeviceDataProducer : IExtension
{
}

public interface IOutputDeviceData
{
}

IOutputDeviceDataProducer utökar IExtension och ger information om avsändaren till utdataenhet.

IOutputDeviceData fungerar som ett platshållargränssnitt. Konceptet bakom IOutputDevice är att hantera mer invecklad information än bara färgad text. Det kan till exempel vara ett komplext objekt som kan representeras grafiskt.

Testplattformen erbjuder som standard en traditionell färgad textmodell för IOutputDeviceData-objektet:

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

Här är ett exempel på hur du kan använda färgad text med den aktiva utdataenheten:

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

Utöver standardanvändningen av färgad text är den största fördelen med IOutputDevice och IOutputDeviceData att den utdataenheten är helt oberoende och okänd för användaren. Detta möjliggör utveckling av komplexa användargränssnitt. Det är till exempel helt möjligt att implementera en realtids- webbapp som visar förloppet för tester.

Tjänsten IPlatformInformation

Innehåller information om plattformen, till exempel: namn, version, incheckningshash och byggdatum.

  • Last updated on