Migration depuis JUnit 4

Bien que le modèle de programmation et le modèle d'extension de JUnit Jupiter ne prennent pas en charge les fonctionnalités de JUnit 4 telles que les règles et les exécutions de manière native, il n'est pas prévu que les responsables du code source aient besoin de mettre à jour tous leurs tests existants, leurs extensions de test et leur infrastructure de test personnalisée pour migrer à JUnit Jupiter.

Au lieu de cela, JUnit fournit un chemin de migration doux via un moteur de test JUnit Vintage permettant d'exécuter des tests existants basés sur JUnit 3 et JUnit 4 à l'aide de l'infrastructure de la plate-forme JUnit. Étant donné que toutes les classes et annotations spécifiques à JUnit Jupiter résident sous le paquet de base org.junit.jupiter, avoir à la fois JUnit 4 et JUnit Jupiter dans le chemin de classe n'entraîne aucun conflit. Il est donc sûr de maintenir les tests JUnit 4 existants aux côtés des tests JUnit Jupiter. De plus, étant donné que l'équipe JUnit continuera à fournir des versions de maintenance et de correction de bogues pour la base de référence JUnit 4.x, les développeurs ont suffisamment de temps pour migrer vers JUnit Jupiter selon leur propre calendrier.

Exécution de tests JUnit 4 sur la plateforme JUnit

Assurez-vous que l'artefact junit-vintage-engine se trouve dans votre chemin d'exécution de test. Dans ce cas, les tests JUnit 3 et JUnit 4 seront automatiquement récupérés par le lanceur de la plateforme JUnit.

Support de catégories

Pour les classes ou méthodes de test annotées avec @Category, le moteur de test JUnit Vintage expose le nom de classe complet de la catégorie en tant que balise pour la classe de test ou la méthode de test correspondante. Par exemple, si une méthode de test est annotée avec @Category(Example.class), elle sera étiquetée avec «com.acme.Example». Semblable au programme d'exécution de catégories dans JUnit 4, ces informations peuvent être utilisées pour filtrer les tests découverts avant de les exécuter.

Conseils de migration

Voici les sujets que vous devez connaître lors de la migration des tests JUnit 4 existants vers JUnit Jupiter.

• Les annotations résident dans le package org.junit.jupiter.api.
• Les assertions résident dans org.junit.jupiter.api.Assertions. Notez que vous pouvez continuer à utiliser les méthodes d'assertion de org.junit.Assert ou de toute autre bibliothèque d'assertions telle que AssertJ, Hamcrest, Truth,...
• Les hypothèses résident dans org.junit.jupiter.api.Assumptions. Notez que JUnit Jupiter 5.4 et les versions ultérieures prennent en charge les méthodes de la classe org.junit.Assume de JUnit 4 pour les hypothèses. Plus précisément, JUnit Jupiter prend en charge AssumptionViolatedException de JUnit 4 pour signaler qu'un test doit être abandonné au lieu d'être marqué comme un échec.
• @Before et @After n'existent plus ; utilisez plutôt @BeforeEach et @AfterEach.
• @BeforeClass et @AfterClass n'existent plus ; utilisez plutôt @BeforeAll et @AfterAll.
• @Ignore n'existe plus : utilisez plutôt @Disabled ou l'une des autres conditions d'exécution intégrées
• @Category n'existe plus ; utilisez plutôt @Tag.
• @RunWith n'existe plus ; remplacé par @ExtendWith.
• @Rule et @ClassRule n'existent plus ; remplacé par @ExtendWith et @RegisterExtension.
• @Test(expected = ...?) et la règle ExpectedException n'existent plus ; utilisez plutôt Assertions.assertThrows(...?).
• Les assertions et hypothèses dans JUnit Jupiter acceptent le message d'échec comme dernier argument au lieu du premier.

Prise en charge limitée des règles JUnit 4

