Partager via

Attributs MSTest

MSTest utilise des attributs personnalisés pour identifier et personnaliser les tests.

Pour fournir une vue d’ensemble plus claire de l’infrastructure de test, cette section organise les membres de l’espace de noms Microsoft.VisualStudio.TestTools.UnitTesting en groupes de fonctionnalités connexes.

Remarque

Les attributs, dont les noms se terminent par « Attribute », peuvent être utilisés avec ou sans « Attribute » à la fin. Les attributs ayant un constructeur sans paramètre peuvent être écrits avec ou sans parenthèses. Les exemples de code suivants fonctionnent de façon identique :

[TestClass()]

[TestClassAttribute()]

[TestClass]

[TestClassAttribute]

Attributs utilisés pour identifier les classes et méthodes de test

Chaque classe de test doit avoir l’attribut TestClass, et chaque méthode de test doit avoir l’attribut TestMethod.

TestClassAttribute

L’attribut TestClass marque une classe qui contient des tests et, éventuellement, des méthodes d’initialisation ou de nettoyage.

Cet attribut peut être étendu pour modifier ou étendre le comportement par défaut.

Exemple :

[TestClass]
public class MyTestClass
{
}

TestMethodAttribute

L’attribut TestMethod est utilisé à l’intérieur d’une TestClass pour définir la méthode de test réelle à exécuter.

La méthode doit être une méthode d’instance public définie comme void, Task ou ValueTask (à partir de MSTest v3.3). Elle peut éventuellement être async, mais elle ne doit pas être async void.

La méthode doit avoir zéro paramètre, sauf si elle est marquée avec l’attribut DataRow , l’attribut DynamicData ou un attribut similaire qui fournit des données de cas de test à la méthode de test.

Prenez l’exemple de classe de test suivant :

[TestClass]
public class MyTestClass
{
    [TestMethod]
    public void TestMethod()
    {
    }
}

Attributs utilisés pour les tests pilotés par des données

Utilisez les éléments suivants pour configurer des tests pilotés par les données. Pour plus d’informations, consultez Créer un test unitaire piloté par les données et Utiliser un fichier de configuration pour définir une source de données.

Conseil / Astuce

MSTest ne prend pas en charge en mode natif le test combinatorial, mais vous pouvez ajouter cette fonctionnalité à l’aide du package NuGet Combinatorial.MSTest open source. Il est géré activement par la communauté et disponible sur GitHub. Ce package n’est pas géré par Microsoft.

DataRowAttribute

L’attribut DataRow vous permet d’exécuter la même méthode de test avec plusieurs entrées différentes. Il peut apparaître une ou plusieurs fois sur une méthode de test. Elle doit être combinée avec l’attribut TestMethod .

Le nombre et les types d’arguments doivent correspondre exactement à la signature de la méthode de test. Prenons l’exemple suivant d’une classe de test valide illustrant l’utilisation DataRowAttribute avec des arguments inline qui s’alignent sur les paramètres de méthode de test :

[TestClass]
public class TestClass
{
    [TestMethod]
    [DataRow(1, "message", true, 2.0)]
    public void TestMethod1(int i, string s, bool b, float f)
    {
        // Omitted for brevity.
    }

    [TestMethod]
    [DataRow(new string[] { "line1", "line2" })]
    public void TestMethod2(string[] lines)
    {
        // Omitted for brevity.
    }

    [TestMethod]
    [DataRow(null)]
    public void TestMethod3(object o)
    {
        // Omitted for brevity.
    }

    [TestMethod]
    [DataRow(new string[] { "line1", "line2" }, new string[] { "line1.", "line2." })]
    public void TestMethod4(string[] input, string[] expectedOutput)
    {
        // Omitted for brevity.
    }
}

Remarque

Vous pouvez également utiliser la fonctionnalité params pour capturer plusieurs entrées de DataRowAttribute.

[TestClass]
public class TestClass
{
    [TestMethod]
    [DataRow(1, 2, 3, 4)]
    public void TestMethod(params int[] values) {}
}

Exemples de combinaisons non valides :

[TestClass]
public class TestClass
{
    [TestMethod]
    [DataRow(1, 2)] // Not valid, we are passing 2 inline data but signature expects 1
    public void TestMethod1(int i) {}

    [TestMethod]
    [DataRow(1)] // Not valid, we are passing 1 inline data but signature expects 2
    public void TestMethod2(int i, int j) {}

