Testing¶

Installer PHPUnit avec Composer¶

Pour installer PHPUnit avec Composer:

$ php composer.phar require --dev phpunit/phpunit:"^8.5"

Cela va ajouter la dépendance à la section require-dev de votre composer.json, et ensuite installer PHPUnit au même endroit que vos autres dépendances.

Vous pouvez maintenant lancer PHPUnit en utilisant:

$ vendor/bin/phpunit

Utiliser le fichier PHAR¶

Après avoir téléchargé le fichier phpunit.phar, vous pouvez l’utiliser pour lancer vos tests:

php phpunit.phar

chmod +x phpunit.phar
sudo mv phpunit.phar /usr/local/bin/phpunit
phpunit --version

Filtrer les Cas de Test¶

Quand vous avez de nombreux cas de test et que vous travaillez sur un seul test qui échoue, vous préférerez lancer seulement une partie des méthodes de test. Avec l’exécuteur en ligne de commande vous pouvez utiliser une option pour filtrer les méthodes de test:

$ phpunit --filter testSave tests/TestCase/Model/Table/ArticlesTableTest

Le paramètre filter est utilisé comme une expression régulière sensible à la casse pour filtrer les méthodes de test à lancer.

Générer une Couverture de Code (Code Coverage)¶

Vous pouvez générer un rapport de couverture de code depuis la ligne de commande en utilisant les outils de couverture de code intégrés à PHPUnit. PHPUnit va générer un ensemble de fichiers statiques en HTML contenant les résultats de couverture. Vous pouvez générer un rapport de couverture pour un seul cas de test de la façon suivante:

$ phpunit --coverage-html webroot/coverage tests/TestCase/Model/Table/ArticlesTableTest

Cela placera le résultat de couverture de code dans le répertoire webroot de votre application. Vous pourrez voir les résultats en consultant http://localhost/votre_app/coverage.

Vous pouvez aussi utiliser phpdbg pour générer la couverture des résultats à la place de xdebug. phpdbg est généralement plus rapide dans la génération des rapports de couverture:

$ phpdbg -qrr phpunit --coverage-html webroot/coverage tests/TestCase/Model/Table/ArticlesTableTest

Combiner les Suites de Test pour les Plugins¶

Souvent, votre application sera composée de plusieurs plugins. Dans ces situations, il peut être assez fastidieux d’effectuer des tests pour chaque plugin. Vous pouvez faire lancer des tests pour chaque plugin qui compose votre application en ajoutant une section <testsuite> supplémentaire dans le fichier phpunit.xml.dist de votre application:

<testsuites>
    <testsuite name="app">
        <directory>./tests/TestCase</directory>
    </testsuite>

    <!-- Ajouter vos plugins -->
    <testsuite name="forum">
        <directory>./plugins/Forum/tests/TestCase/</directory>
    </testsuite>
</testsuites>

Les suites de tests supplémentaires ajoutées à l’élément <testsuites> seront exécutées automatiquement quand vous utiliserez phpunit.

Si vous vous servez de <testsuites> pour utiliser des fixtures à partir de plugins que vous avez installés avec composer, le fichier composer.json du plugin doit ajouter le namespace de la fixture dans la section autoload. Par exemple:

"autoload-dev": {
    "psr-4": {
        "PluginName\\Test\\Fixture\\": "tests/Fixture/"
    }
},

Connexions de Test¶

Par défaut, CakePHP va faire un alias pour chaque connexion de votre application. Pour chaque connexion définie dans le bootstrap de votre application qui ne commence pas par test_, un alias va être créé avec le préfixe test_. Le fait d’ajouter des alias de connexions garantit que vous n’utiliserez pas accidentellement la mauvaise connexion dans les cas de test. Les alias de connexions sont transparents pour le reste de votre application. Par exemple, si vous utilisez la connexion “default”, vous obtiendrez à la place la connexion test dans les cas de test. Si vous utilisez la connexion “replica”, la suite de tests tentera d’utiliser “test_replica”.

Configuration de PHPUnit¶

Avant d’utiliser les fixtures vous devez vous assurer que votre phpunit.xml contienne l’extension fixture:

<!-- dans phpunit.xml -->
<!-- Configurer l'extension pour les fixtures -->
<extensions>
    <extension class="\Cake\TestSuite\Fixture\PHPUnitExtension" />
</extensions>

L’extension est incluse par défaut dans votre application et vos plugins générés par bake.

Avant 4.3.0, CakePHP utilisait un listener PHPUnit au lieu d’une extension PHPUnit et votre fichier phpunit.xml devait contenir:

<!-- dans phpunit.xml -->
<!-- Définir un listener pour les fixtures -->
<listeners>
    <listener
    class="\Cake\TestSuite\Fixture\FixtureInjector">
        <arguments>
            <object class="\Cake\TestSuite\Fixture\FixtureManager" />
        </arguments>
    </listener>
</listeners>

Le listener est déprécié et vous devriez mettre à niveau votre configuration de fixture.

