Zend_Test_PHPUnit_Db

Couper l'accès aux données au modèle métier requiert souvent l'utilisation d'une base de données pour les tests. Mais la base est persistente entre les tests, et leur isolation est donc rompue, de plus, configurer une base de données pour des tests peut vite s'avérer complexe. L'extension sur les bases de données de PHPUnit simplifie les procédures de tests en offrant des mécanismes de preconditions et postconditions sur la base entre les tests. Ce composant étend donc l'extension base de données de PHPUnit en ajoutant du code spécifique à Zend Framework.

Les tests de base de données peuvent être résumés en 2 notions : DataSets et DataTables. En interne, PHPUnit peut créer un objet dont la structure est callée sur une base de données dont les tables et les enregistrements sont montés depuis un fichier de configuration ou un contenu réel. Cet objet abstrait peut alors être comparé à des structures. Un cas courant en tests de base de données consiste à configurer des tables en les remplissant de données fictives, éxecuter du code "utile", puis comparer la base de données avec une structure. Zend_Test_PHPUnit_Db simplifie cette tâche en offrant la possibilité de créer des DataSets et des DataTables provenant d'instances de Zend_Db_Table_Abstract ou Zend_Db_Table_Rowset_Abstract.

Aussi, ce composant permet l'utilisation de n'importe quel Zend_Db_Adapter_Abstract alors qu'à l'originine PHPUnit ne fonctionne qu'avec PDO. Un adaptateur de test basé sur Zend_Db_Adapter_Abstract est aussi inclus. Il permet d'instancier un adaptateur qui ne requiert aucune base de données réelle.

Quickstart

Configurer un cas de tests Database

Nous allons à présent écrire des tests pour la base de données Bug de la documentation sur Zend_Db_Table. D'abord, nous testons qu'insérer un nouveau bug est bien sauvegardé en base. Nous devons créer un cas de tests sous forme de classe étendant Zend_Test_PHPUnit_DatabaseTestCase. Cette classe étend elle- même PHPUnit Database Extension, qui étend alors PHPUnit_Framework_TestCase. Un cas de test pour base de données contient deux méthodes abstraites à définir, une concernant la connexion à la base et l'autre concernant les données à utiliser comme source pour les tests.

Note: Il est recommandé de se familiariser à l'extension PHPUnit Database afin de suivre nos exemples sereinnement. Bien que nous expliquions tous les concepts dans cette documentation, il peut être intéressant de lire la documentation de PHPUnit avant de suivre nos exemples.

class BugsTest extends Zend_Test_PHPUnit_DatabaseTestCase
{
    private $_connectionMock;
 
    /**
     * Retourne la connexion de test
     *
     * @return PHPUnit_Extensions_Database_DB_IDatabaseConnection
     */
    protected function getConnection()
    {
        if($this->_connectionMock == null) {
            $connection = Zend_Db::factory(...);
            $this->_connectionMock = $this->createZendDbConnection(
                $connection, 'zfunittests'
            );
            Zend_Db_Table_Abstract::setDefaultAdapter($connection);
        }
        return $this->_connectionMock;
    }
 
    /**
     * @return PHPUnit_Extensions_Database_DataSet_IDataSet
     */
    protected function getDataSet()
    {
        return $this->createFlatXmlDataSet(
            dirname(__FILE__) . '/_files/bugsSeed.xml'
        );
    }
}

Ici, nous créons la connexion à la base et nous y injectons des données fictives de test. Les éléments suivants sont importants à noter :

Vous ne pouvez retourner directement un objet Zend_Db_Adapter_Abstract depuis getConnection(), mais un objet spécifique à PHPUnit qui est généré grâce à la méthode createZendDbConnection().
Le schéma de la base (tables et bases de données) n'est pas recrée entre chaque test. Les bases de données et les tables doivent être créees à la main avant de lancer les tests.
Les tests vident la base durant setUp() et y insèrent les données en provenance de getDataSet().
Les jeux de données (DataSets) doivent implémenter PHPUnit_Extensions_Database_DataSet_IDataSet. Il en existe quelques uns, basés sur XML ou YAML et ils sont inclus dans PHPUnit et permettent de décrire les données fictives pour les tests. Vous devriez vous reporter à la documentation de PHPUnit pour des informations complémentaires ou plus à jour concernant les DataSets.

