Zend_Test_PHPUnit

Zend_Test_PHPUnit fournit un TestCase pour les applications MVC qui contient des assertions qui permettent de tester toute une variété de responsabilités. La manière la plus facile de comprendre ce qui peut être fait est de regarder l'exemple suivant.

Example #1 Exemple d'un TestCase d'une application de login

L'exemple suivant est un simple test pour un contrôleur UserController permettant de vérifier différentes choses :

Le formulaire de login doit être affiché aux utilisateurs non-authentifiés.
Quand un utilisateur se connecte, il doit être redirigé vers sa page de profil, et cette page doit affichée des infofrmations particulières.

Cet exemple particulier suppose différentes choses. Premièrement, la majeure partie de notre fichier d'amorçage a été déplacé dans un plugin. Ceci simplifie le paramétrage dans le cas des tests en spécifiant rapidement votre environnement, et ainsi vous permet d'amorcer votre application en une seule ligne. Ensuite, notre exemple suppose que le chargement automatique ("autoload") est activé donc nous n'avons pas à nous soucier de charger les classes appropriées (comme le bon contrôleur, le bon plugin, etc.)

class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{
    public function setUp()
    {
        $this->bootstrap = array($this, 'appBootstrap');
        parent::setUp();
    }
 
    public function appBootstrap()
    {
        $this->frontController->registerPlugin(
            new Bugapp_Plugin_Initialize('development')
        );
    }
 
    public function testCallWithoutActionShouldPullFromIndexAction()
    {
        $this->dispatch('/user');
        $this->assertController('user');
        $this->assertAction('index');
    }
 
    public function testIndexActionShouldContainLoginForm()
    {
        $this->dispatch('/user');
        $this->assertAction('index');
        $this->assertQueryCount('form#loginForm', 1);
    }
 
    public function testValidLoginShouldGoToProfilePage()
    {
        $this->request->setMethod('POST')
              ->setPost(array(
                  'username' => 'foobar',
                  'password' => 'foobar'
              ));
        $this->dispatch('/user/login');
        $this->assertRedirectTo('/user/view');
 
        $this->resetRequest()
             ->resetResponse();
        $this->request->setMethod('GET')
             ->setPost(array());
        $this->dispatch('/user/view');
        $this->assertRoute('default');
        $this->assertModule('default');
        $this->assertController('user');
        $this->assertAction('view');
        $this->assertNotRedirect();
        $this->assertQuery('dl');
        $this->assertQueryContentContains('h2', 'User: foobar');
    }
}

Cet exemple pourrait être écrit plus simplement : toutes les assertions ne sont pas nécessaires et sont fournies seulement à titre d'illustration. Cependant, il montre bien combien il est simple de tester vos applications.

Amorcer votre TestCase

Comme noté dans l'exemple de login, tous les tests MVC doivent étendre Zend_Test_PHPUnit_ControllerTestCase. Cette classe étend elle-même PHPUnit_Framework_TestCase, et vous fournit donc toute la structure et les assertions que vous attendez de PHPUnit - ainsi que quelques échafaudages et assertions spécifiques à l'implémentation MVC de Zend Framework.

Si vous voulez tester votre application MVC, vous devez d'abord l'amorcer ("bootstrap"). Il existe plusieurs manières pour faire ceci, toutes celles-ci s'articulent autour de la propriété publique $bootstrap.

Premièrement, et probablement le plus simple, créez simplement une instance de Zend_Application comme vous la souhaitez dans votre fichier index.php, et assignez la à la propriété $bootstrap. Typiquement, vous réaliserez ceci dans votre méthode setUp() ; vous devrez ensuite parent::setUp() :

class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{
    public function setUp()
    {
        // Assign and instantiate in one step:
        $this->bootstrap = new Zend_Application(
            'testing',
            APPLICATION_PATH . '/configs/application.ini'
        );
        parent::setUp();
    }
}