    [TestMethod]
    [DataRow(1)] // Not valid, count matches but types do not match
    public void TestMethod3(string s) {}
}

Remarque

À compter de MSTest v3, lorsque vous souhaitez passer exactement deux tableaux, vous n’avez plus besoin d’encapsuler le deuxième tableau dans un tableau d’objets. Avant :[DataRow(new string[] { "a" }, new object[] { new string[] { "b" } })]À partir de la version 3 :[DataRow(new string[] { "a" }, new string[] { "b" })]

Vous pouvez modifier le nom d’affichage utilisé dans Visual Studio et les enregistreurs d’événements pour chaque instance de DataRowAttribute en définissant la propriété DisplayName.

[TestClass]
public class TestClass
{
    [TestMethod]
    [DataRow(1, 2, DisplayName = "Functional Case FC100.1")]
    public void TestMethod(int i, int j) {}
}

Vous pouvez également créer votre propre attribut spécialisé DataRow en héritant de DataRowAttribute.

[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
public class MyCustomDataRowAttribute : DataRowAttribute
{
}

[TestClass]
public class TestClass
{
    [TestMethod]
    [MyCustomDataRow(1)]
    public void TestMethod(int i) {}
}

Attributs utilisés pour fournir l’initialisation et les nettoyages

Vous pouvez extraire la configuration et le nettoyage communs à plusieurs tests dans une méthode distincte, la marquer avec l’un des attributs listés ci-dessous et l’exécuter au moment approprié, par exemple avant chaque test. Pour plus d’informations, consultez Anatomie d’un test unitaire.

Niveau assembly

L’attribut AssemblyInitialize est appelé juste après le chargement de votre assembly et l’attribut AssemblyCleanup est appelé juste avant que votre assembly ne soit déchargé.

Les méthodes marquées avec ces attributs doivent être définies comme static voidou static Taskstatic ValueTask (à partir de MSTest v3.3), dans une classe marquée avec TestClassAttribute, et s’affichent une seule fois. La partie Initialize nécessite un paramètre de type TestContext et le Cleanup n’a aucun paramètre, ou à partir de MSTest 3.8 peut avoir un paramètre de type TestContext.

[TestClass]
public class MyTestClass
{
    [AssemblyInitialize]
    public static void AssemblyInitialize(TestContext testContext)
    {
    }

    [AssemblyCleanup]
    public static void AssemblyCleanup() // Starting with MSTest 3.8, it can be AssemblyCleanup(TestContext testContext)
    {
    }
}

Niveau classe

L’attribut ClassInitialize est appelé juste avant le chargement de votre classe (mais après le constructeur statique) et classCleanup est appelé juste après le déchargement de votre classe.

Importante

Par défaut, ClassCleanupAttribute sera déclenché après le dernier test de l’assembly (de la même façon que AssemblyCleanupAttribute). Vous pouvez modifier ce comportement en définissant l’attribut CleanupBehavior . Vous pouvez également définir ce comportement globalement pour l’assembly à l’aide de l’attribut d’assembly ClassCleanupExecutionAttribute.

Il est également possible de contrôler le comportement d’héritage : uniquement pour la classe actuelle à l’aide InheritanceBehavior.None, ou pour toutes les classes dérivées à l’aide InheritanceBehavior.BeforeEachDerivedClassde .

Les méthodes marquées avec ces attributs doivent être définies comme static void, static Task ou static ValueTask (à partir de MSTest v3.3), dans TestClass, et n’apparaître qu’une seule fois. La partie Initialize nécessite un paramètre de type TestContext et le Cleanup n’a aucun paramètre, ou à partir de MSTest 3.8 peut avoir un paramètre de type TestContext.

[TestClass]
public class MyTestClass
{
    [ClassInitialize]
    public static void ClassInitialize(TestContext testContext)
    {
    }

    [ClassCleanup]
    public static void ClassCleanup() // Starting with MSTest 3.8, it can be ClassCleanup(TestContext testContext)
    {
    }
}

Niveau test

L’attribut TestInitialize est appelé juste avant le démarrage de votre test et testCleanup est appelé juste après la fin de votre test.

TestInitializeAttribute est similaire au constructeur de classe, mais convient généralement mieux aux initialisations longues ou asynchrones. Le TestInitializeAttribute est toujours appelé après le constructeur et est appelé pour chaque test (y compris chaque entrée de tests pilotés par les données).

TestCleanupAttribute est similaire à la classe Dispose (ou DisposeAsync), mais convient généralement mieux aux nettoyages longs ou asynchrones. Le TestCleanupAttribute est toujours appelé juste avant le DisposeAsync/Dispose, et il est appelé pour chaque test (y compris chaque entrée des tests pilotés par les données).

Les méthodes marquées avec ces attributs doivent être définies comme void, Task ou ValueTask (à partir de MSTest v3.3), dans TestClass, être sans paramètre et apparaître une ou plusieurs fois.

[TestClass]
public class MyTestClass
{
    [TestInitialize]
    public void TestInitialize()
    {
    }

    [TestCleanup]
    public void TestCleanup()
    {
    }
}

Attributs utilisés pour contrôler l’exécution de tests

Vous pouvez utiliser les attributs suivants pour modifier la façon dont les tests sont exécutés.

TimeoutAttribute

Vous pouvez utiliser l’attribut Timeout pour spécifier la durée maximale en millisecondes pendant laquelle une méthode de test est autorisée à s’exécuter. Si la méthode de test s’exécute plus longtemps que la durée spécifiée, le test est abandonné et marqué comme ayant échoué.

Vous pouvez appliquer cet attribut à n’importe quelle méthode de test ou de fixture (méthodes d’initialisation et de nettoyage). Vous pouvez également spécifier le délai d’expiration globalement pour toutes les méthodes de test ou de fixture de test en utilisant les propriétés de délai d’expiration du fichier runsettings.

Remarque

La précision du délai d’expiration n’est pas garantie. Le test sera abandonné une fois l’heure spécifiée passée, mais l’étape peut prendre plus de temps avant l’annulation de l’étape.

Lorsque vous utilisez la fonctionnalité de délai d’expiration, une tâche/un thread distinct est créé pour exécuter la méthode de test. La tâche/le thread principal est responsable du monitoring du délai d’expiration et de la suppression de l’observateur de la tâche/du thread de la méthode si le délai d’expiration est atteint.

À compter de MSTest 3.6, vous pouvez spécifier la propriété CooperativeCancellation sur l’attribut (ou globalement via runsettings) pour activer l’annulation coopérative. Dans ce mode, la méthode est chargée de vérifier le jeton d’annulation et d’abandonner le test en cas de signalement, comme dans une méthode async classique. Ce mode est plus performant et permet un contrôle plus précis du processus d’annulation. Ce mode peut être appliqué aux méthodes asynchrones et synchrones.

STATestClassAttribute

Lorsqu’il est appliqué à une classe de test, l’attribut STATestClass indique que toutes les méthodes de test, ainsi que les méthodes [ClassInitialize] et [ClassCleanup], doivent être exécutées dans un modèle d’appartement à un seul thread (STA). Cet attribut est utile lorsque les méthodes de test interagissent avec des objets COM qui nécessitent STA.

Remarque

Ceci n'est possible que sous Windows et dans les versions 3.6 et ultérieures.

STATestMethodAttribute

Lorsqu’elle est appliquée à une méthode de test, l’attribut STATestMethod indique que la méthode de test doit être exécutée dans un appartement à thread unique (STA). Cet attribut est utile lorsque la méthode de test interagit avec des objets COM qui nécessitent STA.

Remarque

Ceci n'est possible que sous Windows et dans les versions 3.6 et ultérieures.

ParallelizeAttribute

Par défaut, MSTest exécute des tests dans un ordre séquentiel. L’attribut paralléliser au niveau de l’assembly peut être utilisé pour exécuter des tests en parallèle. Vous pouvez spécifier si le parallélisme doit être au niveau de la classe (plusieurs classes peuvent être exécutées en parallèle, mais les tests d’une classe donnée sont exécutés séquentiellement) ou au niveau de la méthode.

Vous pouvez également spécifier le nombre maximal de threads à utiliser pour l’exécution parallèle. Une valeur de 0 (valeur par défaut) signifie que le nombre de threads est égal au nombre de processeurs logiques sur l’ordinateur.

Vous pouvez également spécifier le parallélisme via les propriétés de parallélisation du fichier runsettings.

DoNotParallelizeAttribute

Vous pouvez utiliser l’attribut DoNotParallelize pour empêcher l’exécution parallèle de tests dans un assembly donné. Vous pouvez appliquer cet attribut au niveau de l’assembly, au niveau de la classe ou au niveau de la méthode.

Remarque

Par défaut, MSTest exécute des tests dans l’ordre séquentiel. Vous devez donc utiliser cet attribut uniquement si vous avez appliqué l’attribut Parallelize au niveau de l’assembly.

RetryAttribute

L’attribut Retry a été introduit dans MSTest 3.8. Cet attribut entraîne la nouvelle tentative de la méthode de test lorsqu’elle échoue ou expire. Il vous permet de spécifier le nombre maximal de tentatives de réessai, le délai entre les réessais et un type de recul du délai, qui peut être constant ou exponentiel.

RetryAttribute Une seule est censée être présente sur une méthode de test et RetryAttribute ne peut pas être utilisée sur les méthodes qui ne sont pas marquées avec TestMethod.

Remarque

RetryAttribute dérive d’un RetryBaseAttributeabstrait. Vous pouvez également créer vos propres stratégies de réessai si le RetryAttribute intégré ne correspond pas à vos besoins.

Attributs d’utilitaires

DeploymentItemAttribute

L’attribut DeploymentItem est utilisé pour copier des fichiers ou des dossiers spécifiés en tant qu’éléments de déploiement dans le répertoire de déploiement (sans ajouter de chemin de sortie personnalisé, les fichiers copiés se trouvent dans TestResults le dossier du projet). Le répertoire de déploiement regroupe tous les éléments de déploiement ainsi que la DLL du projet de test.

Il peut être utilisé sur les classes de test (classes marquées avec l’attribut TestClass ) ou sur les méthodes de test (méthodes marquées avec l’attribut TestMethod ).

Les utilisateurs peuvent avoir plusieurs instances de l’attribut pour spécifier plusieurs éléments.

Et ici, vous pouvez voir ses constructeurs.

Exemple

[TestClass]
[DeploymentItem(@"C:\classLevelDepItem.xml")]   // Copy file using some absolute path
public class UnitTest1
{
    [TestMethod]
    [DeploymentItem(@"..\..\methodLevelDepItem1.xml")]   // Copy file using a relative path from the dll output location
    [DeploymentItem(@"C:\DataFiles\methodLevelDepItem2.xml", "SampleDataFiles")]   // File will be added under a SampleDataFiles in the deployment directory
    public void TestMethod1()
    {
        string textFromFile = File.ReadAllText("classLevelDepItem.xml");
    }
}

Avertissement

Nous vous déconseillons d’utiliser cet attribut pour copier des fichiers dans le répertoire de déploiement.

ExpectedExceptionAttribute

L’attribut ExpectedException définit l’exception que la méthode de test est censée lever. Le test réussit si l’exception attendue est levée et que le message d’exception correspond au message attendu.

Avertissement

Cet attribut existe à des fins de compatibilité descendante et n’est pas recommandé pour les nouveaux tests. Utilisez plutôt la méthode Assert.ThrowsException (ou Assert.ThrowsExactly si vous utilisez MSTest 3.8 ou une version ultérieure).

Attributs de métadonnées

Les attributs suivants et les valeurs qui leur sont affectées apparaissent dans la fenêtre Visual StudioPropriétés pour une méthode de test particulière. Ces attributs ne sont pas censés être accessibles via le code du test. Au lieu de cela, ils affectent les façons dont le test est utilisé ou exécuté, par vous via l’IDE de Visual Studio ou par le moteur de test de Visual Studio. Par exemple, certains de ces attributs apparaissent sous forme de colonnes dans la fenêtre Test Manager et la fenêtre Résultats des tests, ce qui signifie que vous pouvez les utiliser pour regrouper et trier les tests et les résultats des tests. C’est le cas de TestPropertyAttribute, un attribut qui vous permet d’ajouter des métadonnées arbitraires à des tests.

Par exemple, vous pouvez l’utiliser pour stocker le nom d’une « étape de test » couverte par ce test, en marquant le test avec [TestProperty("Feature", "Accessibility")]. Vous pouvez également l’utiliser pour stocker un indicateur du genre de test avec [TestProperty("ProductMilestone", "42")]. La propriété que vous créez à l’aide de cet attribut et la valeur de propriété que vous assignez sont affichées dans la fenêtre Propriétés de Visual Studio sous le titre Spécifique au test.

Les attributs ci-dessous lient la méthode de test qu’ils décorent aux entités de la hiérarchie de projet d’un projet d’équipe Team Foundation Server :