Créer un Schéma de Base de Données de Test¶

Vous pouvez générer un schéma de base de données de test soit par des migrations de CakePHP, soit en chargeant un fichier de dump SQL, soit en utilisant un autre outil externe de gestion de schéma. Vous devez créer votre schéma dans le fichier tests/bootstrap.php de votre application.

Si vous utilisez le plugin de migrations de CakePHP pour gérer les schémas de votre application, vous pouvez tout aussi bien réutiliser ces migrations pour générer le schéma de votre base de données de test:

// dans tests/bootstrap.php
use Migrations\TestSuite\Migrator;

$migrator = new Migrator();

// Configuration simple sans plugin
$migrator->run();

// Lancer les migrations pour plusieurs plugins
$migrator->run(['plugin' => 'Contacts']);

// Lancer les migrations Documents sur la connexion test_docs.
$migrator->run(['plugin' => 'Documents', 'connection' => 'test_docs']);

Si vous avez besoin de lancer plusieurs ensembles de migrations, vous pouvez le faire comme ceci:

$migrator->runMany([
    // Lancer les migrations de l'application sur la connexion test
    ['connection' => 'test'],
    // Lancer les migrations du plugin Contacts sur la connexion test
    ['plugin' => 'Contacts'],
    // Lancer les migrations du plugin Documents sur la connexion test_docs
    ['plugin' => 'Documents', 'connection' => 'test_docs']
]);

L’utilisation de runMany() vous garantit que les plugins qui partagent une même base de données ne risquent pas de supprimer des tables quand chaque ensemble de migrations est lancé.

Le plugin de migrations lancera uniquement les migrations qui n’ont pas été appliquées, et réinitialisera les migrations si l’en-tête de votre migration actuelle est différente des migrations appliquées.

Vous pouvez aussi configurer dans vos datasources la façon dont les migrations doivent être lancées dans les tests. Consultez la documentation des migrations pour plus d’information.

Pour charger un fichier de dump SQL, vous pouvez faire ceci:

// dans tests/bootstrap.php
use Cake\TestSuite\Fixture\SchemaLoader;

// Charger un ou plusieurs fichiers SQL.
(new SchemaLoader())->loadSqlFiles('chemin/vers/le/schema.sql', 'test');

Au début du lancement de chaque test, SchemaLoader supprimera toutes les tables dans la connexion et les reconstruira à partir du fichier de schéma fourni.

Gestionnaires d’Etat des Fixtures¶

Par défaut, CakePHP réinitialise l’état des fixtures à la fin de chaque test en tronquant toutes les tables dans la base de données. Cette opération peut devenir coûteuse quand votre application grossit. Si vous utilisez TransactionStrategy, chaque méthode de test sera lancée à l’intérieur d’une transaction suivie d’un rollback à la fin du test. Cela peut améliorer vos performances mais nécessite que vos tests ne dépendent pas trop de données statiques de fixtures, car les valeurs des auto-incréments ne sont pas réinitialisées avant chaque test.

La stratégie de gestion de l’état des fixtures peut être définie à l’intérieur du test:

use Cake\TestSuite\TestCase;
use Cake\TestSuite\Fixture\FixtureStrategyInterface;
use Cake\TestSuite\Fixture\TransactionStrategy;

class ArticlesTableTest extends TestCase
{
    /**
     * Crée la stratégie de fixtures utilisée pour ce cas de test.
     * Vous pouvez utiliser une classe/un trait pour modifier plusieurs classes.
     */
    protected function getFixtureStrategy(): FixtureStrategyInterface
    {
        return new TransactionStrategy();
    }
}

Créer les Fixtures¶

Les fixtures définissent les enregistrements qui seront insérés dans la base de données au démarrage de chaque test. Créons notre première fixture, qui sera utilisée pour tester notre propre model Article. Créez un fichier nommé ArticlesFixture.php dans votre répertoire tests/Fixture avec le contenu suivant:

namespace App\Test\Fixture;

use Cake\TestSuite\Fixture\TestFixture;

class ArticlesFixture extends TestFixture
{

      // Facultatif. Définissez cette variable pour charger des fixtures avec
      // une base de données de test différente.
      public $connection = 'test';

      public $records = [
          [
              'title' => 'Premier Article',
              'body' => 'Contenu du premier Article',
              'published' => '1',
              'created' => '2007-03-18 10:39:23',
              'modified' => '2007-03-18 10:41:31'
          ],
          [
              'title' => 'Deuxième Article',
              'body' => 'Contenu du deuxième Article',
              'published' => '1',
              'created' => '2007-03-18 10:41:23',
              'modified' => '2007-03-18 10:43:31'
          ],
          [
              'title' => 'Troisième Article',
              'body' => 'Contenu du troisième Article',
              'published' => '1',
              'created' => '2007-03-18 10:43:23',
              'modified' => '2007-03-18 10:45:31'
          ]
      ];
 }