Spécifier un jeu de données (DataSet)

Dans l'exemple précédent, nous avons préciser un fichier de jeu de données. Nous allons maintenant le créer, au format XML :

<?xml version="1.0" encoding="UTF-8" ?>
<dataset>
    <zfbugs bug_id="1" bug_description="system needs electricity to run"
        bug_status="NEW" created_on="2007-04-01 00:00:00"
        updated_on="2007-04-01 00:00:00" reported_by="goofy"
        assigned_to="mmouse" verified_by="dduck" />
    <zfbugs bug_id="2" bug_description="Implement Do What I Mean function"
        bug_status="VERIFIED" created_on="2007-04-02 00:00:00"
        updated_on="2007-04-02 00:00:00" reported_by="goofy"
        assigned_to="mmouse" verified_by="dduck" />
    <zfbugs bug_id="3" bug_description="Where are my keys?" bug_status="FIXED"
        created_on="2007-04-03 00:00:00" updated_on="2007-04-03 00:00:00"
        reported_by="dduck" assigned_to="mmouse" verified_by="dduck" />
    <zfbugs bug_id="4" bug_description="Bug no product" bug_status="INCOMPLETE"
        created_on="2007-04-04 00:00:00" updated_on="2007-04-04 00:00:00"
        reported_by="mmouse" assigned_to="goofy" verified_by="dduck" />
</dataset>

Nous allons travailler sur ces quatre entrées dans la table "zfbugs" après. Le script MySQL suivant est nécessaire pour l'exemple:

CREATE TABLE IF NOT EXISTS `zfbugs` (
    `bug_id` int(11) NOT NULL AUTO_INCREMENT,
    `bug_description` varchar(100) DEFAULT NULL,
    `bug_status` varchar(20) DEFAULT NULL,
    `created_on` datetime DEFAULT NULL,
    `updated_on` datetime DEFAULT NULL,
    `reported_by` varchar(100) DEFAULT NULL,
    `assigned_to` varchar(100) DEFAULT NULL,
    `verified_by` varchar(100) DEFAULT NULL,
PRIMARY KEY  (`bug_id`)
) ENGINE=InnoDB AUTO_INCREMENT=1 ;

Quelques tests initiaux

Maintenant que nous avons écrits les deux méthodes obligatoires pour Zend_Test_PHPUnit_DatabaseTestCase et que nous avons préciser avec quoi remplir la base et ses tables, nous pouvons commencer à écrire des tests afin d'effectuer des assertions. Voyons un test pour l'insertion d'un nouveau bug

class BugsTest extends Zend_Test_PHPUnit_DatabaseTestCase
{
    public function testBugInsertedIntoDatabase()
    {
        $bugsTable = new Bugs();
 
        $data = array(
            'created_on'      => '2007-03-22 00:00:00',
            'updated_on'      => '2007-03-22 00:00:00',
            'bug_description' => 'Something wrong',
            'bug_status'      => 'NEW',
            'reported_by'     => 'garfield',
            'verified_by'     => 'garfield',
            'assigned_to'     => 'mmouse',
        );
 
        $bugsTable->insert($data);
 
        $ds = new Zend_Test_PHPUnit_Db_DataSet_QueryDataSet(
            $this->getConnection()
        );
        $ds->addTable('zfbugs', 'SELECT * FROM zfbugs');
 
        $this->assertDataSetsEqual(
            $this->createFlatXmlDataSet(dirname(__FILE__)
                                      . "/_files/bugsInsertIntoAssertion.xml"),
            $ds
        );
    }
}

Au dessus de la ligne $bugsTable->insert($data);, tout devrait vous être familier. La ligne d'après contient le nom de la méthode d'assertion. Nous souhaitons vérifier qu'après l'insertion d'un bug, la base a été correctement mise à jour avec les données. Ainsi, nous utilisons un objet de requête de jeu de données, instance de Zend_Test_PHPUnit_Db_DataSet_QueryDataSet et nous lui fournissons notre connexion à la base de données. Puis nous indiquons à notre objet de requête qu'il contient une table "zfbugs" contenant les données d'une requête SQL statement. Cet état actuel est alors comparé à un état contenu dans un fichier XML "bugsInsertIntoAssertions.xml". Ce fichier XML est le même que celui des données d'origine, à l'exception qu'il contient lui les données supplémentaires attendues:

<?xml version="1.0" encoding="UTF-8" ?>
<dataset>
    <!-- Les 4 enregistrement précédents, puis: -->
    <zfbugs bug_id="5" bug_description="Something wrong" bug_status="NEW"
        created_on="2007-03-22 00:00:00" updated_on="2007-03-22 00:00:00"
        reported_by="garfield" assigned_to="mmouse" verified_by="garfield" />
</dataset>

Il existe d'autres manière de vérifier que l'état actuel de la base est équivalent à un état attendu. La table "Bugs" de l'exemple connait déja sont état interne, utilisons ceci à notre avantage. L'exemple suivant teste que la suppression de données dans la table est possible:

class BugsTest extends Zend_Test_PHPUnit_DatabaseTestCase
{
    public function testBugDelete()
    {
        $bugsTable = new Bugs();
 
        $bugsTable->delete(
            $bugsTable->getAdapter()->quoteInto("bug_id = ?", 4)
        );
 
        $ds = new Zend_Test_PHPUnit_Db_DataSet_DbTableDataSet();
        $ds->addTable($bugsTable);
 
        $this->assertDataSetsEqual(
            $this->createFlatXmlDataSet(dirname(__FILE__)
                                      . "/_files/bugsDeleteAssertion.xml"),
            $ds
        );
    }
}

Ici nous créons un objet représentant un jeu de données pour une table, instance de Zend_Test_PHPUnit_Db_DataSet_DbTableDataSet. Il prend en paramètre un objet Zend_Db_Table_Abstract et l'ajoute au jeu de données avec le nom de la table, dans notre exemple : "zfbugs". Vous pourriez ajouter plus de données dans le jeu de données en utilisant addTable() plusieurs fois.

Ici nous ne possédons qu'une seule table et nous la comparons à un état défini dans "bugsDeleteAssertion.xml" qui est en fait le jeu de données original moins la données supprimée : celle ayant l'id 4.

Voyons maintenant comment vérifier que deux tables soient identiques (et non deux jeux de données correspondants à de telles tables). Ajoutons un test à notre scénario qui va vérifier la mise à jour de données.

class BugsTest extends Zend_Test_PHPUnit_DatabaseTestCase
{
    public function testBugUpdate()
    {
        $bugsTable = new Bugs();
 
        $data = array(
            'updated_on'      => '2007-05-23',
            'bug_status'      => 'FIXED'
        );
 
        $where = $bugsTable->getAdapter()->quoteInto('bug_id = ?', 1);
 
        $bugsTable->update($data, $where);
 
        $rowset = $bugsTable->fetchAll();
 
        $ds        = new Zend_Test_PHPUnit_Db_DataSet_DbRowset($rowset);
        $assertion = $this->createFlatXmlDataSet(
            dirname(__FILE__) . '/_files/bugsUpdateAssertion.xml'
        );
        $expectedRowsets = $assertion->getTable('zfbugs');
 
        $this->assertTablesEqual(
            $expectedRowsets, $ds
        );
    }
}

Ici, nous récupérons l'état de la table depuis un objet Zend_Db_Table_Rowset_Abstract au moyen de Zend_Test_PHPUnit_Db_DataSet_DbRowset($rowset) qui crée une représentation de l'état interne des données du rowset. Nous comparons enfin cet état grâce à l'assertion $this->assertTablesEqual()

Utilisation, API et possibilités d'extension

Le Quickstart permet déja de se rendre compte des capacités de tests d'une base de données avec PHPUnit et Zend Framework. Cette section donne un aperçu de l'API de Zend_Test_PHPUnit_Db ainsi que de son fonctionnement interne.