Deuxièmement, vous pouvez paramétrer cette propriété pour qu'elle pointe vers un fichier. Si vous faîtes ceci, le fichier ne doit pas distribuer le contrôleur frontal, mais seulement paramétrer celui-ci et faire tout réglage spécifique à votre application.

class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{
    public $bootstrap = '/chemin/vers/amorcage/fichier.php'
 
    // ...
}

Troisièmement, vous pouvez fournir un callback PHP qui doit être exécuter pour amorcer votre application. Cet exemple est montré dans l'exemple de login. Si le callback est une fonction ou une méthode statique, ceci peut être paramétrer au niveau de la classe :

class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{
    public $bootstrap = array('App', 'bootstrap');
 
    // ...
}

Dans le cas où une instance d'objet est nécessaire, nous recommandons de réaliser ceci dans votre méthode setUp() :

class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{
    public function setUp()
    {
        // Utilisez la méthode "start" de l'instance d'objet Bootstrap :
        $bootstrap = new Bootstrap('test');
        $this->bootstrap = array($bootstrap, 'start');
        parent::setUp();
    }
}

Notez l'appel de parent::setUp(); ceci est nécessaire puisque la méthode setUp() de Zend_Test_PHPUnit_ControllerTestCase exécutera le reste du processus d'amorçage (incluant l'appel du callback).

En utilisation normale, la méthode setUp() amorcera l'application. Ce premier processus inclue le nettoyage de l'environnement pour rendre un état de requête propre, va réinitialiser tout plugins ou aides, va réinitialiser l'instance du contrôleur frontal, et créer de nouveaux objets de requête et de réponse. Une fois ceci fait, la méthode va faire un include() du fichier spécifié dans $bootstrap, ou appeler le callback spécifié.

L'amorçage doit être le proche possible de ce que fera réellement votre application. Cependant, il y a plusieurs avertissements :

Ne fournissez pas d'implémentations alternatives des objets "Request" et "Response" ; ils ne seront pas utilisés. Zend_Test_PHPUnit_ControllerTestCase utilise des objets de requête et de réponse personnalisés, respectivement Zend_Controller_Request_HttpTestCase et Zend_Controller_Response_HttpTestCase. Ces objets fournissent des méthodes pour paramétrer l'environnement de requête dans le but souhaité, et récupérer les objets de réponse façonnés.
N'espérez pas faire des tests spécifiques de serveur. Autrement dit, ces tests ne garantissent pas que le code va s'exécuter sur un serveur avec une configuration spécifique, mais simplement que l'application va fonctionner comme souhaité si le routeur est capable de router une requête donnée. À cet effet, ne paramétrez pas d'en-têtes spécifiques au serveur dans l'objet de requête.

Une fois que votre application est amorcée, vous pouvez commencer à écrire vos tests.

Tester vos contrôleurs et vos applications MVC

Une fois , votre fichier d'amorçage en place, vous pouvez commencer à tester. Tester est typiquement ce que vous auriez pu faire avec une suite de test PHPUnit ("test suite"), avec quelques petites différences mineures.

Premièrement, vous devez distribuer l'URL à tester en utilisant la méthode dispatch() de TestCase :

class IndexControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{
    // ...
 
    public function testPageAccueil()
    {
        $this->dispatch('/');
        // ...
    }
}

Il y a des moments, cependant, où vous devez fournir des informations supplémentaires - des variables GET et POST, des informations de COOKIE, etc. Vous pouvez peupler la requête avec ces informations :

class FooControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{
    // ...
 
    public function testBarActionShouldReceiveAllParameters()
    {
        // Passer les variables GET :
        $this->request->setQuery(array(
            'foo' => 'bar',
            'bar' => 'baz',
        ));
 
        // Passer les variables POST :
        $this->request->setPost(array(
            'baz'  => 'bat',
            'lame' => 'bogus',
        ));
 
        // Paramètrer une valeur de cookie :
        $this->request->setCookie('user', 'matthew');
        // ou plusieurs :
        $this->request->setCookies(array(
            'timestamp' => time(),
            'host'      => 'foobar',
        ));
 
        // Ajouter des en-têtes :
        $this->request->setHeader('X-Requested-With', 'XmlHttpRequest');
 
        // Définir le type de requête :
        $this->request->setMethod('POST');
 
        // Distribuer :
        $this->dispatch('/foo/bar');
 
        // ...
    }
}

Maintenant que la requête est construite, il est temps de créer des assertions.

Controller Tests and the Redirector Action Helper

Important

The redirect action helper issues an exit() statement when using the method gotoAndExit() and will then obviously also stops a test running for this method. For testability of your application dont use that method on the redirector!

Due to its nature the redirector action helper plugin issues a redirect and exists after this. Because you cannot test parts of an application that issue exit calls Zend_Test_PHPUnit_ControllerTestCase automatically disables the exit part of the redirector which can cause different behaviours in tests and the real application. To make sure redirect work correctly you should it them in the following way:

class MyController extends Zend_Controller_Action
{
    public function indexAction()
    {
        if($someCondition == true) {
            return $this->_redirect(...);
        } else if($anotherCondition == true) {
            $this->_redirector->gotoSimple("foo");
            return;
        }
 
        // do some stuff here
    }
}

Important

Depending on your application this is not enough as additional action, preDispatch() or postDispatch() logic might be executed. This cannot be handled in a good way with Zend Test currently.

Assertions

Les assertions sont le coeur des tests unitaires; vous les utilisez pour vérifier que le résultat est bien celui que vous attendiez. A cette fin, Zend_Test_PHPUnit_ControllerTestCase fournit un certain nombre d'assertions pour simplifier le test de vos applications et contrôleurs MVC.

Les assertions par sélecteurs CSS

Les sélecteurs CSS sont une manière simple de vérifier que certaines constructions sont bien présentes dans le contenu de votre réponse. Cela rend aussi plus simple de s'assurer que les éléments nécessaires pour les librairies Javascript et/ou l'intégration d'AJAX sont présents ; la plupart des bibliothèques Javascript fournissent des mécanismes pour charger des éléments DOM sur la base des sélecteurs CSS, ainsi la syntaxe sera identique.

Cette fonctionnalité est fournie via Zend_Dom_Query, et intégré à un jeu d'assertions de type "Query*". Chacune de ces assertions prend un sélecteur CSS en tant que premier argument, avec optionnellement des arguments additionnels et/ou un message d'erreur, basé sur le type d'assertion. Vous pouvez trouver les règles d'écriture des électeurs CSS dans le chapitre Zend_Dom_Query - Aspect théorique. Les assertion "Query*" incluent :

assertQuery($path, $message = '') : vérifie qu'un ou plusieurs éléments DOM correspondant au sélecteur CSS fourni sont présents. Si un $message est présent, il sera ajouté en cas d'échec de l'assertion.
assertQueryContentContains($path, $match, $message = '') : vérifie qu'un ou plusieurs éléments DOM correspondant au sélecteur CSS fourni sont présents, et qu'au moins un de ceux-ci contient le contenu fournit dans $match. Si un $message est présent, il sera ajouté en cas d'échec de l'assertion.
assertQueryContentRegex($path, $pattern, $message = '') : vérifie qu'un ou plusieurs éléments DOM correspondant au sélecteur CSS fourni sont présents, et qu'au moins un de ceux-ci correspond à l'expression régulière fournie dans $pattern. Si un $message est présent, il sera ajouté en cas d'échec de l'assertion.
assertQueryCount($path, $count, $message = '') : vérifie qu'un nombre exact $count d'éléments DOM correspondant au sélecteur CSS fourni sont présents. Si un $message est présent, il sera ajouté en cas d'échec de l'assertion.
assertQueryCountMin($path, $count, $message = '') : vérifie qu'au moins un nombre $count d'éléments DOM correspondant au sélecteur CSS fourni sont présents. Si un $message est présent, il sera ajouté en cas d'échec de l'assertion. Note : spécifier une valeur de 1 pour $count est la même chose qu'un simple assertQuery().
assertQueryCountMax($path, $count, $message = '') : vérifie qu'il n'y a pas plus d'un nombre $count d'éléments DOM correspondant au sélecteur CSS fourni sont présents. Si un $message est présent, il sera ajouté en cas d'échec de l'assertion. Note : spécifier une valeur de 1 pour $count est la même chose qu'un simple assertQuery().

De plus, toutes les méthodes ci-dessus possèdent une variante "Not" qui correspond à l'assertion négative : assertNotQuery(), assertNotQueryContentContains(), assertNotQueryContentRegex(), et assertNotQueryCount(). (Notez que les versions CountMin et CountMax n'ont pas de variantes pour des raisons évidentes).

