ApiTestCase

ApiTestCase

ApiTestCase est un PHPUnit TestCase qui vous facilitera grandement la vie en tant que développeur d'API Symfony. Il étend Symfony WebTestCase de base avec quelques fonctionnalités intéressantes.

Grâce à PHP-Matcher vous pouvez, selon son fichier readme, "écrire les réponses json attendues comme un gangster". Nous sommes définitivement d’accord.

Il utilise également Alice pour faciliter le chargement des appareils Doctrine.

Caractéristiques:

• Flux de travail TDD clair pour le développement d'API avec Symfony ;
• Correspondance JSON/XML avec des messages d'erreur clairs ;
• Chargement des projecteurs avec Alice (facultatif) ;

Installation

En supposant que Composer soit déjà installé globalement :

composer require --dev lchrusciel/api-test-case

Et c'est fait ! ApiTestCase fonctionne avec la configuration par défaut.

Usage

Nous proposons deux classes de base pour vos cas de test : JsonApiTestCase et XmlApiTestCase. Choisissez-en un en fonction du format de l'API que vous souhaitez créer.

Exemple Json

Le flux de travail de base TDD est le suivant :

1. Écrivez un scénario de test qui envoie la requête et utilisez la méthode d'assertion assertResponse pour vérifier si le contenu de la réponse correspond à vos attentes. Vous avez besoin d'un nom pour le fichier de réponses ;
2. Créez le fichier portant le nom que vous avez choisi à l'étape 1. et placez-y le contenu de la réponse attendu. Il doit être mis dans src/AppBundle/Tests/Responses/Expected/hello_world.json par exemple.
3. Faites-le rouge.
4. Rendez-le vert.
5. Refactoriser.

Voyons un exemple simple ! Écrivez le test suivant :

 namespace AppBundle  Tests  Controller  HelloWorldTest ;

use ApiTestCase  JsonApiTestCase ;

class HelloWorldTest extends JsonApiTestCase
{
    public function testGetHelloWorldResponse ()
    {
        $ this -> client -> request ( ' GET ' , ' / ' );

        $ response = $ this -> client -> getResponse ();

        $ this -> assertResponse ( $ response , ' hello_world ' );
    }
}

Définissez maintenant le fichier de réponses attendu :

{
    "message" : " Hello ApiTestCase World! "
}

Exécutez vos tests :

vendor/bin/phpunit

Votre test devrait échouer avec quelques erreurs, il vous manque probablement le contrôleur et le routage, alors allez-y et définissez-les ! Dès que vous avez implémenté votre Controller et configuré le routage approprié, vous pouvez réexécuter vos tests :

Si le contenu de la réponse correspond à nos attentes, la console présentera un message simple :

OK (1 tests, 2 assertions)

Sinon, il présentera la différence entre les messages reçus :

 " Hello ApiTestCase World " does not match " Hello ApiTestCase World! " .
@@ -1,4 +1,3 @@
 {
-    " message " : " Hello ApiTestCase World! "
+    " message " : " Hello ApiTestCase World "
 }
-

Tout d'abord, la fonction assertResponse vérifiera le code de réponse (200 est un code de réponse par défaut), puis elle vérifiera si l'en-tête de la réponse contient le type de contenu application/json . À la fin, il vérifiera si le contenu de la réponse correspond à l'attente. Parfois, vous ne pouvez pas prédire certaines valeurs dans la réponse, par exemple la date générée automatiquement ou l'identifiant de la base de données. Aucune magie n'est nécessaire ici car PHP-Matcher vient avec un coup de main. Ce ne sont là que quelques exemples de modèles disponibles :

• @string@
• @integer@
• @boolean@
• @array@

Consultez la documentation de PHP-Matcher pour en savoir plus.

Avec ces modèles, votre réponse attendue ressemblera à ceci :

{
    "message" : " @string@ "
}

Avec cela en place, toute chaîne sous message clé correspondra au modèle. Une réponse attendue plus compliquée pourrait ressembler à ceci :

[
    {
        "id" : " @integer@ " ,
        "name" : " Star-Wars T-shirt " ,
        "sku" : " SWTS " ,
        "price" : 5500 ,
        "sizes" : " @array@ " ,
        "created_at" : " @[email protected]() "
    },
    {
        "id" : " @integer@ " ,
        "name" : " Han Solo Mug " ,
        "sku" : " HSM " ,
        "price" : 500 ,
        "sizes" : " @array@ " ,
        "created_at" : " @[email protected]() "
    }
]

Et correspondra à la liste de produits suivante :

 array (
    array (
        ' id ' => 1 ,
        ' name ' => ' Star-Wars T-shirt ' ,
        ' sku ' => ' SWTS ' ,
        ' price ' => 5500 ,
        ' sizes ' => array ( ' S ' , ' M ' , ' L ' ),
        ' created_at ' => new  DateTime (),
    ),
    array (
        ' id ' => 2 ,
        ' name ' => ' Han Solo Mug ' ,
        ' sku ' => ' HSM ' ,
        ' price ' => 500 ,
        ' sizes ' => array ( ' S ' , ' L ' ),
        ' created_at ' => new  DateTime (),
    ),
)

Tests avec des appareils de base de données

ApiTestCase est intégré à nelmio/alice . Grâce à cette jolie bibliothèque, vous pouvez facilement charger vos appareils lorsque vous en avez besoin. Vous devez définir vos appareils et les placer dans un répertoire approprié. Voici un exemple de la manière de définir vos appareils et votre cas d'utilisation. Pour plus d'informations sur la façon de définir vos appareils, consultez la documentation d'Alice.