La propriété $connection définit la source de données que la fixture va utiliser. Si votre application utilise plusieurs sources de données, vous devriez faire correspondre les fixtures avec les sources de données du model, en ajoutant le préfixe test_. Par exemple, si votre model utilise la source de données mydb, votre fixture devra utiliser la source de données test_mydb. Si la connexion test_mydb n’existe pas, vos models utiliseront la source de données test par défaut. Les sources de données des fixtures doivent être préfixées par test pour réduire la possibilité de tronquer accidentellement toutes les données de votre application en lançant vos tests.

Nous pouvons définir un ensemble d’enregistrements qui seront insérés après la création de la table de fixture. Le format parle de lui-même. $records est un tableau d’enregistrements. Chaque item dans $records correspond à un enregistrement (une seule ligne). À l’intérieur de chaque ligne, il doit y avoir un tableau associatif des colonnes et valeurs pour la ligne. Gardez juste à l’esprit que tous les enregistrements dans le tableau $records doivent avoir les mêmes clés car les lignes sont insérées en une seule requête SQL.

Les Données Dynamiques¶

Pour utiliser des fonctions ou d’autres données dynamiques dans les enregistrements de vos fixtures, vous pouvez définir vos enregistrements dans la méthode init() des fixtures:

namespace App\Test\Fixture;

use Cake\TestSuite\Fixture\TestFixture;

class ArticlesFixture extends TestFixture
{
    public function init(): void
    {
        $this->records = [
            [
                'title' => 'Premier Article',
                'body' => 'Contenu du premier Article',
                'published' => '1',
                'created' => date('Y-m-d H:i:s'),
                'modified' => date('Y-m-d H:i:s'),
            ],
        ];
        parent::init();
    }
}

Charger les Fixtures dans vos Tests¶

Une fois que vous avez créé vos fixtures, vous pouvez les utiliser dans vos cas de test. Vous devez charger dans chaque cas de test les fixtures dont vous aurez besoin. Vous devriez charger une fixture pour chaque model sur lequel une requête sera exécutée. Pour charger les fixtures, définissez la propriété $fixtures dans votre model:

class ArticleTest extends TestCase
{
    protected $fixtures = ['app.Articles', 'app.Comments'];
}

À partir de 4.1.0 vous pouvez utiliser getFixtures() pour définir votre liste de fixtures depuis une méthode:

public function getFixtures(): array
{
    return [
        'app.Articles',
        'app.Comments',
    ];
}

Ceci va charger les fixtures d’Article et de Comment à partir du répertoire Fixture de votre application. Vous pouvez aussi charger des fixtures du cœur de CakePHP ou des plugins:

class ArticlesTest extends TestCase
{
    protected $fixtures = [
        'plugin.DebugKit.Articles',
        'plugin.MonNomDeVendor/MonPlugin.Messages',
        'core.Comments'
    ];
}

Utiliser le préfixe core va charger des fixtures de CakePHP, et utiliser un nom de plugin en préfixe chargera la fixture à partir de ce plugin.

Vous pouvez charger les fixtures dans des sous-répertoires. Si votre application est volumineuse, il est plus facile d’organiser vos fixtures en utilisant plusieurs répertoires. Pour charger des fixtures dans des sous-répertoires, incluez simplement le nom du sous-répertoire dans le nom de la fixture:

class ArticlesTest extends CakeTestCase
{
    protected $fixtures = ['app.Blog/Articles', 'app.Blog/Comments'];
}

Dans l’exemple ci-dessus, les deux fixtures seront chargées à partir de tests/Fixture/Blog/.

Fixture Factories¶

Le nombre et la taille de vos fixtures vont croissant avec la taille votre application. Il est possible qu’à un certain point, vous ne soyez plus en mesure de les maintenir et de suivre leur contenu.

Le plugin fixture factories propose une alternative efficace pour des applications de grande taille.

Le plugin utilise le plugin test suite light pour tronquer avant chaque test toutes les tables modifiées.

Cette commande bake vous aidera créer vos factories:

bin/cake bake fixture_factory -h

Une fois vos factories mises en place, vous voilà équipés pour créer vos fixtures de test à une vitesse folle.

Les interactions inutiles avec la base de donnée vont ralentir les tests ainsi que votre application. Il est possible de créer des fixtures sans les insérer. Ceci est utile lorsque vous testez des méthodes qui n’interagissent pas avec la base de donnée:

$article = ArticleFactory::make()->getEntity();

Pour insérer dans la base de donnée:

$article = ArticleFactory::make()->persist();

Les factories peuvent aussi aider à créer des fixtures associées. En supposant que les Articles belongs to many Authors, il est possible de créer 5 articles ayant chacun 2 auteurs de la manière suivante:

$articles = ArticleFactory::make(5)->with('Authors', 2)->getEntities();

Notez que bien que les factories ne nécessitent ni création, ni déclaration de fixtures. Elles sont toujours parfaitement compatibles avec les fixtures qui viennent de CakePHP. Pour plus de détails, rendez-vous ici.

