Tutoriel pour apprendre à utiliser le framework Laravel 5.3

Laravel utilise PHPUnit pour effectuer les tests. C'est un framework créé par Sebastian Bergmann qui fonctionne à partir d'assertions.

Ce framework est installé comme dépendance de Laravel en mode développement :

"require-dev": {
    "fzaninotto/faker": "~1.4",
    "mockery/mockery": "0.9.*",
    "phpunit/phpunit": "~5.0",
    "symfony/css-selector": "3.1.*",
    "symfony/dom-crawler": "3.1.*"
},

Mais vous pouvez aussi utiliser le fichier phar que vous pouvez trouver sur cette page et le placer à la racine de votre application et vous êtes prêt à tester !

La version 5 de PHPUnit nécessite au minimum PHP 5.6

Vous pouvez vérifier que ça fonctionne en entrant cette commande :

php phpunit(numéro de version).phar -h

Vous obtenez ainsi la liste de toutes les commandes disponibles.

Si vous utilisez la version installée avec Laravel ça donne :

php vendor\phpunit\phpunit\phpunit -h

Je vous conseille de vous faire un alias !

Il y a aussi la possibilité d'utiliser les fichiers placés dans le dossier vendor/bin.

Dans tous les exemples de ce chapitre j'utiliserai le fichier phar.

Si vous regardez les dossiers de Laravel vous allez en trouver un qui est consacré aux tests :

Vous avez déjà deux fichiers. Voilà le code de TestCase.php :

<?php
 
abstract class TestCase extends Illuminate\Foundation\Testing\TestCase
{
    /**
     * The base URL to use while testing the application.
     *
     * @var string
     */
    protected $baseUrl = 'http://localhost';
 
    /**
     * Creates the application.
     *
     * @return \Illuminate\Foundation\Application
     */
    public function createApplication()
    {
        $app = require __DIR__.'/../bootstrap/app.php';
 
        $app->make(Illuminate\Contracts\Console\Kernel::class)->bootstrap();
 
        return $app;
    }
}

Cette classe est chargée de créer une application pour les tests dans un environnement spécifique (ce qui permet de mettre en place une configuration adaptée aux tests).

Elle étend la classe Illuminate\Foundation\Testing\TestCase qui elle-même étend la classe PHPUnit_Framework_TestCase en lui ajoutant quelques fonctionnalités bien pratiques, comme nous allons le voir.

Toutes les classes de test que vous allez créer devront étendre cette classe TestCase.

Il y a un exemple de test déjà présent ExampleTest.php :

<?php
 
use Illuminate\Foundation\Testing\WithoutMiddleware;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Illuminate\Foundation\Testing\DatabaseTransactions;
 
class ExampleTest extends TestCase
{
    /**
     * A basic functional test example.
     *
     * @return void
     */
    public function testBasicExample()
    {
        $this->visit('/')
             ->see('Laravel');
    }
}

Sans entrer pour le moment dans le code sachez simplement que l'on envoie une requête pour la route de base et que l'on attend une réponse. Pour lancer ce test c'est très simple, entrez cette commande :

On voit qu'un test et deux assertions ont été effectués et que tout s'est bien passé.

Je vous ai dit que les tests s'effectuent dans un environnement particulier, ce qui est bien pratique.

Où se trouve cette configuration ?

Regardez le fichier phpunit.xml :

<?xml version="1.0" encoding="UTF-8"?>
<phpunit backupGlobals="false"
         backupStaticAttributes="false"
         bootstrap="bootstrap/autoload.php"
         colors="true"
         convertErrorsToExceptions="true"
         convertNoticesToExceptions="true"
         convertWarningsToExceptions="true"
         processIsolation="false"
         stopOnFailure="false">
    <testsuites>
        <testsuite name="Application Test Suite">
            <directory suffix="Test.php">./tests</directory>
        </testsuite>
    </testsuites>
    <filter>
        <whitelist processUncoveredFilesFromWhitelist="true">
            <directory suffix=".php">./app</directory>
        </whitelist>
    </filter>
    <php>
        <env name="APP_ENV" value="testing"></env>
        <env name="CACHE_DRIVER" value="array"></env>
        <env name="SESSION_DRIVER" value="array"></env>
        <env name="QUEUE_DRIVER" value="sync"></env>
    </php>