Les assertions XPath

Certains développeurs sont plus familiers avec XPath qu'avec des sélecteurs CSS, ainsi les variantes XPath des toutes les assertions Query sont aussi fournies. Il s'agit de :

assertXpath($path, $message = '')
assertNotXpath($path, $message = '')
assertXpathContentContains($path, $match, $message = '')
assertNotXpathContentContains($path, $match, $message = '')
assertXpathContentRegex($path, $pattern, $message = '')
assertNotXpathContentRegex($path, $pattern, $message = '')
assertXpathCount($path, $count, $message = '')
assertNotXpathCount($path, $count, $message = '')
assertXpathCountMin($path, $count, $message = '')
assertNotXpathCountMax($path, $count, $message = '')

Les assertions de redirections

Souvent une action va redirigé le visiteur. Plutôt que de suivre cette redirection, Zend_Test_PHPUnit_ControllerTestCase vous permet de tester ces redirections avec un jeu d'assertions :

assertRedirect($message = '') : vérifie simplement qu'une redirection est apparue.
assertNotRedirect($message = '') : vérifie qu'aucune redirection n'est apparue.
assertRedirectTo($url, $message = '') : vérifie qu'une redirection est apparue, et que la valeur de l'en-tête "Location" est l' $url fourni.
assertNotRedirectTo($url, $message = '') : vérifie soit qu'aucune redirection n'est apparue, ou que la valeur de l'en-tête "Location" n'est pas l' $url fourni.
assertRedirectRegex($pattern, $message = '') : vérifie qu'une redirection est apparue, et que la valeur de l'en-tête "Location" correspond à l'expression régulière fourni dans $pattern.
assertNotRedirectRegex($pattern, $message = '') : vérifie soit qu'aucune redirection n'est apparue, ou que la valeur de l'en-tête "Location" ne correspond pas à l'expression régulière fourni dans $pattern.