Charger des Routes dans les Tests¶

Si vous testez des mailers, des components de controllers ou d’autres classes qui ont besoin de routes et de résoudre des URLs, vous aurez besoin de charger des routes. Pendant le setUp() d’une classe ou pendant les méthodes de tests individuelles vous pouvez utiliser loadRoutes() pour vous assurer que les routes de votre application sont chargées:

public function setUp(): void
{
    parent::setUp();
    $this->loadRoutes();
}

Cette méthode construira une instance de votre Application et appellera la méthode routes() dessus. Si votre classe Application a besoin de paramètres spécialisés dans le constructeur, vous pouvez les fournir dans loadRoutes($constructorArgs).

Création de routes dans les tests¶

Parfois, il peut être nécessaire d’ajouter dynamiquement des routes dans les tests, par exemple lors du développement de plugins, ou d’applications qui sont extensibles.

Tout comme le chargement de routes d’applications existantes, ceci peut être fait pendant setup() d’une méthode de test, et/ou dans les méthodes de test individuelles elles-mêmes:

use Cake\Routing\Route\DashedRoute;
use Cake\Routing\RouteBuilder;
use Cake\Routing\Router;
use Cake\TestSuite\TestCase;

class PluginHelperTest extends TestCase
{
    protected RouteBuilder $routeBuilder;

    public function setUp(): void
    {
        parent::setUp();

        $this->routeBuilder = Router::createRouteBuilder('/');
        $this->routeBuilder->scope('/', function (RouteBuilder $routes) {
            $routes->setRouteClass(DashedRoute::class);
            $routes->get(
                '/test/view/{id}',
                ['controller' => 'Tests', 'action' => 'view']
            );
            // ...
        });

        // ...
    }
}

Ceci créera une nouvelle instance de route builder qui fusionnera les routes connectées dans la même collection de routes utilisée par toutes les autres instances de route builder qui qui peuvent déjà exister, ou qui doivent encore être créées dans l’environnement.

Charger des Plugins dans les Tests¶

Si votre application est censée charger des plugins dynamiquement, vous pouvez utiliser loadPlugins() pour charger un ou plusieurs plugins pendant les tests:

public function testMethodUsingPluginResources()
{
    $this->loadPlugins(['Company/Cms']);
    // Tester la logique qui nécessite d'avoir chargé Company/Cms.
}

Créer une Méthode de Test¶

Ajoutons maintenant une méthode pour tester la fonction published() dans la table Articles. Modifions le fichier tests/TestCase/Model/Table/ArticlesTableTest.php afin qu’il ressemble maintenant à ceci:

namespace App\Test\TestCase\Model\Table;

use App\Model\Table\ArticlesTable;
use Cake\TestSuite\TestCase;

class ArticlesTableTest extends TestCase
{
    protected $fixtures = ['app.Articles'];

    public function setUp(): void
    {
        parent::setUp();
        $this->Articles = $this->getTableLocator()->get('Articles');
    }

    public function testFindPublished(): void
    {
        $query = $this->Articles->find('published')->all();
        $this->assertInstanceOf('Cake\ORM\Query', $query);
        $result = $query->enableHydration(false)->toArray();
        $expected = [
            ['id' => 1, 'title' => 'Premier Article'],
            ['id' => 2, 'title' => 'Deuxième Article'],
            ['id' => 3, 'title' => 'Troisième Article']
        ];

        $this->assertEquals($expected, $result);
    }
}

Vous pouvez voir que nous avons ajouté une méthode appelée testFindPublished(). Nous commençons par créer une instance de notre classe ArticleTable, et lançons ensuite notre méthode find('published'). Dans $expected, nous définissons ce qui devrait être le résultat approprié (que nous connaissons puisque nous avons défini les enregistrements qui sont remplis initialement dans la table articles). Nous testons si les résultats correspondent à nos attentes en utilisant la méthode assertEquals(). Lisez la section sur les Lancer les Tests pour plus d’informations sur la façon de lancer les cas de test.

En utilisant les fixture factories, le test se présenterait ainsi:

namespace App\Test\TestCase\Model\Table;

use App\Test\Factory\ArticleFactory;
use Cake\TestSuite\TestCase;

class ArticlesTableTest extends TestCase
{
    public function testFindPublished(): void
    {
        // Insérer 3 articles publiés
        $articles = ArticleFactory::make(['published' => 1], 3)->persist();
        // Insérer 2 articles non publiés
        ArticleFactory::make(['published' => 0], 2)->persist();

        $result = ArticleFactory::find('published')->find('list')->toArray();

        $expected = [
            $articles[0]->id => $articles[0]->title,
            $articles[1]->id => $articles[1]->title,
            $articles[2]->id => $articles[2]->title,
        ];

        $this->assertEquals($expected, $result);
    }
}

Aucune fixture n’a besoin d’être déclarée. Les 5 articles créés n’existeront que dans ce test. La méthode statique ::find() va requêter la base de donnée sans utiliser la table ArticlesTable ni ses évènements.