</phpunit>

On trouve déjà quatre variables d'environnement :

• APP_ENV : là on dit que l'on est en mode testing ;
• CACHE_DRIVER : en mode array ce qui signifie que l'on ne va rien mettre en cache pendant les tests (par défaut on a file) ;
• SESSION_DRIVER : en mode array ce qui signifie que l'on ne va pas faire persister la session (par défaut on a file) ;
• QUEUE_DRIVER : je n'évoque pas les tâches dans ce cours, on ne va donc pas tenir compte de cette variable.

On peut évidemment ajouter les variables dont on a besoin. Par exemple, si pendant les tests je ne veux plus MySql mais sqlite.

Il y a une variable dans config/database.php :

'default' => env('DB_CONNECTION', 'mysql'),

Il faut donc la renseigner dans .env :

DB_CONNECTION=mysql

Du coup dans phpunit.xml je peux écrire :

<env name="DB_CONNECTION" value="sqlite"/>

Maintenant pour les tests je vais utiliser sqlite.

Pour construire un test on procède généralement en trois étapes :

1. On initialise les données ;
2. On agit sur ces données ;
3. On vérifie que le résultat est conforme à notre attente.

Comme tout ça est un peu abstrait prenons un exemple. Remplaçons le code de la méthode testBasicExample par celui-ci :

public function testBasicExample()
{
    $data = [10, 20, 30];
    $result = array_sum($data);
    $this->assertEquals(60, $result);
}

On trouve nos trois étapes. On initialise les données :

$data = [10, 20, 30];

On agit sur ces données :

$result = array_sum($data);

On teste le résultat :

$this->assertEquals(60, $result);

La méthode assertEquals permet de comparer deux valeurs, ici 60 et $result. Si vous lancez le test vous obtenez :

Vous voyez à nouveau l'exécution d'un test et d'une assertion. Le tout s'est bien passé. Changez la valeur 60 par une autre et vous obtiendrez ceci :

Vous connaissez maintenant le principe de base d'un test et ce que l'on peut obtenir comme renseignement en cas d'échec.

Les assertions constituent l'outil de base des tests. On en a vu une ci-dessus et il en existe bien d'autres. Vous pouvez en trouver la liste complète ici.

Voici quelques assertions et l'utilisation d'un helper de Laravel que l'on teste au passage :

public function testBasicExample()
{
    $data = 'Je suis petit';
    $this->assertTrue(starts_with($data, 'Je'));
    $this->assertFalse(starts_with($data, 'Tu'));
    $this->assertSame(starts_with($data, 'Tu'), false);
    $this->assertStringStartsWith('Je', $data);
    $this->assertStringEndsWith('petit', $data);
}

Lorsqu'on lance le test on obtient ici :

Un test et cinq assertions correctes.

Il est facile d'appeler une route pour effectuer un test sur la réponse. Modifiez la route de base pour celle-ci :

Route::get('/', function()
{
    return 'coucou';
});

On a donc une requête avec l'URL de base et comme réponse la chaîne « coucou ». Nous allons tester que la requête aboutit bien, qu'il y a une réponse correcte et que la réponse est « coucou » :

public function testBasicExample()
{
    $response = $this->call('GET', '/');
    $this->assertResponseOk();
    $this->assertEquals('coucou', $response->getContent());
}

L'assertion assertResponseOk nous assure que la réponse est correcte. Ce n'est pas une assertion de PHPUnit mais une spécifique de Laravel. La méthode getContent permet de lire la réponse. On obtient :

Qu'en est-il si on retourne une vue ?

Mettez ce code pour la route :

Route::get('/', function()
{
    return view('welcome')->with('message', 'Vous y êtes !');
});

Ajoutez dans cette vue ceci :

{{ $message }}

Maintenant voici le test :

public function testBasicExample()
{
    $response = $this->call('GET', '/');
    $view = $response->original;
    $this->assertEquals('Vous y êtes !', $view['message']);
}

