dotnet test
Cet article s’applique à : ✔️ .NET Core 3.1 et versions ultérieures
dotnet test
- Pilote de test .NET utilisée pour exécuter des tests unitaires.
dotnet test [<PROJECT> | <SOLUTION> | <DIRECTORY> | <DLL> | <EXE>]
[--test-adapter-path <ADAPTER_PATH>]
[-a|--arch <ARCHITECTURE>]
[--artifacts-path <ARTIFACTS_DIR>]
[--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
La commande dotnet test
est utilisée pour exécuter des tests unitaires dans une solution donnée. La dotnet test
commande génère la solution et exécute une application hôte de test pour chaque projet de test dans la solution à l’aide VSTest
de . L’hôte de test exécute les tests dans le projet donné à l’aide d’un framework de test (par exemple, MSTest, NUnit ou xUnit) et signale la réussite ou l’échec de chaque test. Si tous les tests réussissent, l’exécuteur de tests retourne 0 en tant que code de sortie. Sinon, si un test échoue, il retourne 1.
Notes
dotnet test
a été initialement conçu pour prendre en charge uniquement VSTest
les projets de test basés sur des données. Les versions récentes des frameworks de test ajoutent la prise en charge de Microsoft.Testing.Platform. Cette autre plateforme de test est plus légère et plus rapide que VSTest
et prend en charge dotnet test
avec différentes options de ligne de commande. Pour plus d’informations, consultez Microsoft.Testing.Platform.
Pour les projets multi-ciblés, les tests sont exécutés pour chaque framework ciblé. L’hôte de test et le framework de test unitaire sont empaquetés sous forme de packages NuGet et sont restaurés comme des dépendances ordinaires du projet. À compter du Kit de développement logiciel (SDK) .NET 9, ces tests sont exécutés en parallèle par défaut. Pour désactiver l’exécution parallèle, définissez la TestTfmsInParallel
propriété MSBuild sur false
. Pour plus d’informations, consultez Exécuter des tests en parallèle et l’exemple de ligne de commande plus loin dans cet article.
Les projets de test spécifient l’application Test Runner à l’aide d’un élément <PackageReference>
ordinaire, comme indiqué dans l’exemple de fichier projet suivant :
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.10.0" />
<PackageReference Include="xunit" Version="2.8.1" />
<PackageReference Include="xunit.runner.visualstudio" Version="2.8.1" />
</ItemGroup>
</Project>
Où Microsoft.NET.Test.Sdk
désigne l’hôte de test et xunit
le framework de test. Et xunit.runner.visualstudio
désigne un adaptateur de test, qui permet au framework xUnit de travailler avec l’hôte de test.
Vous n’avez pas besoin d’exécuter dotnet restore
, car il est exécuté implicitement par toutes les commandes qui nécessitent une restauration pour se produire, comme dotnet new
, dotnet build
, dotnet run
, dotnet test
, dotnet publish
et dotnet pack
. Pour désactiver la restauration implicite, utilisez l’option --no-restore
.
La commande dotnet restore
est toujours utile dans certains scénarios où la restauration explicite est logique, comme les builds d’intégration continue dans Azure DevOps Services ou dans les systèmes de génération qui doivent contrôler explicitement le moment où la restauration se produit.
Pour plus d’informations sur la gestion des flux NuGet, consultez la documentation dotnet restore
.
Lorsque vous exécutez cette commande, elle lance en arrière-plan un téléchargement asynchrone des manifestes publicitaires des charges de travail. Si le téléchargement est toujours en cours lorsque cette commande se termine, celui-ci est arrêté. Pour plus d’informations, consultez Manifestes publicitaires.
PROJECT | SOLUTION | DIRECTORY | DLL | EXE
- Chemin du projet de test.
- Chemin d’accès à la solution.
- Chemin d’accès à un répertoire qui contient un projet ou une solution.
- Chemin d’accès à un fichier .dll de projet de test.
- Chemin d’accès à un fichier .exe de projet de test.
S’il n’est pas spécifié, l’effet est identique à l’utilisation de l’argument
DIRECTORY
pour spécifier le répertoire actif.
Avertissement
Changements cassants dans les options :
- À partir de .NET 7 : basculer
-a
vers l’alias--arch
au lieu de--test-adapter-path
- À partir de .NET 7 : basculer
-r
vers l’alias--runtime
au lieu de--results-directory
Avertissement
Lorsque vous utilisez Microsoft.Testing.Platform
, reportez-vous à l’intégration de test dotnet pour les options prises en charge. En règle générale, chaque option non liée aux tests est prise en charge, tandis que chaque option liée aux tests n’est pas prise en charge telle qu’elle est.
--test-adapter-path <ADAPTER_PATH>
Chemin d’accès à un répertoire dans lequel des adaptateurs de test supplémentaires doivent être recherchés. Seuls les fichiers .dll avec suffixe
.TestAdapter.dll
sont inspectés. S’il n’est pas spécifié, la recherche est effectuée dans le répertoire du fichier .dll de test.-a
abrégé disponible dans les versions du kit SDK .NET antérieures à la version 7.
--arch <ARCHITECTURE>
Spécifie l’architecture cible. Il s’agit d’une syntaxe abrégée pour définir l’identificateur d’exécution (RID), où la valeur fournie est combinée avec le RID par défaut. Par exemple, sur une machine
win-x64
, la spécification de--arch x86
définit le RID surwin-x86
. Si vous utilisez cette option, n’utilisez pas l’option-r|--runtime
. Disponible depuis .NET 6 Preview 7.
--artifacts-path <ARTIFACTS_DIR>
Tous les fichiers de sortie de build de la commande exécutée vont dans les sous-dossiers sous le chemin spécifié, séparés par projet. Pour plus d’informations, consultez Disposition de sortie d’artefacts. Disponible depuis le Kit de développement logiciel (SDK) .NET 8.
--blame
Exécute les tests en mode responsable. Cette option permet d’isoler les tests responsables des incidents sur l’hôte de test. Lorsqu’un incident est détecté, elle crée dans
TestResults/<Guid>/<Guid>_Sequence.xml
un fichier de séquence qui enregistre l’ordre des tests exécutés avant l’incident.Cette option ne crée pas d’image mémoire et n’a aucune utilité lorsque le test est suspendu.
--blame-crash
(Disponible à partir du kit SDK .NET 5.0)Exécute les tests en mode blame (responsabilité) et collecte une image mémoire lorsque l’hôte de test se ferme de manière inattendue. Cette option dépend de la version de .NET utilisée, du type d’erreur et du système d’exploitation.
Pour les exceptions liées au code managé, une image mémoire est automatiquement collectée sur .NET 5.0 et versions ultérieures. Elle génère une image mémoire pour l’hôte de test ou tout processus enfant qui s’est également exécuté sur .NET 5.0 avant d’être bloqué. Les incidents liés au code natif ne génèrent pas d’image mémoire. Cette option fonctionne sous Windows, macOS et Linux.
Les images mémoire liées au code natif, ou à l’utilisation de .NET Core 3.1 ou versions antérieures, ne peuvent être collectées que sous Windows, à l’aide de Procdump. Un répertoire contenant procdump.exe et procdump64.exe doit figurer dans la variable d’environnement PATH ou PROCDUMP_PATH. Téléchargez les outils. Implique
--blame
.Pour collecter une image mémoire à partir d’une application native exécutée sur .NET 5.0 ou version ultérieure, l’utilisation de Procdump peut être forcée en définissant la variable d’environnement
VSTEST_DUMP_FORCEPROCDUMP
sur1
.--blame-crash-dump-type <DUMP_TYPE>
(Disponible à partir du kit SDK .NET 5.0)Type d’image mémoire à collecter. Les types d’image mémoire pris en charge sont
full
(par défaut) etmini
. Implique--blame-crash
.--blame-crash-collect-always
(Disponible à partir du kit SDK .NET 5.0)Collecte une image mémoire sur les sorties attendues et inattendues de l’hôte de test.
--blame-hang
(Disponible à partir du kit SDK .NET 5.0)Exécute les tests en mode blame (responsabilité) et collecte une image mémoire de blocage lorsque le test dépasse le délai d’expiration spécifié.
--blame-hang-dump-type <DUMP_TYPE>
(Disponible à partir du kit SDK .NET 5.0)Type d’image mémoire à collecter. Il doit s’agir de
full
,mini
ounone
. Lorsquenone
est spécifié, l’hôte de test est arrêté au terme du délai d’expiration, mais aucune image mémoire n’est collectée. Implique--blame-hang
.--blame-hang-timeout <TIMESPAN>
(Disponible à partir du kit SDK .NET 5.0)Délai d’expiration par test, après lequel une image mémoire de blocage est déclenchée et le processus de l’hôte de test et tous ses processus enfants sont vidés et arrêtés. La valeur du délai d’expiration est spécifiée dans l’un des formats suivants :
- 1,5h, 1,5heure, 1,5heures
- 90m, 90min, 90minutes, 90minutes
- 5400s, 5400sec, 5400secondes, 5400secondes
- 5400000ms, 5400000mil, 5400000milliseconde, 5400000millisecondes
Lorsqu’aucune unité n’est utilisée (par exemple, 5400000), la valeur est supposée être en millisecondes. Lorsqu’il est utilisé avec des tests pilotés par les données, le comportement du délai d’expiration dépend de l’adaptateur de test utilisé. Pour xUnit, NUnit. et MSTest 2.2.4+, le délai d’expiration est renouvelé après chaque cas de test. Pour les versions antérieures à la version 2.2.4 de MSTest, le délai d’expiration est utilisé pour tous les cas de test. Cette option est prise en charge sous Windows avec
netcoreapp2.1
et versions ultérieures, sous Linux avecnetcoreapp3.1
et versions ultérieures, et sous macOS avecnet5.0
ou version ultérieure. Implique--blame
et--blame-hang
.
-c|--configuration <CONFIGURATION>
Définit la configuration de build. Pour la plupart des projets, la valeur par défaut est
Debug
, mais vous pouvez modifier les paramètres de configuration de build de votre projet.
--collect <DATA_COLLECTOR_NAME>
Active le collecteur de données pour la série de tests. Pour plus d’informations, consultez Monitor and analyze test run (Surveiller et analyser la série de tests).
Par exemple, vous pouvez collecter la couverture du code à l’aide de l’option
--collect "Code Coverage"
. Pour plus d’informations, consultez Utiliser la couverture du code, Personnaliser l’analyse de la couverture du code et Problème GitHub dotnet/docs#34479.Pour collecter la couverture du code, vous pouvez également utiliser Coverlet à l’aide de l’option
--collect "XPlat Code Coverage"
.-d|--diag <LOG_FILE>
Active le mode diagnostic pour la plateforme de test et écrit les messages de diagnostic dans le fichier spécifié ainsi que dans les fichiers adjacents. Le processus qui journalise les messages détermine les fichiers à créer, par exemple
*.host_<date>.txt
pour le journal de l’hôte de test et*.datacollector_<date>.txt
pour le journal du collecteur de données.-e|--environment <NAME="VALUE">
Définit la valeur d’une variable d’environnement. Crée la variable si elle n’existe pas, la remplace si elle existe. L’utilisation de cette option force l’exécution des tests dans un processus isolé. L’option peut être spécifiée plusieurs fois pour fournir plusieurs variables.
-f|--framework <FRAMEWORK>
Moniker de framework cible (TFM) du framework cible pour lequel les tests doivent être exécutés. Le framework cible doit être spécifié dans le fichier projet.
--filter <EXPRESSION>
Filtre les tests dans le projet en cours à l’aide de l’expression donnée. Seuls les tests qui correspondent à l’expression de filtre sont exécutés. Pour plus de détails, consultez la section Détails de l’option de filtre. Pour plus d’informations et pour obtenir des exemples sur la façon d’utiliser le filtrage de test unitaire sélectif, consultez Exécution de tests unitaires sélectifs.
-?|-h|--help
Imprime une description de l’utilisation de la commande.
--interactive
Permet à la commande de s’arrêter et d’attendre une action ou une entrée utilisateur. Par exemple, pour effectuer une authentification. Option disponible à partir du kit SDK .NET Core 3.0.
-l|--logger <LOGGER>
Spécifie un enregistreur d’événements pour les résultats des tests, et éventuellement des commutateurs pour l’enregistreur d’événements. Spécifiez ce paramètre plusieurs fois pour activer plusieurs enregistreurs d’événements. Pour plus d’informations, consultez Rapports sur les résultats des tests, Commutateurs pour les enregistreurs d’événements ainsi que les exemples présentés plus loin dans cet article.
Pour transmettre des commutateurs de ligne de commande à l’enregistreur d’événements :
- Utilisez le nom complet du commutateur, et non le formulaire abrégé (par exemple,
verbosity
au lieu dev
). - Omettez les tirets de début.
- Remplacez l’espace séparant chaque commutateur par un point-virgule
;
. - Si le commutateur possède une valeur, remplacez le séparateur deux-points entre ce commutateur et sa valeur par le signe égal
=
.
Par exemple,
-v:detailed --consoleLoggerParameters:ErrorsOnly
deviendraitverbosity=detailed;consoleLoggerParameters=ErrorsOnly
.- Utilisez le nom complet du commutateur, et non le formulaire abrégé (par exemple,
--no-build
Ne génère pas le projet de test avant son exécution. L’indicateur
--no-restore
est également défini implicitement.--nologo
Exécutez les tests sans afficher la bannière Microsoft TestPlatform. Option disponible à partir du kit SDK .NET Core 3.0.
--no-restore
N’effectue pas de restauration implicite à l’exécution de la commande.
-o|--output <OUTPUT_DIRECTORY>
Répertoire dans lequel rechercher les binaires à exécuter. S’il n’est pas spécifié, le chemin d'accès par défaut est
./bin/<configuration>/<framework>/
. Pour les projets comportant plusieurs frameworks cibles (via la propriétéTargetFrameworks
), vous devez également définir--framework
lorsque vous spécifiez cette option.dotnet test
exécute toujours les tests à partir du répertoire de sortie. Vous pouvez utiliser AppDomain.BaseDirectory pour utiliser les ressources de test du répertoire de sortie.Kit SDK .NET 7.0.200 et versions ultérieures
Si vous spécifiez l’option
--output
lors de l’exécution de cette commande sur une solution, l’interface CLI émet un avertissement (une erreur dans la version 7.0.200) en raison du manque de clarté de la sémantique du chemin de sortie. L’option--output
n’est pas autorisée, car toutes les sorties de tous les projets générés seraient copiées dans le répertoire spécifié. Or, cette configuration n’est compatible ni avec les projets à plusieurs cibles, ni avec les projets présentant différentes versions de dépendances directes et transitives. Pour plus d’informations, consultez Option--output
au niveau de la solution non valide pour les commandes liées à la build.
--os <OS>
Spécifie le système d’exploitation cible. Il s’agit d’une syntaxe abrégée pour définir l’identificateur d’exécution (RID), où la valeur fournie est combinée avec le RID par défaut. Par exemple, sur une machine
win-x64
, la spécification de--os linux
définit le RID surlinux-x64
. Si vous utilisez cette option, n’utilisez pas l’option-r|--runtime
. Disponible à partir de .NET 6.
--results-directory <RESULTS_DIR>
Répertoire où les résultats de test doivent être placés. Si le répertoire spécifié n’existe pas, il est créé. La valeur par défaut est
TestResults
dans le répertoire qui contient le fichier projet.-r
abrégé disponible dans les versions antérieures à la version 7 du kit SDK .NET.-r|--runtime <RUNTIME_IDENTIFIER>
Runtime cible à tester.
-r
abrégé disponible à partir du kit SDK .NET 7.-s|--settings <SETTINGS_FILE>
Fichier
.runsettings
à utiliser pour exécuter les tests. L’élémentTargetPlatform
(x86|x64) n’a aucun effet pourdotnet test
. Pour exécuter des tests qui ciblent x86, installez la version x86 de .NET Core. Le nombre de bits du fichier dotnet.exe situé sur le chemin d’accès est celui qui sera utilisé pour exécuter les tests. Pour plus d’informations, consultez les ressources suivantes :-t|--list-tests
Listez les tests découverts au lieu d’exécuter les tests.
-v|--verbosity <LEVEL>
Définit le niveau de détail de la commande. Les valeurs autorisées sont
q[uiet]
,m[inimal]
,n[ormal]
,d[etailed]
etdiag[nostic]
. La valeur par défaut estminimal
. Pour plus d'informations, consultez LoggerVerbosity.
args
Spécifie des arguments supplémentaires à passer à l’adaptateur. Utilisez un espace pour séparer plusieurs arguments.
La liste des arguments possibles dépend du comportement spécifié :
- Lorsque vous spécifiez un projet, une solution ou un répertoire, ou si vous omettez cet argument, l’appel est transféré vers
msbuild
. Dans ce cas, les arguments disponibles se trouvent dans la documentation de dotnet msbuild. - Lorsque vous spécifiez un fichier .dll ou .exe, l’appel est transféré vers
vstest
. Dans ce cas, les arguments disponibles se trouvent dans la documentation de dotnet vstest.
- Lorsque vous spécifiez un projet, une solution ou un répertoire, ou si vous omettez cet argument, l’appel est transféré vers
Arguments
RunSettings
Les arguments RunSettings
inlined sont transmis en tant que derniers arguments sur la ligne de commande, après « -- » (attention à l’espace après --). Les arguments RunSettings
inlined sont spécifiés sous forme de paires [name]=[value]
. Un espace est utilisé pour séparer plusieurs paires [name]=[value]
.
Exemple : dotnet test -- MSTest.DeploymentEnabled=false MSTest.MapInconclusiveToFailed=True
Pour plus d’informations, consultez Transmettre des arguments RunSettings via la ligne de commande.
Exécutez les tests du projet dans le répertoire actif :
dotnet test
Exécuter les tests dans le projet
test1
:dotnet test ~/projects/test1/test1.csproj
Exécutez les tests à l’aide de l’assembly
test1.dll
:dotnet test ~/projects/test1/bin/debug/test1.dll
Exécutez les tests du projet dans le répertoire actif et générez un fichier de résultats de tests au format trx :
dotnet test --logger trx
Exécutez les tests du projet dans le répertoire actif et générez un fichier de couverture du code (après l’installation des collecteurs Coverlet) :
dotnet test --collect:"XPlat Code Coverage"
Exécutez les tests du projet dans le répertoire actif et générez un fichier de couverture du code (Windows uniquement) :
dotnet test --collect "Code Coverage"
Exécutez les tests du projet dans le répertoire actif et connectez-vous à la console avec des informations précises :
dotnet test --logger "console;verbosity=detailed"
Exécutez les tests du projet dans le répertoire actif et utilisez l’enregistreur d’événements trx pour vous connecter à testResults.trx dans le dossier TestResults :
dotnet test --logger "trx;logfilename=testResults.trx"
Comme le nom du fichier journal est spécifié, le même nom est utilisé pour chaque framework cible dans le cas d’un projet multi-ciblé. La sortie de chaque framework cible remplace la sortie des précédents. Le fichier est créé dans le dossier TestResults du dossier du projet de test, car les chemins d’accès sont relatifs à ce dossier. L’exemple suivant montre comment produire un fichier distinct pour chaque framework cible.
Exécutez les tests du projet dans le répertoire actif et utilisez l’enregistreur d’événements trx pour vous connecter aux fichiers du dossier TestResults, avec des noms de fichier uniques pour chaque framework cible :
dotnet test --logger:"trx;LogFilePrefix=testResults"
Exécutez les tests du projet dans le répertoire actif et utilisez l’enregistreur d’événements html pour vous connecter à testResults.html dans le dossier TestResults :
dotnet test --logger "html;logfilename=testResults.html"
Exécutez les tests du projet dans le répertoire actif et signalez les tests qui étaient en cours lorsque l’hôte de test s’est bloqué :
dotnet test --blame
Exécutez les tests du projet
test1
, en fournissant l’argument-bl
(journal binaire) àmsbuild
:dotnet test ~/projects/test1/test1.csproj -bl
Exécutez les tests du projet
test1
, en définissant la propriété MSBuildDefineConstants
surDEV
:dotnet test ~/projects/test1/test1.csproj -p:DefineConstants="DEV"
Exécutez les tests du projet
test1
, en définissant la propriété MSBuildTestTfmsInParallel
surfalse
:dotnet test ~/projects/test1/test1.csproj -p:TestTfmsInParallel=false
--filter <EXPRESSION>
<Expression>
est au format <property><operator><value>[|&<Expression>]
.
<property>
est un attribut de Test Case
. Les propriétés suivantes sont prises en charge par les principales infrastructures de tests unitaires :
Framework de test | Propriétés prises en charge |
---|---|
MSTest |
|
xUnit |
|
NUnit |
|
La section <operator>
décrit la relation entre la propriété et la valeur :
Opérateur | Fonction |
---|---|
= |
Concordance exacte |
!= |
Pas de correspondance exacte |
~ |
Contient |
!~ |
Ne contient pas |
<value>
est une chaîne. Toutes les recherches respectent la casse.
Une expression sans <operator>
est automatiquement considérée comme contains
sur la propriété FullyQualifiedName
(par exemple, dotnet test --filter xyz
est identique à dotnet test --filter FullyQualifiedName~xyz
).
Les expressions peuvent être associées à des opérateurs conditionnels :
Opérateur | Fonction |
---|---|
| |
OU |
& |
AND |
Vous pouvez mettre des expressions entre parenthèses quand vous utilisez des opérateurs conditionnels (par exemple, (Name~TestMethod1) | (Name~TestMethod2)
).
Pour plus d’informations et pour obtenir des exemples sur la façon d’utiliser le filtrage de test unitaire sélectif, consultez Exécution de tests unitaires sélectifs.
Commentaires sur .NET
.NET est un projet open source. Sélectionnez un lien pour fournir des commentaires :