Méthodes de Mocking des Models¶

Il y aura des fois où vous voudrez mocker les méthodes des models quand vous les testez. Vous devrez utiliser getMockForModel pour créer des mocks de test des classes de tables. Cela évite des problèmes avec les propriétés réfléchies qu’ont les mocks normaux:

public function testSendingEmails(): void
{
    $model = $this->getMockForModel('EmailVerification', ['send']);
    $model->expects($this->once())
        ->method('send')
        ->will($this->returnValue(true));

    $model->verifyEmail('[email protected]');
}

Dans votre méthode tearDown(), assurez-vous de retirer le mock avec ceci:

$this->getTableLocator()->clear();

Configurer la Requête¶

Le trait IntegrationTestTrait comporte de nombreux helpers pour configurer les requêtes que vous allez envoyer à l’application testée:

// Définit des cookies
$this->cookie('name', 'Oncle Bob');

// Définit des données de session
$this->session(['Auth.User.id' => 1]);

// Configure les en-têtes
$this->configRequest([
    'headers' => ['Accept' => 'application/json']
]);

Les états définis par les méthodes de cet utilitaire sont remis à zéro dans la méthode tearDown().

Tester Des Actions Qui Nécessitent Une Authentification¶

Si vous utilisez AuthComponent, vous aurez besoin de simuler les données de session utilisées par AuthComponent pour valider l’identité d’un utilisateur. Pour ce faire, vous pouvez utiliser les méthodes utilitaires fournies par IntegrationTestTrait. En admettant que vous ayez un ArticlesController qui contient une méthode add, et que cette méthode nécessite une authentification, vous pourriez écrire les tests suivants:

public function testAddUnauthenticatedFails(): void
{
    // Pas de données de session définies.
    $this->get('/articles/add');

    $this->assertRedirect(['controller' => 'Users', 'action' => 'login']);
}

public function testAddAuthenticated(): void
{
    // Définit des données de session
    $this->session([
        'Auth' => [
            'User' => [
                'id' => 1,
                'username' => 'testing',
                // autres clés.
            ]
        ]
    ]);
    $this->get('/articles/add');

    $this->assertResponseOk();
    // Autres assertions.
}

Test de l’Authentification Stateless (sans état) et des APIs¶

Pour tester les APIs qui utilisent une authentification stateless, telles que l’authentification Basic, vous pouvez configurer la requête de manière à y injecter des variables d’environnement et des en-têtes qui vont simuler de vraies en-têtes d’authentification.

Lorsque vous testez les authentifications Basic ou Digest, vous pouvez ajouter les variables d’environnement créées automatiquement par PHP <https://php.net/manual/fr/features.http-auth.php> `_. Ces variables d’environnement utilisées dans l’adaptateur d’authentification sont décrites dans: ref: `basic-authentication

public function testBasicAuthentication(): void
{
    $this->configRequest([
        'environment' => [
            'PHP_AUTH_USER' => 'username',
            'PHP_AUTH_PW' => 'password',
        ]
    ]);

    $this->get('/api/posts');
    $this->assertResponseOk();
}

Si vous testez d’autres types d’authentification, tel que OAuth2, vous pouvez définir l’en-tête d’autorisation directement:

public function testOauthToken(): void
{
    $this->configRequest([
        'headers' => [
            'authorization' => 'Bearer: oauth-token'
        ]
    ]);

    $this->get('/api/posts');
    $this->assertResponseOk();
}

Vous pouvez utiliser la clé headers dans configRequest() pour configurer n’importe quelle autre en-tête HTTP dont vous auriez besoin pour cette action.

Tester les Actions Protégées par CsrfProtectionMiddleware ou FormProtectionComponent¶

Quand vous testez des actions protégées par CsrfProtectionMiddleware ou FormProtectionComponent, vous pouvez activer la génération automatique de token pour vous assurer que vos tests ne vont pas échoué à cause d’un problème de token:

public function testAdd(): void
{
    $this->enableCsrfToken();
    $this->enableSecurityToken();
    $this->post('/posts/add', ['title' => 'News excitante!']);
}

Il est aussi important d’activer le débogage dans les tests qui utilisent des tokens pour éviter que le FormProtectionComponent ne pense que le token de débogage est utilisé dans un environnement non-debug. Quand vous faites des tests avec d’autres méthodes comme requireSecure(), vous pouvez utiliser configRequest() pour définir les bonnes variables d’environnement:

// Fake out SSL connections.
$this->configRequest([
    'environment' => ['HTTPS' => 'on']
]);

Si votre action a besoin de champs déverrouillés vous pouvez les déclarer avec setUnlockedFields():

$this->setUnlockedFields(['dynamic_field']);

Test d’intégration sur les middlewares PSR-7¶

Les tests d’intégration peuvent aussi être utilisés pour tester entièrement vos applications PSR-7 et les Middleware. Par défaut, IntegrationTestTrait détectera automatiquement la présence d’une classe App\Application et activera automatiquement les tests d’intégration sur votre Application.

