dotnet test

Articolo
03/27/2024

Questo articolo si applica a: ✔️ .NET Core 3.1 SDK e versioni successive

Nome

dotnet test: driver di test .NET usato per eseguire gli unit test.

Riepilogo

dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
    [--test-adapter-path <ADAPTER_PATH>]
    [-a|--arch <ARCHITECTURE>]
    [--blame]
    [--blame-crash]
    [--blame-crash-dump-type <DUMP_TYPE>]
    [--blame-crash-collect-always]
    [--blame-hang]
    [--blame-hang-dump-type <DUMP_TYPE>]
    [--blame-hang-timeout <TIMESPAN>]
    [-c|--configuration <CONFIGURATION>]
    [--collect <DATA_COLLECTOR_NAME>]
    [-d|--diag <LOG_FILE>]
    [-f|--framework <FRAMEWORK>]
    [-e|--environment <NAME="VALUE">]
    [--filter <EXPRESSION>]
    [--interactive]
    [-l|--logger <LOGGER>]
    [--no-build]
    [--nologo]
    [--no-restore]
    [-o|--output <OUTPUT_DIRECTORY>]
    [--os <OS>]
    [--results-directory <RESULTS_DIR>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [-s|--settings <SETTINGS_FILE>]
    [-t|--list-tests]
    [-v|--verbosity <LEVEL>]
    [<args>...]
    [[--] <RunSettings arguments>]

dotnet test -h|--help

Descrizione

Il comando dotnet test si usa per eseguire unit test in una determinata soluzione. Il comando dotnet test compila la soluzione ed esegue un'applicazione host di test per ogni progetto di test nella soluzione. L'host di test esegue i test nel progetto specificato usando un framework di test, ad esempio MSTest, NUnit o xUnit, e segnala l'esito positivo o negativo di ogni test. Se tutti i test hanno esito positivo, il test runner restituisce 0 come codice di uscita. Se invece i test hanno esito negativo, restituisce 1.

Per i progetti con più destinazioni, i test vengono eseguiti per ogni framework di destinazione. L'host di test e il framework di unit test sono disponibili come pacchetti NuGet e vengono ripristinati come dipendenze ordinarie per il progetto. A partire da .NET 9 SDK, questi test vengono eseguiti in parallelo per impostazione predefinita. Per disabilitare l'esecuzione parallela, impostare la TestTfmsInParallel proprietà MSBuild su false. Per altre informazioni, vedere Eseguire test in parallelo e la riga di comando di esempio più avanti in questo articolo.

I progetti di test specificano l'applicazione di esecuzione dei test usando un normale elemento <PackageReference>, come illustrato nel file di progetto di esempio seguente:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
    <PackageReference Include="xunit" Version="2.7.1" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.8" />
  </ItemGroup>

</Project>

Nell'esempio, Microsoft.NET.Test.Sdk è l'host di test, xunit è il framework di test e xunit.runner.visualstudio è un adattatore di test, che permette al framework xUnit di interagire con l'host di test.

Ripristino implicito

Non è necessario eseguire dotnet restore perché viene eseguito in modo implicito da tutti i comandi che richiedono un ripristino, ad esempio dotnet new, dotnet build, dotnet run, dotnet test, dotnet publish e dotnet pack. Per disabilitare il ripristino implicito, usare l'opzione --no-restore.

Il comando dotnet restore è ancora utile in alcuni scenari in cui ha senso eseguire un ripristino esplicito, ad esempio le compilazioni di integrazione continua in Azure DevOps Services o in sistemi di compilazione che richiedono il controllo esplicito quando viene eseguito il ripristino.

Per informazioni su come gestire i feed NuGet, vedere la dotnet restore documentazione.

Download del manifesto del carico di lavoro

Quando si esegue questo comando, avvia un download in background asincrono dei manifesti pubblicitari per i carichi di lavoro. Se il download è ancora in esecuzione al termine di questo comando, il download viene arrestato. Per altre informazioni, vedere Manifesti pubblicitari.

Argomenti

PROJECT | SOLUTION | DIRECTORY | DLL | EXE
- Percorso del progetto di test.
- Percorso della soluzione.
- Percorso di una directory contenente un progetto o una soluzione.
- Percorso del file .dll di un progetto di test.
- Percorso del file .exe di un progetto di test.
Se non specificato, l'effetto è lo stesso che si ottiene usando l'argomento DIRECTORY per specificare la directory corrente.

Opzioni

Avviso

Modifiche che causano un'interruzione nelle opzioni:

A partire da .NET 7: usare -a come alias di --arch anziché di --test-adapter-path
A partire da .NET 7: usare -r come alias di --runtime anziché di --results-directory

--test-adapter-path <ADAPTER_PATH>

Percorso di una directory in cui cercare altri adattatori di test. Vengono controllati solo i file .dll con suffisso .TestAdapter.dll. Se non specificato, la ricerca viene eseguita nella directory del file .dll del test.

Nelle versioni di .NET SDK precedenti alla 7 è disponibile la forma breve -a.

--arch <ARCHITECTURE>

Specifica l'architettura di destinazione. Si tratta di una sintassi abbreviata per l'impostazione dell'identificatore di runtime (RID), in cui il valore fornito viene combinato con il RID predefinito. Ad esempio, in un computer win-x64, specificando --arch x86 si imposta il RID su win-x86. Se si usa questa opzione, non usare l'opzione -r|--runtime. Disponibile a partire da .NET 6 Preview 7.

--blame

Esegue i test in modalità di segnalazione degli errori. Questa opzione è utile per isolare i test problematici che causano l'arresto anomalo dell'host di test. Quando viene rilevato un arresto anomalo, crea un file di sequenza in TestResults/<Guid>/<Guid>_Sequence.xml che acquisisce l'ordine dei test eseguiti prima dell'arresto anomalo.

Questa opzione non crea un dump di memoria e non è utile quando il test è bloccato.
--blame-crash (disponibile a partire da .NET 5.0 SDK)

Esegue i test in modalità di segnalazione errore e raccoglie un dump di arresto anomalo quando l'host di test si chiude in modo imprevisto. Questa opzione dipende dalla versione di .NET usata, dal tipo di errore e dal sistema operativo.

Per le eccezioni nel codice gestito, in .NET 5.0 e versioni successive verrà raccolto automaticamente un dump. Verrà generato un dump per l'host di test o per qualsiasi altro processo figlio eseguito in .NET 5.0 che si è arrestato in modo anomalo. Gli arresti anomali nel codice nativo non genereranno un dump. Questa opzione funziona in Windows, macOS e Linux.

I dump di arresto anomalo del sistema nel codice nativo, oppure quando si usa .NET Core 3.1 e versioni precedenti, possono essere raccolti solo in Windows tramite Procdump. Nella variabile di ambiente PATH o PROCDUMP_PATH deve essere specificata una directory contenente procdump.exe e procdump64.exe. Scaricare gli strumenti. Implica --blame.

Per raccogliere un dump di arresto anomalo da un'applicazione nativa in esecuzione in .NET 5.0 o versione successiva, è possibile forzare l'utilizzo di Procdump impostando la variabile di ambiente VSTEST_DUMP_FORCEPROCDUMP su 1.
--blame-crash-dump-type <DUMP_TYPE> (disponibile a partire da .NET 5.0 SDK)

Tipo di dump di arresto anomalo da raccogliere. I tipi di dump supportati sono full (valore predefinito) e mini. Implica --blame-crash.
--blame-crash-collect-always (disponibile a partire da .NET 5.0 SDK)

Raccoglie un dump di arresto anomalo in caso di chiusura prevista o imprevista dell'host di test.
--blame-hang (disponibile a partire da .NET 5.0 SDK)

Esegue i test in modalità di segnalazione errore e abilita la raccolta di un dump di blocco quando un test supera il timeout specificato.
--blame-hang-dump-type <DUMP_TYPE> (disponibile a partire da .NET 5.0 SDK)

Tipo di dump di arresto anomalo da raccogliere. Deve essere full, mini o none. Quando si specifica none, l'host di test viene terminato al raggiungimento del timeout, ma non viene raccolto alcun dump. Implica --blame-hang.
--blame-hang-timeout <TIMESPAN> (disponibile a partire da .NET 5.0 SDK)

Timeout per singolo test dopo il quale viene attivato un dump di blocco; il processo dell'host di test con tutti i suoi processi figlio viene terminato e vengono raccolti i dump. Il valore di timeout viene specificato in uno dei formati seguenti:
- 1.5h, 1.5hour, 1.5hours
- 90m, 90min, 90minute, 90minutes
- 5400s, 5400sec, 5400second, 5400seconds
- 5400000ms, 5400000mil, 5400000millisecond, 5400000milliseconds
Quando non viene usata alcuna unità (ad esempio 5400000), si presuppone che il valore sia espresso in millisecondi. Se viene usato insieme a test basati sui dati, il comportamento di timeout dipende dall'adattatore di test usato. Per xUnit, NUnit e MSTest 2.2.4+, il timeout viene rinnovato dopo ogni test case. Per MSTest prima della versione 2.2.4, il timeout viene usato per tutti i test case. Questa opzione è supportata in Windows con netcoreapp2.1 e versioni successive, in Linux con netcoreapp3.1 e versioni successive e in macOS con net5.0 o versioni successive. Implica --blame e --blame-hang.

-c|--configuration <CONFIGURATION>

Definisce la configurazione di compilazione. Il valore predefinito per la maggior parte dei progetti è Debug, ma è possibile eseguire l'override delle impostazioni di configurazione della compilazione nel progetto.

--collect <DATA_COLLECTOR_NAME>

Abilita l'agente di raccolta dati per l'esecuzione dei test. Per altre informazioni, vedere Monitoraggio e analisi di esecuzioni dei test.

Ad esempio, è possibile raccogliere il code coverage usando l'opzione --collect "Code Coverage". Per altre informazioni, vedere Usare la funzionalità code coverage, Personalizzare l'analisi code coverage e il problema GitHub dotnet/docs#34479.

Per raccogliere il code coverage è anche possibile usare Coverlet con l'opzione --collect "XPlat Code Coverage".
-d|--diag <LOG_FILE>

Abilita la modalità di diagnostica per la piattaforma di test e scrive messaggi di diagnostica nel file specificato e nei file adiacenti. Il processo che registra i messaggi determina quali file vengono creati, ad esempio *.host_<date>.txt per il log dell'host di test e *.datacollector_<date>.txt per il log dell'agente di raccolta dati.
-e|--environment <NAME="VALUE">

Imposta il valore di una variabile di ambiente. Crea la variabile se non esiste, ne esegue l'override se esiste. L'uso di questa opzione forzerà l'esecuzione dei test in un processo isolato. È possibile specificare l'opzione più volte per fornire più variabili.
-f|--framework <FRAMEWORK>

Moniker framework di destinazione (TFM) del framework di destinazione per cui eseguire i test. Il framework di destinazione deve essere specificato anche nel file di progetto.
--filter <EXPRESSION>

Filtra i test nel progetto corrente usando l'espressione specificata. Vengono eseguiti solo i test che corrispondono all'espressione filtro. Per altre informazioni, vedere la sezione Dettagli dell'opzione filter. Per altre informazioni ed esempi sull'uso del filtro degli unit test selettivi, vedere Esecuzione di unit test selettivi.

-?|-h|--help

Stampa le istruzioni di utilizzo del comando.

--interactive

Consente al comando di arrestarsi e attendere l'input o l'azione dell'utente, ad esempio il completamento dell'autenticazione. Disponibile a partire da .NET Core 3.0 SDK.

-l|--logger <LOGGER>

Specifica un logger per i risultati del test e, facoltativamente, le opzioni per il logger. Specificare questo parametro più volte per abilitare più logger. Per altre informazioni, vedere Creazione di report sui risultati dei test, Opzioni per i logger e gli esempi più avanti in questo articolo.

Per passare opzioni della riga di comando al logger:
- Usare il nome completo dell'opzione e non la forma abbreviata, ad esempio verbosity anziché v.
- Omettere i trattini iniziali.
- Sostituire lo spazio che separa ogni opzione con un punto e virgola ;.
- Se l'opzione ha un valore, sostituire il separatore due punti tra tale opzione e il relativo valore con il segno di uguale =.
Ad esempio, -v:detailed --consoleLoggerParameters:ErrorsOnly diventerebbe verbosity=detailed;consoleLoggerParameters=ErrorsOnly.
--no-build

Non compila il progetto di test prima dell'esecuzione. Imposta anche in modo implicito il flag --no-restore.
--nologo

Esegue i test senza visualizzare il banner di Microsoft TestPlatform. Disponibile a partire da .NET Core 3.0 SDK.
--no-restore

Non esegue un ripristino implicito quando si esegue il comando.
-o|--output <OUTPUT_DIRECTORY>

Directory in cui trovare i file binari da eseguire. Se non specificata, il percorso predefinito è ./bin/<configuration>/<framework>/. Per i progetti con più framework di destinazione (tramite la proprietà TargetFrameworks), quando si specifica questa opzione è necessario definire anche --framework. dotnet test esegue sempre i test dalla directory di output. È possibile usare AppDomain.BaseDirectory per utilizzare le risorse di test nella directory di output.
- .NET 7.0.200 SDK e versioni successive
  
  Se si specifica l'opzione --output quando si esegue questo comando in una soluzione, l'interfaccia della riga di comando genererà un avviso (un errore nella versione 7.0.200) a causa della semantica non chiara del percorso di output. L'opzione --output non è consentita perché tutti gli output di tutti i progetti compilati verrebbero copiati nella directory specificata e questo non è compatibile con progetti con più destinazioni, né con progetti con versioni diverse di dipendenze dirette e transitive. Per altre informazioni, vedere Opzione --output a livello di soluzione non più valida per i comandi correlati alla compilazione.

--os <OS>

Specifica il sistema operativo di destinazione. Si tratta di una sintassi abbreviata per l'impostazione dell'identificatore di runtime (RID), in cui il valore fornito viene combinato con il RID predefinito. Ad esempio, in un computer win-x64, specificando --os linux si imposta il RID su linux-x64. Se si usa questa opzione, non usare l'opzione -r|--runtime. Disponibile a partire da .NET 6.

--results-directory <RESULTS_DIR>

Directory in cui verranno inseriti i risultati del test. Se la directory specificata non esiste, viene creata. Il valore predefinito è TestResults nella directory che contiene il file di progetto.

Nelle versioni di .NET SDK precedenti alla 7 è disponibile la forma breve -r.
-r|--runtime <RUNTIME_IDENTIFIER>

Runtime di destinazione per cui eseguire i test.

A partire da .NET SDK 7 è disponibile la forma breve -r.
-s|--settings <SETTINGS_FILE>

Il file .runsettings da usare per l'esecuzione dei test. L'elemento TargetPlatform (x86|x64) non ha alcun effetto per dotnet test. Per eseguire test destinati a piattaforme x86, installare la versione x86 di .NET Core. Per l'esecuzione dei test verrà usato il numero di bit dell'applicazione dotnet.exe presente nel percorso. Per ulteriori informazioni, vedi le seguenti risorse:
- Configurare unit test usando un file .runsettings.
- Configurare un agente di test
-t|--list-tests

Elenca i testi individuati invece di eseguirli.

-v|--verbosity <LEVEL>

Imposta il livello di dettaglio del comando. I valori consentiti sono q[uiet], m[inimal], n[ormal], d[etailed] e diag[nostic]. Il valore predefinito è minimal. Per ulteriori informazioni, vedere LoggerVerbosity.

args

Specifica argomenti aggiuntivi da passare all'adattatore. Per separare più argomenti usare uno spazio.

L'elenco di possibili argomenti dipende dal comportamento specificato:
- Quando si specifica un progetto, una soluzione o una directory oppure si omette questo argomento, la chiamata viene inoltrata a msbuild. In questo caso, gli argomenti disponibili sono illustrati nella documentazione di dotnet msbuild.
- Quando si specifica un file .dll o .exe, la chiamata viene inoltrata a vstest. In questo caso, gli argomenti disponibili sono illustrati nella documentazione di dotnet vstest.
Argomenti RunSettings

Gli argomenti RunSettings inline vengono passati come ultimi argomenti nella riga di comando dopo "-- " (si noti lo spazio dopo --). I RunSettings inline vengono specificati come coppie [name]=[value]. Per separare più coppie [name]=[value], viene usato uno spazio.

Esempio: dotnet test -- MSTest.DeploymentEnabled=false MSTest.MapInconclusiveToFailed=True

Per altre informazioni, vedere Passare argomenti RunSettings tramite la riga di comando.

Esempi

Eseguire i test nel progetto nella directory corrente:
```
dotnet test
```

Eseguire i test nel progetto test1:

dotnet test ~/projects/test1/test1.csproj

Eseguire i test usando l'assembly test1.dll:

dotnet test ~/projects/test1/bin/debug/test1.dll

Eseguire i test nel progetto nella directory corrente e generare un file dei risultati dei test in formato trx:
```
dotnet test --logger trx
```
Eseguire i test nel progetto nella directory corrente e generare un file di code coverage (dopo aver installato l'integrazione degli agenti di raccolta Coverlet):
```
dotnet test --collect:"XPlat Code Coverage"
```
Eseguire i test nel progetto nella directory corrente e generare un file di code coverage (solo Windows):
```
dotnet test --collect "Code Coverage"
```
Eseguire i test nel progetto nella directory corrente e registrare nella console con livello di dettaglio massimo:
```
dotnet test --logger "console;verbosity=detailed"
```
Eseguire i test nel progetto nella directory corrente e registrare con il logger trx in testResults.trx nella cartella TestResults:
```
dotnet test --logger "trx;logfilename=testResults.trx"
```
Poiché è specificato il nome del file di log, nel caso di un progetto con più destinazioni viene usato lo stesso nome per tutti i framework di destinazione. L'output per ogni framework di destinazione sovrascrive l'output dei framework di destinazione precedenti. Il file viene creato nella cartella TestResults all'interno della cartella del progetto di test, perché i percorsi relativi sono relativi a tale cartella. L'esempio seguente mostra come produrre un file separato per ogni framework di destinazione.
Eseguire i test nel progetto nella directory corrente e registrare con il logger trx in file all'interno della cartella TestResults, usando nomi di file univoci per ogni framework di destinazione:
```
dotnet test --logger:"trx;LogFilePrefix=testResults"
```
Eseguire i test nel progetto nella directory corrente e registrare con il logger html in testResults.html nella cartella TestResults:
```
dotnet test --logger "html;logfilename=testResults.html"
```
Eseguire i test nel progetto nella directory corrente e segnalare i test che erano in corso quando l'host di test si è arrestato in modo anomalo:
```
dotnet test --blame
```
Eseguire i test nel progetto test1, specificando l'argomento -bl (log binario) per msbuild:
```
dotnet test ~/projects/test1/test1.csproj -bl
```
Eseguire i test nel progetto test1, impostando la proprietà DefineConstants di MSBuild su DEV:
```
dotnet test ~/projects/test1/test1.csproj -p:DefineConstants="DEV"
```
Eseguire i test nel progetto test1, impostando la proprietà TestTfmsInParallel di MSBuild su false:
```
dotnet test ~/projects/test1/test1.csproj -p:TestTfmsInParallel=false
```

--filter <EXPRESSION>

<Expression> ha il formato <property><operator><value>[|&<Expression>].

<property> è un attributo di Test Case. La tabella seguente elenca le proprietà supportate da framework diffusi per unit test:

Framework di test	Proprietà supportate
MSTest	FullyQualifiedName Nome ClassName Priorità TestCategory
xUnit	FullyQualifiedName DisplayName Category
NUnit	FullyQualifiedName Nome Category Priorità

<operator> descrive la relazione tra la proprietà e il valore:

Operatore	Funzione
`=`	Corrispondenza esatta
`!=`	Corrispondenza non esatta
`~`	Contiene
`!~`	Non contiene

<value> è una stringa. Per tutte le ricerche non viene fatta distinzione tra maiuscole e minuscole.

Un'espressione senza <operator> viene considerata automaticamente come un'operazione contains sulla proprietà FullyQualifiedName. Ad esempio, dotnet test --filter xyz è uguale a dotnet test --filter FullyQualifiedName~xyz.

Le espressioni possono essere unite con operatori condizionali:

Operatore	Funzione
`\|`	OR
`&`	E

È possibile racchiudere le espressioni tra parentesi quando si usano gli operatori condizionali (ad esempio, (Name~TestMethod1) | (Name~TestMethod2)).

Per altre informazioni ed esempi sull'uso del filtro degli unit test selettivi, vedere Esecuzione di unit test selettivi.

Vedi anche

Frameworks and Targets (Framework e destinazioni)
Catalogo RID (Runtime Identifier) .NET
Passare argomenti RunSettings tramite la riga di comando