Comme indiqué ci-dessus, JUnit Jupiter ne prend pas en charge et ne prendra pas en charge les règles JUnit 4 de manière native. L'équipe JUnit se rend cependant compte que de nombreuses organisations, en particulier les plus grandes, sont susceptibles d'avoir de grandes bases de code JUnit 4 utilisant des règles personnalisées. Pour servir ces organisations et permettre une migration progressive, l'équipe JUnit a décidé de prendre en charge une sélection de règles JUnit 4 textuellement dans JUnit Jupiter. Cette prise en charge est basée sur des adaptateurs et est limitée aux règles sémantiquement compatibles avec le modèle d'extension JUnit Jupiter, c'est-à-dire celles ne modifiant pas complètement le flux d'exécution global du test.

Le module junit-jupiter-migrationsupport de JUnit Jupiter prend actuellement en charge les trois types de règles suivants, y compris les sous-classes de ces types :

• org.junit.rules.ExternalResource (y compris org.junit.rules.TemporaryFolder)
• org.junit.rules.Verifier (y compris org.junit.rules.ErrorCollector)
• org.junit.rules.ExpectedException

Comme dans JUnit 4, les champs annotés par des règles ainsi que les méthodes sont pris en charge. En utilisant ces extensions au niveau de la classe sur une classe de test, ces implémentations de règles dans les bases de code héritées peuvent rester inchangées, y compris les instructions d'importation de règles JUnit 4.

Cette forme limitée de prise en charge des règles peut être activée par l'annotation au niveau de la classe @EnableRuleMigrationSupport. Cette annotation est une annotation composée activant toutes les extensions de prise en charge de la migration de règles : VerifierSupport, ExternalResourceSupport et ExpectedExceptionSupport. Vous pouvez également choisir d'annoter votre classe de test avec @EnableJUnit4MigrationSupport enregistrant la prise en charge de la migration pour les règles et l'annotation @Ignore de JUnit 4 (voir JUnit 4 @Ignore Support).

Cependant, si vous avez l'intention de développer une nouvelle extension pour JUnit Jupiter, veuillez utiliser le nouveau modèle d'extension de JUnit Jupiter au lieu du modèle basé sur des règles de JUnit 4.

Support du JUnit 4 @Ignore

Afin de fournir un chemin de migration fluide de JUnit 4 vers JUnit Jupiter, le module junit-jupiter-migrationsupport fournit une prise en charge de l'annotation @Ignore de JUnit 4 analogue à l'annotation @Disabled de Jupiter.

Pour utiliser @Ignore avec les tests basés sur JUnit Jupiter, configurez une dépendance de test sur le module junit-jupiter-migrationsupport dans votre build, puis annotez votre classe de test avec @ExtendWith(IgnoreCondition.class) ou @EnableJUnit4MigrationSupport (qui enregistre automatiquement IgnoreCondition avec Prise en charge limitée des règles JUnit 4). IgnoreCondition est une ExecutionCondition désactivant les classes de test ou les méthodes de test annotées avec @Ignore.

Paramètre du message d'échec

Les classes Assumptions et Assertions dans JUnit Jupiter déclarent les paramètres dans un ordre différent de celui de JUnit 4. Dans JUnit 4, les méthodes d'assertion et d'hypothèse acceptent le message d'échec comme premier paramètre ; alors que, dans JUnit Jupiter, les méthodes d'assertion et d'hypothèse acceptent le message d'échec comme dernier paramètre.

Par exemple, la méthode assertEquals dans JUnit 4 est déclarée comme assertEquals (String message, Object attendu, Object actual), mais dans JUnit Jupiter, elle est déclarée comme assertEquals (Object attendu, Object actual, String message). La raison en est qu'un message d'échec est facultatif et que les paramètres facultatifs doivent être déclarés après les paramètres requis dans une signature de méthode.

Les méthodes concernées par ce changement sont les suivantes :

• Assertions :
• assertTrue
• assertFalse
• assertNull
• assertNotNull
• assertEquals
• assertNotEquals
• assertArrayEquals
• assertSame
• assertNotSame
• assertThrows
• Assumptions :
• assumeTrue
• assumeFalse