Vous pouvez personnaliser le nom de la classe Application utilisée ainsi que les arguments du contructeur, en utilisant la méthode configApplication():

public function setUp(): void
{
    $this->configApplication('App\App', [CONFIG]);
}

Vous devriez également faire en sorte d’utiliser Application::bootstrap() pour charger les plugins qui contiennent des événements ou des routes. De cette manière, vous vous assurez que les événements et les routes seront connectés pour tous vos test cases.

Tester avec des Cookies Cryptés¶

Si vous utilisez le Middleware de Gestion de Cookies Chiffrés dans votre application, il y a des méthodes pratiques pour définir des cookies chiffrés dans vos test cases:

// Définit un cookie en utilisant AES et la clé par défaut.
$this->cookieEncrypted('mon_cookie', 'Des valeurs secrètes');

// Partons du principe que cette action modifie le cookie.
$this->get('/bookmarks/index');

$this->assertCookieEncrypted('Une nouvelle valeur', 'mon_cookie');

Tester les Messages Flash¶

Si vous souhaitez faire une assertion sur la présence de messages Flash en session et pas sur le rendu du HTML, vous pouvez utiliser enableRetainFlashMessages() dans vos tests pour que les messages Flash soient conservés dans la session et que vous puissez ainsi effectuer vos assertions:

// Active la rétention des messages flash plutôt que leur consommation
$this->enableRetainFlashMessages();
$this->get('/bookmarks/delete/9999');

$this->assertSession("Ce marque-page n'existe pas", 'Flash.flash.0.message');

// Vérifie un message flash sous la clé 'flash'.
$this->assertFlashMessage('Marque-page supprimé', 'flash');

// Vérifie le deuxième message flash, également sous la clé 'flash'.
$this->assertFlashMessageAt(1, 'Marque-page vraiment supprimé');

// Vérifie un message flash en première position sous la clé 'auth'
$this->assertFlashMessageAt(0, "Vous n'avez pas le droit d'entrer dans ce donjon !", 'auth');

// Vérifie qu'un message flash utilise l'élément error
$this->assertFlashElement('Flash/error');

// Vérifie l'élément du deuxième message flash
$this->assertFlashElementAt(1, 'Flash/error')

Tester un Controller Retournant du JSON¶

JSON est un format commun et agréable à utiliser lors de la conception d’un service web. Avec CakePHP, il est très simple de tester les terminaux de votre service web. Commençons avec un exemple simple de controller qui renvoie du JSON:

use Cake\View\JsonView;

class MarkersController extends AppController
{
    public function viewClasses(): array
    {
        return [JsonView::class];
    }

    public function view($id)
    {
        $marker = $this->Markers->get($id);
        $this->set('marker', $marker);
        $this->viewBuilder()->setOption('serialize', ['marker']);
    }
}

Créons maintenant le fichier tests/TestCase/Controller/MarkersControllerTest.php et assurons-nous que le web service répond correctement:

class MarkersControllerTest extends IntegrationTestCase
{
    public function testGet(): void
    {
        $this->configRequest([
            'headers' => ['Accept' => 'application/json']
        ]);
        $result = $this->get('/markers/view/1.json');

        // Vérification que la réponse était bien une 200
        $this->assertResponseOk();

        $expected = [
            ['id' => 1, 'lng' => 66, 'lat' => 45],
        ];
        $expected = json_encode($expected, JSON_PRETTY_PRINT);
        $this->assertEquals($expected, (string)$this->_response->getBody());
    }
}

Nous utilisons l’option JSON_PRETTY_PRINT car la vue JsonView intégrée à CakePHP utilise cette option quand le mode debug est activé.

Test avec Téléversement de Fichiers¶

La simulation d’un téléversement de fichiers est enfantine lorsque vous utilisez le mode par défaut de « téléversement de fichiers en tant qu’objets ». Vous pouvez créer tout simplement des instances qui implémentent \Psr\Http\Message\UploadedFileInterface (l’implémentation par défaut actuellement utilisée par CakePHP est \Laminas\Diactoros\UploadedFile), et les passer dans les données de vos requêtes de test. Dans l’environnement CLI, ces objets passeront par défaut les contrôles de validation qui testent si le fichier a été téléversé via HTTP. Il n’en va pas de même pour les données de type tableau comme celles que l’on trouve dans $_FILES ; ce contrôle échouerait.

Afin de simuler exactement la façon dont les objets de fichiers téléversés seraient présents dans une requête normale, vous devez non seulement les passer dans les données de la requête, mais aussi les passer dans la configuration de la requête de test via l’option files. Ce n’est toutefois pas techniquement nécessaire, sauf si votre code accède aux fichiers téléversés via les méthodes Cake\Http\ServerRequest::getUploadedFile() ou Cake\Http\ServerRequest::getUploadedFiles().