Note: Remarque sur les tests de bases de données
Tout comme les TestCase de vos contrôleurs, les tests de bases de données sont efféctués au niveau intégration. Ils utilisent différentes couches applicatives pour lancer les tests et à ce titre devraient être utilisés avec précaution.
Notez que tester la logique métier au seul moyen de tests d'intégration comme ceux fournis avec Zend_Test de Zend Framework est une mauvaise pratique. Les tests d'intégration sont là pour prouver le bon fonctionnement de l'assemblage des composants entre eux, ils ne doivent donc pas remplacer des tests unitaires éffectués plus bas dans les couches de votre logique métier.

La classe Zend_Test_PHPUnit_DatabaseTestCase

La classe Zend_Test_PHPUnit_DatabaseTestCase étend PHPUnit_Extensions_Database_TestCase, celle-ci permet de configurer un jeu de données concernant la base, pour chaque test. L'implementation du Zend Framework offre quelques fonctionalités supplémentaires par rapport à l'extension PHPUnit concernant les bases de données, ceci dans le but d'utiliser des ressources provenant de Zend_Db. Voici le scénario classique d'un test de base de données :

Pour chaque test, PHPUnit crée une instance de la classe de tests (TestCase) et lance la méthode setUp().
Le scénario de test (TestCase) crée à son tour une instance du testeur de base de données (Database Tester) qui s'occupe de la construction et destruction de la base de données.
Le testeur de base de données récupère la connexion à la base et le jeu de données initiales grâce à getConnection() et getDataSet() qui sont toutes deux des méthodes abstraites que vous devez implémenter dans votre scénario de test.
Par défaut le testeur vide les tables spécifiées dans le jeu de données, puis peuple la base avec le jeu de données.
Lorsque le testeur a fini de monter la base, PHPUnit lance votre test.
Après que votre test ait fini, tearDown() est appelée. Cette méthode n'exécute aucune action du la base de données elle-même car les actions à mener sont efféctuées en setUp() (vider les tables).

Note: Le test de la base s'attend à ce que la base de données et les tables soient présentes. Il n'existe pas de mécanisme pour créer/détruire des base de données et/ou des tables.

La classe Zend_Test_PHPUnit_DatabaseTestCase permet les tests de base de données à l'echelle du Zend Framework.

Le tableau suivant liste uniquement les nouvelles méthodes par rapport à la classe PHPUnit_Extensions_Database_TestCase, dont l'» API est documentée dans la documentation de PHPUnit.

**Méthodes de Zend_Test_PHPUnit_DatabaseTestCase**
Méthode	Description
createZendDbConnection(Zend_Db_Adapter_Abstract $connection, $schema)	Créer une connexion compatible avec l'extension PHPUnit Database depuis une instance de Zend_Db_Adapter_Abstract. Cette méthode devrait être utilisée dans la configuration du scénario de tests en implémentant la méthode abstraite getConnection().
getAdapter()	Méthode permettant l'accès à l'instance de Zend_Db_Adapter_Abstract qui est encapsulée dans la connexion efféctuée par PHPUnit au moyen de getConnection().
createDbRowset(Zend_Db_Table_Rowset_Abstract $rowset, $tableName = null)	Créer un objet représentant les données d'une table depuis une instance de Zend_Db_Table_Rowset_Abstract donnée. La table reliée au rowset est choisie lorsque `$tableName` est `NULL`.
createDbTable(Zend_Db_Table_Abstract $table, $where = null, $order = null, $count = null, $offset = null)	Créer un objet qui représente les données contenues dans une instance de Zend_Db_Table_Abstract donnée. La récupération des données est faite grâce à fetchAll(), les paramètres additionnels peuvent servir à limiter les données retournées.
createDbTableDataSet(array $tables=array())	Crée un jeu de données basé sur les tables `$tables`, tableau d'instances de Zend_Db_Table_Abstract.

Intégrer les tests de bases de données avec les tests de contrôleurs

PHP n'autorise pas l'héritage multiple, donc vous ne pouvez utiliser les tests de contrôleurs et de bases de données en même temps via héritage. Cependant, vous pouvez utiliser Zend_Test_PHPUnit_Db_SimpleTester dans vos tests de contrôleurs pour configurer un environnement relatif à la base pour chaque test de contrôleur.

Example #1 Exemple d'intégration d'une base de données

Cet exemple reprend le test de UserController utilisé dans la documentation de Zend_Test_PHPUnit_ControllerTestCase et y inclut la gestion d'une base de données.

