Configurazione di MSTest SDK

Questo articolo illustra le opzioni di configurazione avanzate per MSTest.Sdk. Per la configurazione di base e l'avvio, vedere Introduzione a MSTest.

Importante

Per impostazione predefinita, MSTest.Sdk usa lo strumento di esecuzione MSTest con MTP, incluso con dotnet test. Ciò richiede la modifica delle chiamate CI e della CLI locale, e influisce anche sugli elementi disponibili di .runsettings. È possibile mantenere le vecchie integrazioni e gli strumenti passando a VSTest.

MSTest.Sdk imposta EnableMSTestRunner e TestingPlatformDotnetTestSupport su true per impostazione predefinita. Per altre informazioni sul test dotnet e sulle relative diverse modalità, vedere Test con dotnet test.

Biblioteche di supporto per utility di test

Se il project che usa MSTest.Sdk deve essere una libreria helper dell'utilità di test e non contiene per sé test eseguibili, il project deve avere <IsTestApplication>false</IsTestApplication>.

Seleziona il corridore

Per impostazione predefinita, MSTest SDK si basa su MTP, ma è possibile passare a VSTest aggiungendo la proprietà <UseVSTest>true</UseVSTest>.

Estendere il protocollo MTP

È possibile personalizzare l'esperienza MTP tramite un set di estensioni del pacchetto NuGet. Per semplificare e migliorare questa esperienza, MSTest SDK introduce due funzionalità:

Microsoft.Testing.Platform profilo

Il concetto di profile consente di selezionare il set predefinito di configurazioni ed estensioni che verranno applicate al project di test.

È possibile impostare il profilo usando la proprietà TestingExtensionsProfile con uno dei tre profili seguenti:

  • None - Non viene abilitata alcuna estensione.

  • Default - Abilita le estensioni consigliate per questa versione di MSTest.SDK. Si tratta dell'impostazione predefinita quando la proprietà non è impostata in modo esplicito.

    Abilita le estensioni seguenti:

  • AllMicrosoft - Abilita le estensioni Microsoft selezionate per un ampio uso generale predefinito, incluse le estensioni con licenza restrittiva. Le estensioni sperimentali e solo API possono comunque richiedere il consenso esplicito.

    Abilita tutte le estensioni dal Default profilo, oltre alle estensioni seguenti:

    In MSTest.Sdk versioni da 3.11.0 a 4.2.x l'estensione Azure DevOps report è inclusa solo in AllMicrosoft.

Nota

I profili fanno riferimento ai pacchetti report Azure DevOps e GitHub Actions report, ma la creazione di report rimane disabilitata in fase di esecuzione. Passa --report-azdo per abilitare la creazione di report in Azure DevOps. Per abilitare la creazione di report GitHub Actions, eseguire i test in GitHub Actions e passare --report-gh.

Di seguito è riportato un esempio completo, usando il profilo None:

<Project Sdk="MSTest.Sdk/4.1.0">

    <PropertyGroup>
        <TargetFramework>net10.0</TargetFramework>
        <TestingExtensionsProfile>None</TestingExtensionsProfile>
    </PropertyGroup>

</Project>
Estensione/Profilo Nessuno Predefinito AllMicrosoft
Copertura del codice ✔️ ✔️
dump di arresto anomalo del sistema ✔️
Falsi ✔️¹
scarica sospesa ✔️
Ricaricamento rapido ✔️
HTML Report ✔️
Report di GitHub Actions ✔️³ ✔️³
riprovare ✔️
Trx ✔️ ✔️
Report di Azure DevOps ✔️³ ✔️²

¹ MSTest.Sdk 3.7.0+ ² MSTest.Sdk 3.11.0+ ² MSTest.Sdk 4.3.0+

Abilitare o disabilitare le estensioni

Le estensioni possono essere abilitate e disabilitate dalle proprietà di MSBuild con il modello Enable[NugetPackageNameWithoutDots].

Ad esempio, per abilitare l'estensione crash dump (pacchetto NuGet Microsoft.Testing.Extensions.CrashDump), è possibile utilizzare la seguente proprietà EnableMicrosoftTestingExtensionsCrashDump impostata su true:

<Project Sdk="MSTest.Sdk/4.1.0">

<PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <EnableMicrosoftTestingExtensionsCrashDump>true</EnableMicrosoftTestingExtensionsCrashDump>
</PropertyGroup>

</Project>

Per un elenco di tutte le estensioni disponibili, vedere Funzionalità MTP.