Pour utiliser Alice avec Doctrine, vous devez activer deux offres supplémentaires :

Symfony 4.0+

 // config/bundles.php
return [
    // ...
    
    Nelmio  Alice  Bridge  Symfony NelmioAliceBundle::class => [ ' test ' => true ],
    Fidry  AliceDataFixtures  Bridge  Symfony FidryAliceDataFixturesBundle::class => [ ' test ' => true ],
];

Supposons maintenant que vous ayez une entité Doctrine mappée appelée Book dans votre application :

    class Book 
    {
        private $ id ;
        private $ title ;
        private $ author ;
    
        // ... 
    }

Pour charger les appareils pour le test, vous devez définir un simple fichier YAML dans src/AppBundle/Tests/DataFixtures/ORM/books.yml :

    ApiTestCaseTestEntityBook :
        book1 :
            title : " Lord of The Rings "
            author : " J. R. R. Tolkien "
        book2 :
            title : " Game of Thrones "
            price : " George R. R. Martin "

Enfin, pour utiliser ces appareils dans un test, appelez simplement une méthode appropriée :

    public function testBooksIndexAction ()
    {
        // This method require subpath to locate specific fixture file in your DataFixtures/ORM directory.
        $ this -> loadFixturesFromFile ( ' books.yml ' );  
      
        // There is another method that allows you to load fixtures from directory.
        $ this -> loadFixturesFromDirectory ( ' big_library ' );
    }

Référence de configuration

Pour personnaliser la configuration de votre suite de tests, vous pouvez ajouter quelques options supplémentaires à phpunit.xml :

< php >
    < server name = " KERNEL_CLASS " value = " AcmeKernel " />
    < server name = " EXPECTED_RESPONSE_DIR " value = " /path/to/expected/responses/ " />
    < server name = " FIXTURES_DIR " value = " /path/to/DataFixtures/ORM/ " />
    < server name = " OPEN_ERROR_IN_BROWSER " value = " true/false " />
    < server name = " OPEN_BROWSER_COMMAND " value = " open %s " />
    < server name = " IS_DOCTRINE_ORM_SUPPORTED " value = " true/false " />
    < server name = " TMP_DIR " value = " /tmp/path/to/temporary/folder/ " />
    < server name = " ESCAPE_JSON " value = " true/false " />
</ php >

• KERNEL_CLASS vous permet de spécifier exactement quelle classe doit être utilisée pour configurer le noyau.
• La variable ERESPONSE_DIR contient les chemins d'accès au dossier avec les réponses attendues. Il est utilisé lorsque le résultat de l'API est comparé au fichier json existant. Si cette valeur n'est pas définie, ApiTestCase tentera de deviner l'emplacement des réponses, en recherchant les réponses dans un dossier : '../Responses' relativement situé par rapport à la classe de test de votre contrôleur.
• La variable FIXTURES_DIR contient un chemin vers le dossier contenant vos appareils de données. Par défaut, si cette variable n'est pas définie, elle recherchera ../DataFixtures/ORM/ relativement situé par rapport à votre classe de test. ApiTestCase lance RunTimeException si le dossier n'existe pas ou s'il n'y a aucun fichier à charger.
• OPEN_ERROR_IN_BROWSER est un indicateur qui active l'affichage d'une erreur dans une fenêtre de navigateur. La valeur par défaut est fausse.
• OPEN_BROWSER_COMMAND est une commande qui sera utilisée pour ouvrir le navigateur avec une exception.
• IS_DOCTRINE_ORM_SUPPORTED est un indicateur qui active la prise en charge de la doctrine et comprend un chargeur de données pratique et un purgeur de base de données.
• La variable TMP_DIR contient un chemin vers le dossier temporaire, où les fichiers journaux seront stockés.
• ESCAPE_JSON est un indicateur qui active l'échappement (caractères Unicode et barres obliques) de votre sortie JSON avant de la comparer aux données attendues. La valeur par défaut est fausse. Cet indicateur n'existe que pour une compatibilité ascendante avec les versions précédentes d'ApiTestCase (lorsqu'il est activé) et sera supprimé dans une version future.

Exemple de projet

Dans le répertoire test/ , vous pouvez trouver un exemple de projet Symfony avec une configuration minimale requise pour utiliser cette bibliothèque.

Essai

Afin d'exécuter notre suite de tests PHPUnit, exécutez les commandes suivantes :

composer install
test/app/console doctrine:database:create
test/app/console doctrine:schema:create
vendor/bin/phpunit

Suivi des bogues et suggestions

Si vous avez trouvé un bug ou avez une bonne idée d'amélioration, veuillez ouvrir un ticket sur ce référentiel.

Gestion des versions

Les versions seront numérotées au format major.minor.patch .

Et construit avec les directives suivantes.

• Briser la rétrocompatibilité modifie le problème majeur.
• Les nouveaux ajouts sans rompre la rétrocompatibilité modifient le mineur.
• Les corrections de bugs et les modifications diverses modifient le correctif.

Pour plus d’informations sur SemVer, veuillez visiter le site Web semver.org.

Licence MIT

La licence peut être trouvée ici.

Auteurs

La bibliothèque a été créée à l'origine par :

• Lukasz Chruściel
• Michael Marcinkowski
• Paweł Jędrzejewski
• Arkadiusz Krakowiak

chez Lakion sous le référentiel https://github.com/Lakion/ApiTestCase.

Voir la liste des contributeurs.