Supposons que les articles aient une image d’accroche, et une association Articles hasMany Attachments. Le formulaire ressemblerait à quelque chose comme ceci en conséquence, où un fichier image et plusieurs fichiers ou pièces jointes seraient acceptés:

<?= $this->Form->create($article, ['type' => 'file']) ?>
<?= $this->Form->control('title') ?>
<?= $this->Form->control('teaser_image', ['type' => 'file']) ?>
<?= $this->Form->control('attachments.0.attachment', ['type' => 'file']) ?>
<?= $this->Form->control('attachments.0.description']) ?>
<?= $this->Form->control('attachments.1.attachment', ['type' => 'file']) ?>
<?= $this->Form->control('attachments.1.description']) ?>
<?= $this->Form->button('Submit') ?>
<?= $this->Form->end() ?>

Le test qui simulerait la requête correspondante pourrait ressembler à ceci:

public function testAddWithUploads(): void
{
    $teaserImage = new \Laminas\Diactoros\UploadedFile(
        '/path/to/test/file.jpg', // flux ou chemin d'accès au fichier représentant le fichier temporaire
        12345,                    // la taille du fichier en octets
        \UPLOAD_ERR_OK,           // le statut de téléversement ou d'erreur
        'teaser.jpg',             // le nom du fichier tel qu'il aurait été envoyé par le client
        'image/jpeg'              // le type mime tel qu'il aurait été envoyé par le client
    );

    $textAttachment = new \Laminas\Diactoros\UploadedFile(
        '/path/to/test/file.txt',
        12345,
        \UPLOAD_ERR_OK,
        'attachment.txt',
        'text/plain'
    );

    $pdfAttachment = new \Laminas\Diactoros\UploadedFile(
        '/path/to/test/file.pdf',
        12345,
        \UPLOAD_ERR_OK,
        'attachment.pdf',
        'application/pdf'
    );

    // Voici les données accessibles via `$this->request->getUploadedFile()`
    // et `$this->request->getUploadedFiles()`.
    $this->configRequest([
        'files' => [
            'teaser_image' => $teaserImage,
            'attachments' => [
                0 => [
                    'attachment' => $textAttachment,
                ],
                1 => [
                    'attachment' => $pdfAttachment,
                ],
            ],
        ],
    ]);

    // Voici les données accessibles via `$this->request->getData()`.
    $postData = [
        'title' => 'Nouvel Article',
        'teaser_image' => $teaserImage,
        'attachments' => [
            0 => [
                'attachment' => $textAttachment,
                'description' => 'Fichier texte',
            ],
            1 => [
                'attachment' => $pdfAttachment,
                'description' => 'Fichier PDF',
            ],
        ],
    ];
    $this->post('/articles/add', $postData);

    $this->assertResponseOk();
    $this->assertFlashMessage("L'article a été sauvegardé avec succès");
    $this->assertFileExists('/path/to/uploads/teaser.jpg');
    $this->assertFileExists('/path/to/uploads/attachment.txt');
    $this->assertFileExists('/path/to/uploads/attachment.pdf');
}

De même, vous pouvez simuler des erreurs de téléversement ou d’autres fichiers invalides qui ne passent pas la validation:

public function testAddWithInvalidUploads(): void
{
    $missingTeaserImageUpload = new \Laminas\Diactoros\UploadedFile(
        '',
        0,
        \UPLOAD_ERR_NO_FILE,
        '',
        ''
    );

    $uploadFailureAttachment = new \Laminas\Diactoros\UploadedFile(
        '/path/to/test/file.txt',
        1234567890,
        \UPLOAD_ERR_INI_SIZE,
        'attachment.txt',
        'text/plain'
    );

    $invalidTypeAttachment = new \Laminas\Diactoros\UploadedFile(
        '/path/to/test/file.exe',
        12345,
        \UPLOAD_ERR_OK,
        'attachment.exe',
        'application/vnd.microsoft.portable-executable'
    );

    $this->configRequest([
        'files' => [
            'teaser_image' => $missingTeaserImageUpload,
            'attachments' => [
                0 => [
                    'file' => $uploadFailureAttachment,
                ],
                1 => [
                    'file' => $invalidTypeAttachment,
                ],
            ],
        ],
    ]);

    $postData = [
        'title' => 'Nouvel Article',
        'teaser_image' => $missingTeaserImageUpload,
        'attachments' => [
            0 => [
                'file' => $uploadFailureAttachment,
                'description' => 'Pièce jointe en échec de téléversement',
            ],
            1 => [
                'file' => $invalidTypeAttachment,
                'description' => 'Pièce jointe de type invalide',
            ],
        ],
    ];
    $this->post('/articles/add', $postData);

    $this->assertResponseOk();
    $this->assertFlashMessage("L'article n'a pas pu être sauvegardé");
    $this->assertResponseContains("Une image d'accroche est nécessaire");
    $this->assertResponseContains('Dépassement de la taille maximale autorisée des fichiers');
    $this->assertResponseContains('Type de fichier non supporté');
    $this->assertFileNotExists('/path/to/uploads/teaser.jpg');
    $this->assertFileNotExists('/path/to/uploads/attachment.txt');
    $this->assertFileNotExists('/path/to/uploads/attachment.exe');
}