Alcune estensioni MTP rimangono facoltative e non sono incluse nei profili Default o AllMicrosoft:

  • A partire da MSTest.Sdk 4.3, impostare <EnableMicrosoftTestingExtensionsJUnitReport>true</EnableMicrosoftTestingExtensionsJUnitReport>, quindi passare --report-junit.
  • A partire dall'anteprima di MSTest.Sdk 4.4, impostare <EnableMicrosoftTestingExtensionsCtrfReport>true</EnableMicrosoftTestingExtensionsCtrfReport>, quindi passare --report-ctrf.
  • Per fare riferimento all'estensione OpenTelemetry, impostare <EnableMicrosoftTestingExtensionsOpenTelemetry>true</EnableMicrosoftTestingExtensionsOpenTelemetry>. Poiché l'estensione richiede la configurazione API, registrarla nel punto di ingresso personalizzato come descritto in OpenTelemetry.

Queste estensioni sono disponibili solo con MTP.

Avviso

È importante rivedere le condizioni di licenza per ogni estensione in quanto potrebbero variare.

Le estensioni abilitate e disabilitate vengono combinate con le estensioni fornite dal profilo di estensione selezionato.

Questi criteri di proprietà possono essere utilizzati per abilitare un'estensione aggiuntiva sopra il profilo Default implicito (come illustrato nell'esempio CrashDumpExtension precedente).

È anche possibile disabilitare un'estensione proveniente dal profilo selezionato. Ad esempio, disabilitare l'estensione MS Code Coverage impostando <EnableMicrosoftTestingExtensionsCodeCoverage>false</EnableMicrosoftTestingExtensionsCodeCoverage>:

<Project Sdk="MSTest.Sdk/4.1.0">

    <PropertyGroup>
        <TargetFramework>net10.0</TargetFramework>
        <EnableMicrosoftTestingExtensionsCodeCoverage>false</EnableMicrosoftTestingExtensionsCodeCoverage>
    </PropertyGroup>

</Project>

In MSTest.Sdk 4.3.0 e versioni successive il Default profilo fa riferimento ai pacchetti report Azure DevOps e GitHub Actions report. Per rimuovere il riferimento al pacchetto, impostare <EnableMicrosoftTestingExtensionsAzureDevOpsReport>false</EnableMicrosoftTestingExtensionsAzureDevOpsReport> o <EnableMicrosoftTestingExtensionsGitHubActionsReport>false</EnableMicrosoftTestingExtensionsGitHubActionsReport>. Se mantieni i riferimenti al pacchetto, la creazione di report in Azure DevOps inizia solo quando passi --report-azdo. La creazione di report in GitHub Actions inizia solo quando esegui i test su GitHub Actions e passi --report-gh.

Funzionalità

Oltre alla selezione del runner e delle relative estensioni specifiche, MSTest.Sdk offre anche funzionalità aggiuntive per semplificare e migliorare l'esperienza di testare.

Test con Aspire

Aspire è uno stack predefinito e pronto per il cloud per la creazione di applicazioni osservabili, pronte per la produzione e distribuite. Aspire viene distribuito tramite una raccolta di pacchetti NuGet che gestiscono problemi specifici nativi del cloud. Per altre informazioni, vedere la Aspire documentazione.

Nota

Questa funzionalità è disponibile in MSTest.Sdk 3.4.0.

Impostando la proprietà EnableAspireTesting su true, è possibile importare tutte le dipendenze e le direttive using predefinite necessarie per i test con Aspire e MSTest.

<Project Sdk="MSTest.Sdk/4.1.0">

    <PropertyGroup>
        <TargetFramework>net10.0</TargetFramework>
        <EnableAspireTesting>true</EnableAspireTesting>
    </PropertyGroup>

</Project>

Esegui test con Playwright

Playwright consente di effettuare test end-to-end affidabili per le applicazioni web moderne. Per altre informazioni, vedere la documentazione ufficiale Playwright.

Nota

Questa funzionalità è disponibile in MSTest.Sdk 3.4.0.

Impostando la proprietà EnablePlaywright su true, è possibile importare tutte le dipendenze e le direttive using predefinite necessarie per i test con Playwright e MSTest.

<Project Sdk="MSTest.Sdk/4.1.0">

    <PropertyGroup>
        <TargetFramework>net10.0</TargetFramework>
        <EnablePlaywright>true</EnablePlaywright>
    </PropertyGroup>