Les assertions d'en-têtes de réponses

En plus de vérifier les en-têtes de redirection, vous avez souvent besoin de vérifier des codes de réponse HTTP et des en-têtes spécifiques - par exemple, pour déterminer si une action entraînera une réponse 404 ou 500, ou pour s'assurer qu'une réponse JSON contient bien l'en-tête Content-Type approprié. Les assertions suivantes sont disponibles :

assertResponseCode($code, $message = '') : vérifie qu'une réponse renvoie le code de réponse HTTP fourni.
assertHeader($header, $message = '') : vérifie qu'une réponse renvoie l'en-tête fourni.
assertHeaderContains($header, $match, $message = '') : vérifie qu'une réponse renvoie l'en-tête fourni et que son contenu vaut la chaîne fournie.
assertHeaderRegex($header, $pattern, $message = '') : vérifie qu'une réponse renvoie l'en-tête fourni et que son contenu correspond à l'expression régulière fournie.

De plus, toutes les méthodes ci-dessus possèdent une variante "Not" qui correspond à l'assertion négative.

Les assertions de requêtes

Il est souvent pratique de vérifier l'action, le contrôleur et le module dernièrement exécuté ; ou, vous pouvez vouloir vérifier quelle route a été utilisée. Les assertions suivantes peuvent vous aider dans ce cas :