Désactiver le Middleware de Gestion d’Erreurs dans les Tests¶

Quand vous déboguez des tests qui échouent parce que votre application rencontre des erreurs, il peut être utile de désactiver temporairement le middleware de gestion des erreurs pour permettre aux erreurs de remonter. Pour cela, vous pouvez utiliser la méthode disableErrorHandlerMiddleware():

public function testGetMissing(): void
{
    $this->disableErrorHandlerMiddleware();
    $this->get('/markers/not-there');
    $this->assertResponseCode(404);
}

Dans l’exemple ci-dessus, le test échouera et le message d’exception et la stack-trace seront affichés à la place de la page d’erreur de l’application.

Méthodes d’Assertion¶

Le trait IntegrationTestTrait fournit de nombreuses méthodes d’assertions afin de tester les réponses plus simplement. Quelques exemples:

// Vérifie un code de réponse 2xx
$this->assertResponseOk();

// Vérifie un code de réponse 2xx/3xx
$this->assertResponseSuccess();

// Vérifie un code de réponse 4xx
$this->assertResponseError();

// Vérifie un code de réponse 5xx
$this->assertResponseFailure();

// Vérifie un code de réponse spécifique, par exemple 200
$this->assertResponseCode(200);

// Vérifie l'en-tête Location
$this->assertRedirect(['controller' => 'Articles', 'action' => 'index']);

// Vérifie qu'aucun en-tête Location n'a été envoyé
$this->assertNoRedirect();

// Vérifie une partie de l'en-tête Location
$this->assertRedirectContains('/articles/edit/');

// Vérifie que l'en-tête location ne contient pas...
$this->assertRedirectNotContains('/articles/edit/');

// Vérifie que le contenu de la réponse n'est pas vide
$this->assertResponseNotEmpty();

// Vérifie que le contenu de la réponse est vide
$this->assertResponseEmpty();

// Vérifie le contenu de la réponse
$this->assertResponseEquals('Ouais !');

// Vérifie que le contenu de la réponse n'est pas égal à...
$this->assertResponseNotEquals('Non !');

// Vérifie un contenu partiel de la réponse
$this->assertResponseContains("C'est gagné !");
$this->assertResponseNotContains("Encore raté !");

// Vérifie un fichier renvoyé
$this->assertFileResponse('/chemin/absolu/vers/le/fichier.ext');

// Vérifie le layout
$this->assertLayout('default');

// Vérifie quel Template a été rendu (s'il y en a un)
$this->assertTemplate('index');

// Vérifie les données de la session
$this->assertSession(1, 'Auth.User.id');

// Vérifie l'en-tête de la réponse.
$this->assertHeader('Content-Type', 'application/json');
$this->assertHeaderContains('Content-Type', 'html');

// Vérifie que l'en-tête de la réponse ne contient pas de xml
$this->assertHeaderNotContains('Content-Type', 'xml');

// Vérifie le contenu d'une variable.
$user =  $this->viewVariable('user');
$this->assertEquals('jose', $user->username);

// Vérifie les cookies.
$this->assertCookie('1', 'thingid');

// Vérifie le type de contenu
$this->assertContentType('application/json');

En plus des méthodes d’assertion ci-dessus, vous pouvez également utiliser toutes les assertions de TestSuite et celles de PHPUnit.

Comparer les Résultats du Test avec un Fichier¶

Pour certains types de test, il peut être plus simple de comparer les résultats d’un test avec le contenu d’un fichier - par exemple, quand vous testez le rendu d’une vue. StringCompareTrait ajoute une méthode d’assertion simple pour cela.

Pour l’utiliser, vous devez inclure le trait, définir le répertoire contenant le fichier servant de base de comparaison et appeler assertSameAsFile:

use Cake\TestSuite\StringCompareTrait;
use Cake\TestSuite\TestCase;

class SomeTest extends TestCase
{
    use StringCompareTrait;

    public function setUp(): void
    {
        $this->_compareBasePath = APP . 'tests' . DS . 'comparisons' . DS;
        parent::setUp();
    }

    public function testExample(): void
    {
        $result = ...;
        $this->assertSameAsFile('example.php', $result);
    }
}

Cet exemple va comparer $result au contenu du fichier APP/tests/comparisons/example.php.

Il existe un mécanisme pour écrire/mettre à jour les fichiers de test, en définissant la variable d’environment UPDATE_TEST_COMPARISON_FILES, ce qui va créer et/ou mettre à jour les fichiers de comparaison de test dès qu’ils seront référencés:

phpunit
...
FAILURES!
Tests: 6, Assertions: 7, Failures: 1

UPDATE_TEST_COMPARISON_FILES=1 phpunit
...
OK (6 tests, 7 assertions)

git status
...
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#   modified:   tests/comparisons/example.php