On envoie la requête et on récupère la réponse. Ensuite la méthode original nous permet de récupérer la vue. On peut alors tester la valeur de la variable $message dans la vue.

Laravel propose une autre assertion pour effectuer presque la même chose :

public function testBasicExample()
{
  $response = $this->call('GET', '/');
  $this->assertViewHas('message');
  $this->assertViewHas('message', 'Vous y êtes !');
}

L'assertion assertViewHas permet de vérifier qu'une vue reçoit bien une donnée, on peut aussi grâce au second paramètre vérifier sa valeur.

Créez ce contrôleur :

<?php
 
namespace App\Http\Controllers;
 
class WelcomeController extends Controller
{
    public function index()
    {
        return view('welcome');
    }
}

Vous pouvez tester facilement les actions d'un contrôleur.

Créez cette route pour mettre en œuvre le contrôleur ci-dessus :

Route::get('welcome', 'WelcomeController@index');

Vérifiez que ça fonctionne (vous aurez peut-être besoin de retoucher la vue où nous avons introduit une variable).

Supprimez le fichier ExampleTest.php qui ne va plus nous servir.

Créez cette architecture de dossiers et le fichier WelcomeControllerTest.php :

Et mettez ce code dans le fichier WelcomeControllerTest.php :

<?php
 
class WelcomeControllerTest extends TestCase
{
    public function testIndex()
    {
        $response = $this->action('GET', 'WelcomeController@index');
        $this->assertResponseOk();
    }
}

Il y a une commande d'artisan pour créer une classe de test :

php artisan make:test WelcomeControllerTest

Si vous lancez le test ça devrait bien se passer :

Donc pour appeler une action d'un contrôleur il suffit d'utiliser la méthode action et de préciser le verbe, le nom du contrôleur et le nom de la méthode associée.

D'autre part il est important de bien organiser les tests pour s'y retrouver. Une bonne façon de procéder est d'adopter la même architecture de dossiers que celle prévue pour l'application.

Nous allons voir maintenant comment l'utiliser mais pour cela on va mettre en place le code à tester. Ce ne sera pas trop réaliste, mais c'est juste pour comprendre le mécanisme de fonctionnement de Mockery. Remplacez le code du contrôleur WelcomeController par celui-ci :

<?php
 
namespace App\Http\Controllers;
 
use Livre;
 
class WelcomeController extends Controller
{
    public function __construct()
    {
        $this->middleware('guest');
    }
 
    public function index(Livre $livre)
    {
        $livres = $livre->all();
        return view('welcome', compact('livres'));
    }
}

J'ai prévu l'injection d'un modèle dans la méthode index. Ce n'est pas forcément très judicieux d'un point de vue conceptuel et il vaudrait mieux passer par un repository comme nous l'avons vu plusieurs fois dans ce cours mais on va prendre cette situation simple pour exécuter un test.

D'ailleurs la classe Livre n'a pas besoin de vraiment exister puisqu'on ne va pas vraiment l'utiliser.

La difficulté ici réside dans la présence de l'injection d'une classe. Comme on veut isoler les tests, l'idéal serait de pouvoir simuler cette classe. C'est justement ce que permet de faire Mockery.

Voici la classe de test que nous allons utiliser :

<?php
 
use Illuminate\Database\Eloquent\Collection;
 
class WelcomeControllerTest extends TestCase
{
    public function testIndex()
    {
        // Création de la collection
        $collection = new Collection;
        foreach (range(1, 2) as $i) {
            $collection->add((object) ['titre' => 'Titre' . $i]);
        }
 
        // Création Mock
        $mock = Mockery::mock('Livre');
        $mock ->shouldReceive('all')
              ->once()
              ->andReturn($collection);
 
        // Création lien
        $this->app->instance('Livre', $mock);
 
        // Action
        $response = $this->call('GET', 'welcome');
 
        // Assertions
        $this->assertResponseOk();
        $this->assertViewHas('livres');
 
    }
 
    public function tearDown()
    {
        Mockery::close();
    }
}

Et voici le code à ajouter dans la vue pour faire réaliste :

