Tester une API REST Spring MVC avec le Spring TestContext Framework

Commençons par créer notre classe OrderWebServiceTI avec les quelques annotations de base.

On a ici le test d'intégration le plus basique possible. On retrouve les annotations classiques des TU avec jUnit @Before, @RunWith et @Test.

@RunWith(SpringJUnit4ClassRunner.class)
@WebAppConfiguration
@ContextConfiguration("/applicationContext.xml")
public class OrderWebServiceTest {

SpringJUnit4ClassRunner permet l'utilisation de spring-test pour l'exécution du test, @WebAppConfiguration permet de précharger une configuration propre aux applications web (ça tombe bien, on fait du Spring MVC !) et @ContextConfiguration permet d'indiquer la configuration du contexte Spring. Ici, on veut charger toutes les dépendances de l'application (dao, service, etc.).

Comme préconisé par la documentation officielle, on charge la mock servlet à partir du webcontext fourni par Spring dans le before du test :

@Before
public void setUp() throws Exception {
    this.mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build();
}

Et enfin le test en lui-même :

@Test
public void testSaveOrder() throws Exception {
    String payload = "{ \"products\": [{ \"name\": \"Mon produit\" }]}";
    MockHttpServletRequestBuilder req = post(SERVICE_URI).contentType(MediaType.APPLICATION_JSON)
            .accept(MediaType.APPLICATION_JSON_UTF8)
            .content(payload);
    this.mockMvc.perform(req).andExpect(status().isOk());
}

Nous sommes dans le cas le plus simple. Il n'y a rien dans la base MongoDB. On fait donc une création de commande via le webservice POST /order. Notre requête au format json contient un produit. Elle est construite grâce à la méthode post (importée de manière statique) de la classe MockMvcRequestBuilders. Cette classe permet de construire notre requête à la demande. Une bonne partie des méthodes de cette classe renvoyant « this », on peut chaîner les méthodes directement. Ici on précise le content-type ainsi que l'accept. À la place de renseigner directement les strings adéquats, on peut utiliser la classe MediaType directement fournie par Spring. Enfin, on utilise la méthode content() pour préciser le corps de la requête (ce qui n'est bien sûr pas nécessaire pour des opérations telles que le GET, DELETE, etc.).

L'appel proprement dit se fait à l'aide de la méthode perform() de l'objet mockMvc. Cette méthode renvoie un objet sur lequel on peut chaîner les méthodes. Ici on utilise andExpect() qui permet d'effectuer directement des assertions sur la réponse. On vérifie, par exemple, que le HTTP status est 200. Cette méthode prend en paramètres des objets de type ResultMatcher. MockMvcResultMatchers permet d'avoir accès à un grand nombre d'assertions communes. Charge au développeur d'explorer toutes les possibilités.

Enfin, si on veut récupérer le corps de la réponse de manière brute, on peut le faire grâce aux méthodes andReturn() et getResponse() qui permettent de le récupérer sous forme binaire (getContentAsByteArray()) ou bien sous forme de chaîne de caractères (getContentAsString()).

Il existe un grand nombre de méthodes complémentaires pour effectuer toutes les opérations d'assertions d'un coup, mais je n'y ai jamais eu recours. Je préfère récupérer la réponse brute et effectuer les assertions dans un second temps. Cela me permet de choisir mon framework d'assertion.

Il est temps d'exécuter notre test ! D'abord, on démarre notre serveur de BDD mongo, et ensuite :

mvn clean test

On a bien nos trois tests exécutés et qui se terminent sans erreur :

Results: Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 5.079s
[INFO] Finished at: Wed Dec 02 09:57:01 CET 2015
[INFO] Final Memory: 18M/221M
[INFO] ------------------------------------------------------------------------

Pour ceux qui aiment les logs, on peut voir qu'on a bien nos deux TU exécutés et notre TI, comme en témoignent les logs de chargement du contexte Spring. D'ailleurs, pour les plus courageux, en mode debug, on voit bien chaque étape du chargement du contexte de la même manière que si l'on déployait la webapp dans un conteneur de servlet ou serveur d'application. Le chargement du contexte prenant un peu de temps, on peut se rassurer en voyant qu'il ne se charge qu'une seule fois par build et non une fois par test ou classe de tests.

Ajoutons un second test. Ou plutôt, ajoutons deux tests qui couvriront le GET de notre CRUD. D'abord, testons le cas où on ne trouve pas de commande en base. On cherche une commande qui aurait pour id « test », qui n'existe pas en base. On teste donc que le service renvoie bien un 404 (status().isNotFound()). L'objet req ne servant pas à grand-chose au-delà de la lisibilité, on imbrique directement tous les appels de méthodes (avec une indentation lisible s'il vous plait !).

Maintenant on aimerait tester que le GET remonte bien un objet existant en base. Comme on veut des tests indépendants les uns des autres, on ne peut pas se baser sur le test du POST pour faire un GET juste après et vérifier que la donnée créée par le premier test est remontée par le second. On a donc besoin de récupérer une DAO pour interagir avec la BDD. Ça tombe bien, on en a une dans le contexte Spring de l'application ! On peut donc l'ajouter en tant que membre de notre classe de test, @Autowired par Spring :

@Autowired
private IOrderRepository dao;

On se crée également un objet Order à sauvegarder dans le setUp()…

@Before
public void setUp() throws Exception {
    this.mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build();
    orderDataset = new OrderEntity();
    orderDataset = dao.save(orderDataset);
}

… et la suppression de cet objet dans le tearDown() pour ne pas polluer la base.

@After
public void tearDown() throws Exception {
    dao.delete(orderDataset.get_id());
}

Notre test :

@Test
public void testGetNotFoundOrder() throws Exception {
    this.mockMvc.perform(get(SERVICE_URI + "/" + "test")
            .contentType(MediaType.APPLICATION_JSON)
            .accept(MediaType.APPLICATION_JSON_UTF8_VALUE)
    ).andExpect(status().isNotFound());
}

On exécute le tout avec Maven :

Results : Tests run: 5, Failures: 0, Errors: 0, Skipped: 0

Jusqu'à maintenant, on a eu des cas très simples qui, au-delà du code HTTP, ne vérifient pas grand-chose, si ce n'est qu'il n'y ait pas de crash des services.

Étant donné que l'API de services renvoie les ressources avec lesquelles le client est en interaction (pour ceux qui veulent le mot savant pour briller au prochain meetup, les opérations PUT et POST sont dites « isomorphiques »), on pourrait vérifier que les données renvoyées sont cohérentes en sortie de chaque service.

Pour ce faire, la documentation officielle préconise d'utiliser la librairie jsonpath. On peut donc ajouter à notre pom.xml :

<dependency>
    <groupId>com.jayway.jsonpath</groupId>
    <artifactId>json-path</artifactId>
    <version>${jsonpath.version}</version>
    <scope>test</scope>
</dependency>

En fait, on n'est pas du tout obligé de l'utiliser. Personnellement, j'apprécie la facilité et la flexibilité d'utilisation grâce à l'intégration avec Spring. Je vais donc montrer deux façons de traiter la réponse qui exploitent cette librairie.

Mais juste avant, regardons ce qu'on peut faire avec. La principale fonctionnalité est de pouvoir récupérer une sous-partie d'un fichier json à l'aide de requêtes composées d'expressions régulières. La documentation propose une liste d'exemples dont on retiendra ici principalement les plus simples. Le principe général est le suivant :

Le symbole '$' désigne l'élément racine, toutes les requêtes commencent donc avec celui-ci. Le symbole '.' permet d'aller dans le niveau de profondeur suivant dans l'arborescence du json. Le symbole '..' permet de chercher un élément, quel que soit son emplacement dans la hiérarchie de l'élément en cours.

Un exemple avec nos commandes :

{
    order: {
        products: [{
            name: "tv"
        },
        {
            name: "phone"
        }]
    }
}

$.order.products on récupère la liste des produits ;

$..products a le même résultat ;

$.order.products[0].name récupère “tv” ;

$.order.products[*].name récupère la liste ['tv','phone'] ;

$.order.products..name récupère la même liste.

Attention, si on ajoutait un attribut name à l'objet order ayant la valeur “nom de commande”, la requête $..name renverrait ['tv','phone','nom de commande'].

On peut également utiliser des requêtes qui possèdent des assertions du type : “je veux tous les produits dont le nom commence par un 't'”.

Ce qui a fini de me convaincre avec cette librairie, c'est également le « requêteur » web indiqué par la documentation, qui permet de tester ses requêtes sur son jeu de données en ligne.

Appliqué à nos tests, on peut directement intégrer le jsonpath en paramètre de la méthode andExpect(). On va ajouter la récupération de l'id lors du POST pour vérifier que MongoDB a bien attribué un id à notre commande et que lorsqu'on GET une ressource par son id, c'est bien celle-ci qui est remontée par le service. En voici le test :

@Test
public void testGetOrder() throws Exception {
    this.mockMvc.perform(get(SERVICE_URI + "/" + orderDataset.get_id())
            .contentType(MediaType.APPLICATION_JSON)
            .accept(MediaType.APPLICATION_JSON_UTF8_VALUE)
    ).andExpect(status().isOk())
    .andExpect(jsonPath("$.data.id").value(orderDataset.get_id()));
}

Une autre façon de faire consiste à utiliser jsonpath pour uniquement récupérer un POJO correspondant à la commande, ce qui donne :

@Test
public void testGetOrder() throws Exception {
    String jsonResponse = this.mockMvc.perform(get(SERVICE_URI + "/" + orderDataset.get_id())
            .contentType(MediaType.APPLICATION_JSON)
            .accept(MediaType.APPLICATION_JSON_UTF8_VALUE)
    ).andExpect(status().isOk()).andReturn().getResponse().getContentAsString();
    Order responseOrder = JsonPath.parse(jsonResponse).read("$.data",Order.class);
    Assert.assertNotNull(responseOrder.getId());
    Assert.assertFalse(responseOrder.getId().isEmpty());
}

On voit qu'ici, on récupère la réponse sous forme de String, on utilise JsonPath indépendamment de Spring MVC et surtout, on fait des assertions directement sur les POJO.

Personnellement, je préfère cette solution, car en cas de réponse volumineuse ou cas de tests compliqués, lors des assertions, je pourrais réutiliser du code peut-être déjà présent dans les packages utilitaires de mon application, voire des librairies tierces qui savent manipuler des POJO. En fait, j'enlève la contrainte du json pour traiter la donnée. De plus, si je veux utiliser une autre librairie qui manipule le json comme jackson, je peux tout à fait le faire.

Nous avons donc un ensemble de tests pour nos webservices. Pour l'instant, on s'est concentré sur les tests en tant que tels, cependant, si l'on regarde la classe dans son intégralité, on observe que tous les jeux de données enregistrés dans la base de données sont exécutés dans la fonction setUp(). Or celle-ci est exécutée avant chaque méthode de test (dû au @Before jUnit). On effectue donc des opérations inutiles en base. Par exemple, pour un test de mise à jour de prospect, on crée le jeu de données correspondant autant de fois qu'il y a de tests. Ce n'est pas une approche très intuitive, ni très efficace.

Pour corriger cela, on peut envisager deux solutions. La première est de déplacer le code du setUp() correspondant aux différents cas au début de chaque méthode de test. Cela peut faire grossir les méthodes de tests en fonction de la taille des jeux de données, on perd en lisibilité, mais on cantonne toutes les variables au test, la logique d'exécution est plus simple.

La deuxième solution est de déplacer toute la création des jeux de données en base dans une méthode exécutée une seule fois avant l'ensemble des tests. L'avantage est qu'on gagne en lisibilité entre les jeux de données et les tests. L'inconvénient est que, pour faciliter certaines assertions, on peut être obligé de garder une référence vers chaque objet en base en tant qu'attribut de la classe de test.

Libre à chacun de choisir, mais nous allons continuer avec la deuxième solution, pour explorer un peu plus les possibilités de Spring test…

Tout d'abord, on pourrait avoir envie d'utiliser l'annotation @BeforeClass fournie par jUnit, mais celle-ci présente une limitation, notamment lorsqu'on travaille avec un framework qui instancie les objets pour nous, comme Spring. Comme les méthodes annotées @BeforeClass doivent être statiques, tous les objets que l'on veut référencer dans la classe et qui sont initialisés à cet endroit doivent être statiques. Conceptuellement, on ne le veut pas forcément. De plus, @Autowired ne fonctionne pas sur des attributs statiques. En fait, c'est normal, puisqu'au chargement de la classe de test, le contexte Spring n'existe pas encore. On ne peut donc pas récupérer la DAO paramétrée dans l'application. À cet instant, elle vaudrait null.

C'est maintenant que rentrent en scène les TestExecutionListener. Comme pour tous les listeners, cela permet d'exécuter du code à certains moments lors de l'exécution des tests. Avant de créer notre propre listener, ils sont là dès qu'on utilise la classe SpringJUnit4ClassRunner pour lancer les tests. Par défaut, Spring utilise les listeners suivants dans cet ordre (extrait de la documentation officielle) :

• ServletTestExecutionListener : configures Servlet API mocks for a WebApplicationContext
• DependencyInjectionTestExecutionListener : provides dependency injection for the test instance
• DirtiesContextTestExecutionListener : handles the @DirtiesContext annotation
• TransactionalTestExecutionListener : provides transactional test execution with default rollback semantics
• SqlScriptsTestExecutionListener : executes SQL scripts configured via the @Sql annotation

Dans notre cas, les trois derniers ne sont pas utiles.

Pour accéder à notre DAO avant les tests, on va faire de notre classe de test un listener. Pour cela, deux choses à faire :

1. Étendre la classe AbstractTestExecutionListener qui fournit les méthodes à surcharger ;
2. Ajouter l'annotation @TestExecutionListeners pour préciser quels listeners nous intéressent. Ici la classe de test se référence elle-même et on précise qu'on l'ajoute à la liste des listeners par défaut à l'aide du flag MergeMode.MERGE_WITH_DEFAULTS.

@TestExecutionListeners(listeners = OrderWebServiceTest.class, mergeMode = TestExecutionListeners.MergeMode.MERGE_WITH_DEFAULTS)
public class OrderWebServiceTest extends AbstractTestExecutionListener {

On ajoute la surcharge de la méthode beforeTestClass() :

@Override
public void beforeTestClass(TestContext testContext) throws Exception {
    getOrderDataset = dao.save(new OrderEntity());
    updateOrderDataset = dao.save(new OrderEntity());
    deleteOrderDataset = dao.save(new OrderEntity());
}

On exécute et… surprise ! Une bonne vielle NPE sur la référence à notre DAO dans la méthode beforeTestClass(). « Ce n'est pas normal, on est dans un contexte Spring là » me direz-vous. Sauf que si l'on regarde la classe DependencyInjectionTestExecutionListener qui active l'injection de dépendance, on se rend compte qu'elle n'implémente pas la méthode beforeTestClass(). On est donc obligé de récupérer la DAO à la main depuis le contexte Spring passé en paramètre :

@Override
public void beforeTestClass(TestContext testContext) throws Exception {
    dao = testContext.getApplicationContext().getBean(IOrderRepository.class);
    getOrderDataset = dao.save(new OrderEntity());
    updateOrderDataset = dao.save(new OrderEntity());
    deleteOrderDataset = dao.save(new OrderEntity());
}

Maintenant nos tests s'exécutent sans encombre.

Autre détail qui peut paraître bizarre, nos objets « Dataset » sont déclarés en « static » pour pouvoir garder la référence créée dans le beforeTestClass() dans le @Test. L'explication vient du fonctionnement de jUnit. Ce dernier instancie la classe de test une fois par test, alors que la méthode beforeTestClass() est exécutée une seule fois avant l'exécution du premier test. On est donc obligé de déclarer static ces jeux de données.

Cela fait réfléchir sur l'intérêt des listeners. Ici, on ne s'en sert que pour accéder à un objet créé par le contexte Spring avant l'exécution des tests. La raison première des listeners est de factoriser du code dont on aurait besoin dans plusieurs classes de test. Une description plus poussée est disponible entre les possibilités offertes par Spring test en comparaison à jUnit dans ce post stackOverflow, le tout expliqué par l'auteur du framework Spring test.

Dans cet article, le cas de test communique avec une base de données MongoDB. Seulement, en MongoDB, il n'y a pas de transaction. La seule façon de les gérer est de mettre en place la méthode du «two phase commit  », qui consiste à implémenter les états des transactions à la main.

Si on avait une base de données SQL type Oracle à la place de MongoDB, on pourrait utiliser quelques annotations fournies par Spring test comme @Rollback, @Commit,@BeforeTransaction, @AfterTransaction ou encore @TransactionConfiguration (obsolète au profit des deux premières depuis Spring 4.2). L'utilisation se fait via le TransactionalTestExecutionListener et les annotations comme @Transactional, qui permettent de gérer les transactions. D'une manière générale, le sujet n'est pas propre aux tests et ne sera donc pas détaillé ici.