assertModule($module, $message = '') : vérifie que le module fourni a été utilisé lors de la dernière action distribuée.
assertController($controller, $message = '') : vérifie que le contrôleur fourni a été utilisé lors de la dernière action distribuée.
assertAction($action, $message = '') : vérifie que l'action fournie est bien la dernière distribuée.
assertRoute($route, $message = '') : vérifie que la route nommée fournie a été utilisée par le routeur.

De plus, toutes les méthodes ci-dessus possèdent une variante "Not" qui correspond à l'assertion négative.

Exemples

Savoir comment configurer votre infrastructure de tests et comment faire des assertions est seulement la moitié du travail ; maintenant il est temps de commencer à regarder quelques scénarios réels de test pour voir comment vous pouvez les étendre.

Example #2 Test d'un contrôleur "UserController"

Considérons une tâche habituelle d'un site Web : l'authentification et l'enregistrement d'utilisateurs. Dans notre exemple, nous avons défini un contrôleur "UserController" pour gérer ceci, il requiert le conditions suivantes :

Si un utilisateur n'est pas authentifié, il sera toujours redirigé vers la page de login, sans se soucier de l'action demandée.
La page avec le formulaire de login présente à la fois le formulaire de login et le formulaire d'enregistrement.
Fournir une identification invalide entraîne un retour au formulaire de login.
Une identification valide entraîne une redirection vers la page avec le profil de l'utilisateur.
La page de profil peut être personnalisée pour contenir le nom d'utilisateur.
Les utilisateurs déjà authentifiés qui accèdent à la page de login sont redirigés vers leur page de profil.
En cas de déconnexion, un utilisateur est redirigé vers la page de login.
Avec des données invalides, l'enregistrement doit entraîner un échec.

Nous pourrions, et devrions définir d'autres tests, mais ceux-ci suffiront pour l'instant.

Pour notre application, nous définirons un plugin "Initialize", qui fonctionne en routeStartup(). Ceci nous permet d'encapsuler notre fichier d'amorçage dans une interface POO, et qui nous permet aussi de fournir par une solution simple une fonction de rappel ("callback"). Regardons d'abord les bases de cette classe :

class Bugapp_Plugin_Initialize extends Zend_Controller_Plugin_Abstract
{
    /**
     * @var Zend_Config
     */
    protected static $_config;
 
    /**
     * @var string Current environment
     */
    protected $_env;
 
    /**
     * @var Zend_Controller_Front
     */
    protected $_front;
 
    /**
     * @var string Path to application root
     */
    protected $_root;
 
    /**
     * Constructor
     *
     * Initialize environment, root path, and configuration.
     *
     * @param  string $env
     * @param  string|null $root
     * @return void
     */
    public function __construct($env, $root = null)
    {
        $this->_setEnv($env);
        if (null === $root) {
            $root = realpath(dirname(__FILE__) . '/../../../');
        }
        $this->_root = $root;
 
        $this->initPhpConfig();
 
        $this->_front = Zend_Controller_Front::getInstance();
    }
 
    /**
     * Route startup
     *
     * @return void
     */
    public function routeStartup(Zend_Controller_Request_Abstract $request)
    {
        $this->initDb();
        $this->initHelpers();
        $this->initView();
        $this->initPlugins();
        $this->initRoutes();
        $this->initControllers();
    }
 
    // definition of methods would follow...
}

Ceci nous permet de créer un callback d'amorçage comme ce qui suit :

class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{
    public function appBootstrap()
    {
        $controller = $this->getFrontController();
        $controller->registerPlugin(
            new Bugapp_Plugin_Initialize('development')
        );
    }
 
    public function setUp()
    {
        $this->bootstrap = array($this, 'appBootstrap');
        parent::setUp();
    }
 
    // ...
}

Une fois ceci en place, nous pouvons écrire nos tests. Cependant, combien de ces tests nécessiteront qu'un utilisateur soit connecté ? La solution la plus simple est d'utiliser la logique de votre application pour faire ceci... et d'esquiver un peu par l'utilisation des méthodes resetResponse() et resetResponse(), qui vous permettront de distribuer une nouvelle requête.

class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{
    // ...
 