@foreach ($livres as $livre)
    <p>Titre : {{ $livre->titre }}</p>
@endforeach

Si je lance le test j'obtiens :

Un test et deux assertions correctes. Voyons de plus près ce code…

Au départ on crée une collection de livres :

// Création de la collection
$collection = new Collection;
foreach (range(1, 2) as $i) {
    $collection->add((object) ['titre' => 'Titre' . $i]);
}

On crée ensuite un objet Mock en lui demandant de simuler la classe Livre :

$mock = Mockery::mock('Livre');

Ensuite on définit le comportement que l'on désire pour cet objet :

$mock ->shouldReceive('all')
 ->once()
 ->andReturn($collection);

On lui dit que s'il reçoit l'appel de la méthode « all » (shouldReceive) une fois (once) il doit retourner la collection $collection (andReturn).

Ensuite on informe le conteneur de Laravel de la liaison entre la classe Livre et notre objet Mock :

$this->app->instance('Livre', $mock);

C'est une façon de dire à Laravel : chaque fois que tu auras besoin de la classe Livre tu iras plutôt utiliser l'objet Mock.

Ensuite on fait l'action, ici la requête :

$response = $this->call('GET', 'welcome');

Pour finir on prévoit deux assertions, une pour vérifier que l'on a une réponse correcte et la seconde pour vérifier que l'on a bien les livres dans la vue :

$this->assertResponseOk();
$this->assertViewHas('livres');

Pour finir on prévoit, pour travailler proprement, de supprimer l'objet Mock à l'issue du test dans la méthode tearDown qui sert justement à effecteur des actions après un test :

public function tearDown()
{
    Mockery::close();
}

Vous connaissez maintenant le principe de l'utilisation de Mockery. Il existe de vastes possibilités avec ce composant.

Il n'y a pas vraiment de règle quant à la constitution des tests, quant à ce qu'il faut tester ou pas. L'important est de comprendre comment les faire et de juger ce qui est utile ou pas selon les circonstances. Une façon efficace d'apprendre à réaliser des tests tout en comprenant mieux Laravel est de regarder comment ces tests ont été conçus.

On va commencer par quelque chose de simple avec HomeTest :

<?php
 
class HomeTest extends TestCase
{
    /**
     * Home page test
     *
     * @return void
     */
    public function testBasicExample()
    {
        $this->visit('/')
            ->see('Laravel 5')
            ->click('Home')
            ->see('Laravel 5');
    }
}

On a ces actions :

• on visite (visit) l'URL de base (‘/') ;
• on peut voir (see) « Laravel 5 » ;
• on clique (click) sur le lien « Home » ;
• on peut voir (see) « Laravel 5 ».

Vous voyez que l'on se met dans la peau d'un utilisateur devant l'application.

On peut aussi remplir et soumettre un formulaire, regardez ce code dans ContactTest :

<?php
public function testOk()
{
    $this->visit('/contact/create')
        ->type('Someone', 'name')
        ->type('someone@somewhere.com', 'email')
        ->type('A message', 'message')
        ->press('Send')
        ->see('Your message has been recorded')
        ->seeInDatabase('contacts', [
            'name' => 'Someone',
            'email' => 'someone@somewhere.com',
            'message' => 'A message'
        ]);
}

On a ces actions :

• visite (visit) de l'URL /contact/create ;
• entrée de Someone dans le contrôle name ;
• entrée de someone@somewhere.com dans le contrôle email ;
• entrée de A message dans le contrôle message ;
• action sur le bouton Send ;
• on peut voir (see) « Your message has been recorded » ;
• on peut voir que l'on a dans la base (seeInDatabase) les informations transmises.

On peut aussi tester le fonctionnement de la validation, par exemple pour les required pour le même formulaire :

public function testRequired()
{
    $this->visit('/contact/create')
        ->press('Send')
        ->see('The name field is required')
        ->see('The email field is required')
        ->see('The message field is required');
}

Vous voyez que tout ça se lit comme de la prose !

Vous pouvez aller voir le code des autres tests de l'application qui sont fondés sur le même principe.