</Project>

Migrazione a MSTest SDK

Prendere in considerazione i passaggi seguenti necessari per eseguire la migrazione a MSTest SDK.

Aggiornare il project

Quando si esegue la migrazione di un progetto di test MSTest esistente a MSTest SDK, iniziare sostituendo la voce Sdk="Microsoft.NET.Sdk" nella parte superiore del progetto di test con Sdk="MSTest.Sdk"

- Sdk="Microsoft.NET.Sdk"
+ Sdk="MSTest.Sdk"

Aggiungi la versione al global.json:

{
    "msbuild-sdks": {
        "MSTest.Sdk": "4.1.0"
    }
}

È quindi possibile iniziare a semplificare il project.

Rimuovere le proprietà predefinite:

- <EnableMSTestRunner>true</EnableMSTestRunner>
- <OutputType>Exe</OutputType>
- <IsPackable>false</IsPackable>
- <IsTestProject>true</IsTestProject>

Rimuovere i riferimenti ai pacchetti predefiniti:

- <PackageReference Include="MSTest"
- <PackageReference Include="MSTest.TestFramework"
- <PackageReference Include="MSTest.TestAdapter"
- <PackageReference Include="MSTest.Analyzers"
- <PackageReference Include="Microsoft.NET.Test.Sdk"

Infine, in base al profilo delle estensioni in uso, è anche possibile rimuovere alcuni dei pacchetti Microsoft.Testing.Extensions.*.

Aggiorna il tuo CI

Dopo aver aggiornato i progetti, se si usa MTP (impostazione predefinita) e se ci si affida dotnet test per eseguire i test, è necessario aggiornare la configurazione CI. Per ulteriori informazioni e per facilitare la comprensione di tutte le modifiche necessarie, consultare l'integrazione dei test di dotnet.

Se si usa la modalità VSTest di dotnet test, di seguito è riportato un esempio di aggiornamento quando si usa l'attività DotNetCoreCLI in Azure DevOps:

Il profilo di estensione predefinito di MSTest.Sdk fornisce i pacchetti Microsoft.Testing.Extensions.TrxReport e Microsoft.Testing.Extensions.CodeCoverage richiesti dalle opzioni aggiuntive. Selezionando il profilo None, abilitare o richiamare entrambe le estensioni prima di utilizzare le opzioni.

\- task: DotNetCoreCLI@2
  inputs:
    command: 'test'
    projects: '**/**.sln'
-    arguments: '--configuration Release'
+    arguments: '--configuration Release -- --report-trx --results-directory $(Agent.TempDirectory) --coverage'

Generatore di codice sorgente basato sulla riflessione

Importante

Il comportamento MSTest 4.4 seguente è disponibile solo nelle build di anteprima fino al rilascio di MSTest 4.4.0.

MSTest 4.3 ha introdotto il generatore di codice sorgente basato sulla reflection nel pacchetto sperimentale MSTest.SourceGeneration con versionamento indipendente. A partire da MSTest 4.4, il pacchetto esce dallo stato sperimentale e adotta la versione di MSTest.

I progetti AOT nativi includono automaticamente il generatore di origine. Per un progetto non NativeAOT che usa MSTest.Sdk, abilitarlo con <EnableMSTestSourceGeneration>true</EnableMSTestSourceGeneration>. MSTest.Sdk allinea le versioni MSTest.SourceGeneration, MSTest.TestFramework e MSTest.TestAdapter tramite MSTestVersion.

L'SDK supporta anche la generazione di origine in librerie e progetti di test riutilizzabili che usano Central Package Management. Fornisce hook di runtime corrispondenti MSTest.TestAdapter e genera gli elementi PackageVersion necessari.

.NET Standard non supporta questi hook di runtime. Quando si abilita la generazione di origine per una destinazione .NET Standard, l'SDK segnala questo errore:

La generazione del codice sorgente di MSTest non è supportata per i framework di destinazione .NET Standard perché i necessari hook di runtime di MSTest.TestAdapter non sono disponibili.

Il generatore di origine individua i test in fase di compilazione. Quando il generatore è attivo, le classi di test devono dichiarare [TestClass] direttamente anziché ereditarla. L'analizzatore MSTEST0069 contrassegna le classi che si basano su un oggetto ereditato[TestClass].

