Skip to content

Chapitre 2.8 : Test d'API

Temps d'étude : 1 heure

1. Pourquoi les tests sont-ils nécessaires ?

Imaginez que vous ayez construit un vaisseau spatial. Avant de l'envoyer sur Mars, vous effectuez des milliers de vérifications sur Terre. Les tests en programmation, c'est la même chose. Ils :

  • Donnent confiance : Vous pouvez modifier le code, et si les tests passent, cela signifie que vous n'avez rien cassé.
  • Économisent du temps : Au lieu de "cliquer" manuellement sur tout dans Postman après chaque modification, vous exécutez une seule commande qui vérifie tout pour vous en quelques secondes.
  • Servent de documentation : De bons tests montrent comment votre API est censée fonctionner.

2. Configuration du "Laboratoire" de test

Laravel rend la configuration des tests incroyablement simple. Par défaut, il utilise une configuration distincte afin de ne pas affecter votre base de données principale.

Base de données pour les tests : Par défaut, Laravel utilise une base de données en mémoire (:memory:). C'est la méthode la plus rapide car il n'est pas nécessaire d'écrire quoi que ce soit sur le disque. La base de données est créée avant les tests et détruite après. Nous n'avons même rien à configurer pour cela !

Création du fichier de test : Créons un fichier spécial pour les tests liés aux planètes.

php artisan make:test PlanetApiTest

Cette commande créera le fichier tests/Feature/PlanetApiTest.php. Le mot Feature signifie que nous allons tester la fonctionnalité dans son ensemble (par exemple, "l'utilisateur peut-il créer une planète ?"), et non une petite classe individuelle.

3. Anatomie d'un test : Préparation, Action, Vérification

Ouvrez tests/Feature/PlanetApiTest.php. Nous y écrirons notre premier test. Un bon test se compose toujours de trois parties (Arrange, Act, Assert).

<?php

namespace Tests\Feature;

use App\Models\Planet; // N'oubliez pas d'importer le modèle
use Illuminate\Foundation\Testing\RefreshDatabase; // L'outil le plus important !
use Tests\TestCase;

class PlanetApiTest extends TestCase
{
    // Ce trait "nettoie" et recrée "magiquement"
    // notre base de données de test avant chaque test.
    // Cela garantit que les tests ne s'affectent pas mutuellement.
    use RefreshDatabase;

    /**
     * Test : le point de terminaison pour obtenir la liste des planètes fonctionne correctement.
     * Les noms des tests doivent être significatifs !
     */
    public function test_can_get_all_planets(): void
    {
        // 1. PRÉPARATION (Arrange)
        // Nous créons 3 planètes factices dans notre base de données de test
        // à l'aide de la fabrique que nous avons créée précédemment.
        Planet::factory()->count(3)->create();

        // 2. ACTION (Act)
        // Nous simulons une véritable requête GET vers notre API.
        $response = $this->getJson('/api/planets');

        // 3. VÉRIFICATION (Assert)
        // Nous vérifions que tout s'est passé comme prévu.
        $response->assertStatus(200); // Nous nous attendons à ce que le serveur réponde "200 OK"
        $response->assertJsonCount(3); // Nous nous attendons à exactement 3 planètes dans la réponse
    }
}
Points clés :

  • use RefreshDatabase : Ce trait est votre meilleur ami. Il garantit que chaque test commence avec une "table rase", avec une base de données vide.
  • Planet::factory() : Les fabriques sont idéales pour créer des données de test.
  • $this->getJson() : C'est une méthode Laravel spéciale pour envoyer des requêtes API à l'intérieur des tests.
  • assert...() : Ce sont des "assertions" ou des "vérifications". Si au moins l'une d'entre elles échoue, le test échouera.

4. Test des opérations principales (CRUD)

Écrivons des tests pour la création, la mise à jour et la suppression de planètes.

A. Test de création de planète (POST)

<?php
public function test_can_create_a_planet(): void
{
    // 1. Préparation : préparation des données pour une nouvelle planète
    $planetData = [
        'name' => 'Kepler-186f',
        'description' => 'La première exoplanète de la taille de la Terre dans la zone habitable.',
        'size_km' => 14000,
        'solar_system' => 'Kepler-186'
    ];

    // 2. Action : envoi d'une requête POST avec les données
    $response = $this->postJson('/api/planets', $planetData);

    // 3. Vérification
    $response->assertStatus(201); // Nous nous attendons au statut "201 Created"
    $response->assertJsonFragment(['name' => 'Kepler-186f']); // Nous vérifions que le nom créé est présent dans la réponse

    // La vérification la plus importante : les données ont-elles vraiment été ajoutées à la base de données ?
    $this->assertDatabaseHas('planets', [
        'name' => 'Kepler-186f'
    ]);
}

B. Test de suppression de planète (DELETE) 

