Partage via

Attributs MSTest

  • Article

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 utilisée avec [DataRow], [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.

DataRowAttribute

DataRowAttribute 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. Il doit être combiné avec TestMethodAttribute.

Le nombre et les types d’arguments doivent correspondre exactement à la signature de la méthode de test. L’exemple suivant d’une classe de test valide illustre l’utilisation de l’attribut DataRow avec des arguments inline qui s’alignent sur les paramètres de la 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 DataRow.

[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 de ligne de données spécialisé 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

AssemblyInitialize est appelée juste après le chargement de votre assembly, et AssemblyCleanup est appelée juste avant son déchargement.

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 d'initialisation nécessite un paramètre de type TestContext et le nettoyage ne nécessite aucun paramètre, mais à partir de MSTest 3.8, celui-ci 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)
    {
    }
}

[TestClass]
public class MyOtherTestClass
{
    [AssemblyInitialize]
    public static async Task AssemblyInitialize(TestContext testContext)
    {
    }

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

Niveau classe

ClassInitialize est appelée juste avant le chargement de votre classe (mais après le constructeur statique) et ClassCleanup juste après le déchargement de votre classe.

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

Vous pouvez également configurer si le nettoyage de classe doit être exécuté à la fin de la classe ou à la fin de l’assembly.

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 phase d'initialisation nécessite un paramètre de type TestContext et la phase de nettoyage n’a pas de paramètres, ou, à partir de MSTest 3.8, elle 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)
    {
    }
}

[TestClass]
public class MyOtherTestClass
{
    [ClassInitialize]
    public static async Task ClassInitialize(TestContext testContext)
    {
    }

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

Niveau test

TestInitialize est appelée juste avant le démarrage de votre test, et TestCleanup juste après la fin du test.

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

TestCleanup est similaire à la classe Dispose (ou DisposeAsync), mais convient généralement mieux aux nettoyages longs ou asynchrones. TestCleanup est toujours appelée juste avant DisposeAsync/Dispose, et appelée pour chaque test (y compris chaque ligne de données de tests pilotés par des 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()
    {
    }
}

[TestClass]
public class MyOtherTestClass
{
    [TestInitialize]
    public async Task TestInitialize()
    {
    }

    [TestCleanup]
    public async Task 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 est abandonné une fois la durée spécifiée écoulée, mais quelques millisecondes supplémentaires peuvent être nécessaires.

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 (et les méthodes [ClassInitialize] et [ClassCleanup]) de la classe doivent être exécutées dans un thread unique cloisonné (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’il est appliqué à une méthode de test, l’attribut [STATestMethod] indique que la méthode de test doit être exécutée dans un thread unique cloisonné (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. Vous pouvez utiliser l’attribut Parallelize pour exécuter des tests en parallèle. Il s’agit d’un attribut de niveau assembly. 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 uniquement utiliser cet attribut si vous avez appliqué l’attribut [Parallelize] au niveau de l’assembly.

Attributs d’utilitaires

DeploymentItemAttribute

L’infrastructure MSTest a introduit DeploymentItemAttribute pour copier des fichiers ou des dossiers spécifiés comme éléments de déploiement dans le répertoire de déploiement (si vous n’ajoutez pas de chemin de sortie personnalisé, les fichiers sont copiés dans le dossier TestResults à l’intérieur du 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.

Vous pouvez l’utiliser sur des classes de test (marquées avec l’attribut TestClass) ou sur des méthodes de test (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

Le framework MSTest a introduit ExpectedExceptionAttribute pour marquer une méthode de test afin qu’elle attende une exception d’un type spécifique. Le test réussit si l’exception attendue est levée et si le message de l’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 et versions ultérieures).

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 :