A partire da MSTest 4.3.2, MSTestSourceGenMode è impostato per impostazione predefinita su ReflectionFree per i progetti sottoposti a trimming e Native AOT. Questa modalità usa metadati generati e invocatori quando supporta la struttura del test. Negli ambienti di runtime che supportano la reflection, MSTest ricorre alla reflection per gli elementi generati non supportati o mancanti.

A partire da MSTest 4.4, la generazione senza riflessione materializza i metadati completi degli attributi ereditati, inclusi AttributeUsage e AllowMultiple. In MTP, è possibile bypassare il rilevamento e la convalida in fase di esecuzione per i metodi sincroni semplici [DataRow] e [TestMethod]. I test asincroni, gli attributi del metodo di test personalizzato, DynamicDatale implementazioni personalizzate ITestDataSource e le forme di test ambigue usano il percorso di fallback. VSTest mantiene anche il percorso esistente.

La modalità senza riflessione riporta queste informazioni diagnostiche:

ID Forma di test non supportata
AOTSG0001 Classe di test statica
AOTSG0002 Aprire una classe di test generica, inclusa una classe annidata in un tipo generico
AOTSG0003 Classe a cui il codice generato non può accedere, inclusa una classe locale al file o una classe annidata privata o private-protected
AOTSG0004 Metodo di test generico
AOTSG0005 Metodo di test con un refparametro , ino out

Funzionalità sperimentali

Le funzionalità MSTest 4.3 seguenti sono sperimentali. Le loro API pubbliche sono soggette a modifiche e sono esposte tramite strumenti diagnostici sperimentali. Per aderire, confermare l'ID diagnostico corrispondente.

Filtro di test a livello di codice con ITestFilter

Nota

Introdotto in MSTest 4.3.0 (sperimentale).

Il punto di estensione sperimentale ITestFilter , registrato tramite [TestFilterProviderAttribute], consente di decidere a livello di codice se ogni test viene eseguito, prima del caricamento di qualsiasi classe di test. Ciò è utile per la logica di selezione personalizzata che non può essere espressa con i filtri della riga di comando.

Implementare ITestFilter.Filter(TestFilterContext) per esaminare i metadati senza caricare la classe di test:

public sealed class MyFilter : ITestFilter
{
    public TestFilterResult Filter(TestFilterContext context) =>
        context.DisplayName.Contains("Nightly", StringComparison.Ordinal)
            ? TestFilterResult.Run : TestFilterResult.Drop;
}

Premi TestFilterResult.Run per eseguire il test, Drop per ometterlo senza registrare alcun risultato o Skip(reason) per segnalare un risultato saltato. MSTest può chiamare simultaneamente un'istanza di filtro, quindi le implementazioni devono essere thread-safe. I filtri della riga di comando e di Esplora test vengono eseguiti prima di ITestFilter, mentre [Ignore] viene valutato successivamente.

A partire da MSTest 4.4, i progetti .NET possono usare la forma di registrazione generica e tipizzata in modo sicuro [assembly: TestFilterProvider<MyFilter>]. Il compilatore applica quindi che MyFilter implementa ITestFilter e ha un costruttore pubblico senza parametri. L'attributo generico non è disponibile per .NET Framework. Per un progetto con più framework di destinazione, selezionare la forma generica o non generica usando un simbolo del preprocessore relativo al framework di destinazione.

#if NET
[assembly: TestFilterProvider<MyFilter>]
#else
[assembly: TestFilterProvider(typeof(MyFilter))]
#endif

A partire da MSTest 4.4, l'analizzatore MSTEST0081 convalida completamente il modulo di registrazione non generico. Per il modulo generico, vengono comunque segnalati tipi di filtro generici e assembly che registrano più provider.

TestRun.Current e test pianificati

Nota

Introdotto in MSTest 4.3.0 (sperimentale).

L'API sperimentale TestRun.Current (da RFC 014) espone informazioni sull'esecuzione corrente, incluso il set di test pianificati, in modo che le estensioni e le fixture possano controllare cosa è pianificato per l'esecuzione.

Limitazioni note

Gli SDK MSBuild forniti da NuGet (incluso MSTest.Sdk) hanno supporto limitato per gli strumenti quando si tratta di aggiornare la versione, il che significa che il consueto aggiornamento tramite NuGet e l'interfaccia utente di Visual Studio per la gestione dei pacchetti NuGet non funziona come previsto. È necessario aggiornare manualmente la versione nel file global.json e nel file project. Questo vale anche se si usa Dependabot a causa di problemi dependabot-core#12824 e dependabot-core#8615.

Vedi anche

  • Last updated on