    public function loginUser($user, $password)
    {
        $this->request->setMethod('POST')
                      ->setPost(array(
                          'username' => $user,
                          'password' => $password,
                      ));
        $this->dispatch('/user/login');
        $this->assertRedirectTo('/user/view');
 
        $this->resetRequest()
             ->resetResponse();
 
        $this->request->setPost(array());
 
        // ...
    }
 
    // ...
}

Écrivons maintenant les tests :

class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{
    // ...
 
    public function testCallWithoutActionShouldPullFromIndexAction()
    {
        $this->dispatch('/user');
        $this->assertController('user');
        $this->assertAction('index');
    }
 
    public function testLoginFormShouldContainLoginAndRegistrationForms()
    {
        $this->dispatch('/user');
        $this->assertQueryCount('form', 2);
    }
 
    public function testInvalidCredentialsShouldResultInRedisplayOfLoginForm()
    {
        $request = $this->getRequest();
        $request->setMethod('POST')
                ->setPost(array(
                    'username' => 'bogus',
                    'password' => 'reallyReallyBogus',
                ));
        $this->dispatch('/user/login');
        $this->assertNotRedirect();
        $this->assertQuery('form');
    }
 
    public function testValidLoginShouldRedirectToProfilePage()
    {
        $this->loginUser('foobar', 'foobar');
    }
 
    public function testAuthenticatedUserShouldHaveCustomizedProfilePage()
    {
        $this->loginUser('foobar', 'foobar');
        $this->request->setMethod('GET');
        $this->dispatch('/user/view');
        $this->assertNotRedirect();
        $this->assertQueryContentContains('h2', 'foobar');
    }
 
    public function testAuthenticatedUsersShouldBeRedirectedToProfilePageWhenVisitingLoginPage()
    {
        $this->loginUser('foobar', 'foobar');
        $this->request->setMethod('GET');
        $this->dispatch('/user');
        $this->assertRedirectTo('/user/view');
    }
 
    public function testUserShouldRedirectToLoginPageOnLogout()
    {
        $this->loginUser('foobar', 'foobar');
        $this->request->setMethod('GET');
        $this->dispatch('/user/logout');
        $this->assertRedirectTo('/user');
    }
 
    public function testRegistrationShouldFailWithInvalidData()
    {
        $data = array(
            'username' => 'This will not work',
            'email'    => 'this is an invalid email',
            'password' => 'Th1s!s!nv@l1d',
            'passwordVerification' => 'wrong!',
        );
        $request = $this->getRequest();
        $request->setMethod('POST')
                ->setPost($data);
        $this->dispatch('/user/register');
        $this->assertNotRedirect();
        $this->assertQuery('form .errors');
    }
}

Notez que ces tests sont laconiques, et, pour la plupart, ne recherchent pas le contenu réel. Au lieu de cela, ils recherchent des objets construits dans la réponse - codes et en-têtes de réponse, et noeuds DOM. Ceci vous permet de vérifier que la structure est comme prévue - sans entraîner un échec dans vos tests à chaque fois qu'un contenu est ajouté au site.

Notez également que nous utilisons la structure du document dans nos essais. Par exemple, dans le test final, nous recherchons un formulaire qui a un noeud avec la classe "errors" ; ceci nous permet de déterminer simplement la présence des erreurs de validation de formulaire, et sans nous inquiéter de quelles erreurs spécifiques pourraient avoir été levées.

Cette application peut utiliser une base de données. Si oui, vous aurez besoin probablement d'un certain échafaudage pour s'assurer que la base de données est dans une configuration initiale et testable au début de chaque essai. PHPUnit fournit déjà une fonctionnalité pour faire ceci ; » lisez ceci dans la documentation PHPUnit. Nous recommandons d'utiliser une base de données séparée pour les tests et pour la production, et recommandons en particulier d'employer un fichier SQLite ou une base de données en mémoire, d'autant que les deux options s'exécutent très bien, sans nécessité d'un serveur séparé, et peuvent utiliser la plupart de la syntaxe SQL