class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{
    public function setUp()
    {
        $this->setupDatabase();
        $this->bootstrap = array($this, 'appBootstrap');
        parent::setUp();
    }
 
    public function setupDatabase()
    {
        $db = Zend_Db::factory(...);
        $connection = new Zend_Test_PHPUnit_Db_Connection($db,
                                                      'database_schema_name');
        $databaseTester = new Zend_Test_PHPUnit_Db_SimpleTester($connection);
 
        $databaseFixture =
                    new PHPUnit_Extensions_Database_DataSet_FlatXmlDataSet(
                        dirname(__FILE__) . '/_files/initialUserFixture.xml'
                    );
 
        $databaseTester->setupDatabase($databaseFixture);
    }
}

Ici le jeu de données XML "initialUserFixture.xml" est utilisé pour monter des données en base avant chaque test, exactement de la même manière que DatabaseTestCase le fait en interne.

Utiliser l'adaptateur de tests

Il peut être nécessaire quelques fois de vouloir tester l'application, mais sans base de données réelle physique. Zend_Test_DbAdapter offre des possibilités d'utiliser une implémentation de Zend_Db_Adapter_Abstract sans avoir à ouvrir une connexion vers une base physique. En plus, cet adaptateur est très facilement déguisable car aucun paramètre de constructeur n'est nécessaire.

L'adaptateur de tests agit comme une pile pour des résultats de base. L'ordre des résultats doit être implémenté manuellement ce qui peut devenir assez complexe, mais cet adaptateur est très pratique dans le cas où un ensemble logique de requêtes est éxecuté et que vous connaissez l'ordre précis dans lequel les résultats doivent être retournés.

$adapter   = new Zend_Test_DbAdapter();
$stmt1Rows = array(array('foo' => 'bar'), array('foo' => 'baz'));
$stmt1     = Zend_Test_DbStatement::createSelectStatement($stmt1Rows);
$adapter->appendStatementToStack($stmt1);
 
$stmt2Rows = array(array('foo' => 'bar'), array('foo' => 'baz'));
$stmt2     = Zend_Test_DbStatement::createSelectStatement($stmt2Rows);
$adapter->appendStatementToStack($stmt2);
 
$rs = $adapter->query('SELECT ...'); // Retourne Statement 2
while ($row = $rs->fetch()) {
    echo $rs['foo']; // Prints "Bar", "Baz"
}
$rs = $adapter->query('SELECT ...'); // Retourne Statement 1

Le comportement des adaptateurs réels est simulé afin que des méthodes telles que fetchAll(), fetchObject(), fetchColumn() puissent fonctionner avec l'adaptateur de tests.

Bien sûr, INSERT, UPDATE et DELETE peuvent être empilés aussi, mais vous ne pourrez alors tester que $stmt->rowCount() car ces types de requêtes ne retournent pas de résultats.

$adapter = new Zend_Test_DbAdapter();
$adapter->appendStatementToStack(
    Zend_Test_DbStatement::createInsertStatement(1)
);
$adapter->appendStatementToStack(
    Zend_Test_DbStatement::createUpdateStatement(2)
);
$adapter->appendStatementToStack(
    Zend_Test_DbStatement::createDeleteStatement(10
));

Par défaut, le profiler est activé pour que vous puissiez récupérer la requête éxecutée de manière textuelle, avec ses paramètres donc.

$adapter = new Zend_Test_DbAdapter();
$stmt = $adapter->query("SELECT * FROM bugs");
 
$qp = $adapter->getProfiler()->getLastQueryProfile();
 
echo $qp->getQuerY(); // SELECT * FROM bugs

L'adaptateur de test ne vérifie jamais si la requête spécifiée est réellement de type SELECT, DELETE, INSERT ou UPDATE. L'ordre exact de retour des données doit être spécifié manuellement dans l'adaptateur de tests.

L'adaptateur de tests définit aussi les méthodes listTables(), describeTables() et lastInsertId(). De plus en utilisant setQuoteIdentifierSymbol() vous pouvez spécifier quel symbole utilisé pour l'échappement, par défaut aucun n'est utilisé.