dotnet test

  • Article

Cet article s’applique à : ✔️ .NET Core 3.1 et versions ultérieures

Nom

dotnet test - Pilote de test .NET utilisée pour exécuter des tests unitaires.

Synopsis

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

Description

La commande dotnet test est utilisée pour exécuter des tests unitaires dans une solution donnée. La commande dotnet test génère la solution et exécute une application hôte de test pour chaque projet de test de la solution. 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.

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

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.

Restauration implicite

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.

Téléchargement de manifestes de charge de travail

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.

Arguments

  • 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.

Options

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

  • --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 sur win-x86. Si vous utilisez cette option, n’utilisez pas l’option -r|--runtime. Disponible depuis .NET 6 Preview 7.

  • --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 sur 1.

  • --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) et mini. 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 ou none. Lorsque none 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 avec netcoreapp3.1 et versions ultérieures, et sous macOS avec net5.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 de v).
    • 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 deviendrait verbosity=detailed;consoleLoggerParameters=ErrorsOnly.

  • --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 sur linux-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ément TargetPlatform (x86|x64) n’a aucun effet pour dotnet 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] et diag[nostic]. La valeur par défaut est minimal. 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.

  • 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.

Exemples

  • 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é MSBuild DefineConstants sur DEV :

    dotnet test ~/projects/test1/test1.csproj -p:DefineConstants="DEV"

  • Exécutez les tests du projet test1, en définissant la propriété MSBuild TestTfmsInParallel sur false :

    dotnet test ~/projects/test1/test1.csproj -p:TestTfmsInParallel=false

Détails de l’option de filtre

--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
  • FullyQualifiedName
  • Nom
  • ClassName
  • Priorité
  • TestCategory
xUnit
  • FullyQualifiedName
  • DisplayName
  • Category
NUnit
  • FullyQualifiedName
  • Nom
  • Catégorie
  • Priority

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.

Voir aussi