<?php
public function test_can_delete_a_planet(): void
{
    // 1. Préparation : création de la planète à supprimer
    $planet = Planet::factory()->create();

    // 2. Action : envoi d'une requête DELETE
    $response = $this->deleteJson("/api/planets/{$planet->id}");

    // 3. Vérification
    $response->assertStatus(204); // Nous nous attendons à "204 No Content" - suppression réussie

    // Nous vérifions que l'enregistrement a bien disparu de la base de données
    $this->assertDatabaseMissing('planets', [
        'id' => $planet->id
    ]);
}

5. Test des "mauvais" scénarios

Tester les cas réussis est une bonne chose. Mais il est encore plus important de tester les erreurs !

A. Test d'erreur de validation 

<?php
public function test_creation_fails_with_invalid_data(): void
{
    // 2. Action : envoi de données sciemment incorrectes
    $response = $this->postJson('/api/planets', ['name' => '']); // Nom vide

    // 3. Vérification
    $response->assertStatus(422); // Nous nous attendons à "422 Unprocessable Entity"
    $response->assertJsonValidationErrors('name'); // Nous nous attendons à ce que l'erreur se trouve spécifiquement dans le champ 'name'
}

B. Test de "non trouvé" (404) 

<?php
public function test_returns_404_for_non_existent_planet(): void
{
    // 2. Action : demande d'une planète avec un ID inexistant
    $response = $this->getJson('/api/planets/99999');

    // 3. Vérification
    $response->assertStatus(404); // Nous nous attendons à "404 Not Found"
}

6. Exécution des tests

Maintenant que les tests sont écrits, les exécuter est très simple. Exécutez dans le terminal :

php artisan test

Laravel trouvera tous vos tests et les exécutera un par un. Si tout se passe bien, vous verrez une sortie verte. Si un test échoue, vous verrez une sortie rouge avec une description détaillée de l'erreur, ce qui vous permettra de la corriger rapidement.

Pour exécuter un seul fichier spécifique : 

php artisan test tests/Feature/PlanetApiTest.php

8. Couverture de code (Code Coverage)

Étape 1 : Installation de Xdebug

Pour collecter les informations de couverture de code, l'extension PHP Xdebug est requise.

Envoyez votre php -i au wizard et suivez les instructions.

Étape 2 : Configuration de phpunit.xml 

<phpunit ... >
    <coverage processUncoveredFiles="true">
        <include>
            <directory suffix=".php">./app</directory>
        </include>
    </coverage>
</phpunit>

Étape 3 : Exécution avec rapport 

php artisan test --coverage-html=coverage
Rapport : Ouvrez coverage/index.html dans le navigateur

9. Intégration avec Postman

Automatisation via Newman :

  1. Exportez la collection Postman vers tests/Postman/SpaceApi.postman_collection.json
  2. Installez Newman : 
    npm install -g newman
  3. Ajoutez le script dans composer.json : 
    "scripts": {
    "test:postman": "newman run tests/Postman/SpaceApi.postman_collection.json"
}
  4. Exécution : 
    composer test:postman

Quiz pour la consolidation

1. Commande pour créer une classe de test :

2. Le trait RefreshDatabase est utilisé pour :

3. Méthode pour vérifier la structure JSON :

4. Les fabriques dans Laravel sont nécessaires pour :

5. Outil pour exécuter des collections Postman depuis la CLI :

🚀 Résumé du chapitre : Vous avez effectué un cycle complet de tests de pré-lancement ! Votre API peut désormais :

  • ✅ Configurer l'environnement de test sans effort supplémentaire
  • 🛡️ Écrire des tests basés sur le principe "Préparation-Action-Vérification".
  • 📊 Tester les scénarios réussis (CRUD) ainsi que les erreurs (validation, 404).
  • 🔁 Exécuter les tests avec une seule commande et être confiant dans votre code.

Le vaisseau spatial est prêt pour le lancement ! Vous avez terminé la section sur la création d'une API avec Laravel.

📌 Vérification finale :

  1. Exécutez php artisan test
  2. Assurez-vous que tous les tests passent (lumière verte !)
  3. Vérifiez le rapport de couverture

⚠️ Si les tests échouent :

  • Vérifiez le fonctionnement de l'API via Postman
  • Assurez-vous que la base de données de test est configurée
  • Utilisez dd($response->content()) pour le débogage

Félicitations pour l'achèvement du Chapitre 2 ! Vous n'avez pas seulement créé une API, vous avez construit un "vaisseau spatial" fiable et testé, prêt pour de futures missions.

🌌 Prochaines étapes :

  1. Configuration de l'authentification (Sanctum)
  2. Documentation de l'API avec Swagger
  3. Déploiement sur un serveur (Forge, VPS)
  4. Développement du frontend avec Vue/React

Bon lancement pour votre mission spatiale ! Dans le prochain chapitre, nous aborderons la création d'une API à partir de zéro 🚀