Chapitre 6. Tester des bases de données

Le dataset le plus commun est appelé XML à plat (flat XML). C'est un format xml très simple dans lequel une balise à l'intérieur d'un noeud racine <dataset> représente exactement une ligne de la base de données. Les noms des balises sont ceux des tables dans lesquelles insérer les lignes et un attribut représente la colonne. Un exemple pour une simple application de livre d'or pourrait ressembler à ceci :

<?xml version="1.0" ?>
<dataset>
    <livre_d_or id="1" contenu="Salut Poum!" utilisateur="joe" date_creation="2010-04-24 17:15:23" />
    <livre_d_or id="2" contenu="J'aime !" utilisateur="nancy" date_creation="2010-04-26 12:14:20" />
</dataset>

C'est à l'évidence facile à écrire. Ici, <livre_d_or> est le nom de la table dans laquelle les deux lignes sont insérées, chacune avec quatre colonnes « id », « contenu », « utilisateur » et « date_creation » et leurs valeurs respectives.

Cependant, cette simplicité a un coût.

Avec l'exemple précédent, difficile de voir comment nous devons indiquer une table vide. Vous pouvez insérer une balise avec aucun attribut contenant le nom de la table vide. Un fichier XML à plat pour une table livre_d_or pourrait alors ressembler à ceci:

<?xml version="1.0" ?>
<dataset>
    <livre_d_or />
</dataset>

La gestion des valeurs NULL avec le dataset en XML à plat est fastidieuse. Une valeur NULL est différente d'une chaîne vide dans la plupart des bases de données (Oracle étant une exception), quelque chose qu'il est difficile de décrire dans le format XML à plat. Vous pouvez représenter une valeur NULL en omettant d'attribut indiquant la ligne. Si votre livre d'or autorise les entrées anonymes représentées par une valeur NULL dans la colonne utilisateur, un état hypothétique de la table livre_d_or pourrait ressembler à ceci:

<?xml version="1.0" ?>
<dataset>
    <livre_d_or id="1" contenu="Hello Poum !" utilisateur="joe" date_creation="2010-04-24 17:15:23" />
    <livre_d_or id="2" contenu="J'aime !" date_creation="2010-04-26 12:14:20" />
</dataset>

Dans ce cas, la seconde entrée est postée anonymement. Cependant, ceci conduit à un sérieux problème pour la reconnaissance de la colonne. Lors des assertions d'égalité de datasets, chaque dataset doit indiquer quelle colonne une table contient. Si un attribut est NULL pour toutes les lignes de la data-table, comment l'extension de base de données sait que la colonne doit faire partie de la table ?

Le dataset en XML à plat fait maintenant une hypothèse cruciale en décrétant que les attributs de la première ligne définie pour une table définissent les colonnes de cette table. Dans l'exemple précédent, ceci signifierait que « id », « contenu », « utilisateur » et « date_creation » sont les colonnes de la table livre_d_or. Pour la seconde ligne dans laquelle « utilisateur » n'est pas défini, un NULL sera inséré dans la base de données.

Quand la première entrée du livre d'or est supprimée du dataset, seuls « id », « contenu » et « date_creation » seront des colonnes de la table livre_d_or, puisque « utilisateur » n'est pas indiqué.

Pour utiliser efficacement le dataset au format XML à plat quand des valeurs NULL sont pertinentes, la première ligne de chaque table ne doit contenir aucune valeur NULL, seules les lignes suivantes pouvant omettre des attributs. Ceci peut s'avérer délicat, puisque l'ordre des lignes est un élément pertinent pour les assertions de base de données.

A l'inverse, si vous n'indiquez qu'un sous-élément des colonnes de la table dans le dataset au format XML à plat, toutes les valeurs omises sont positionnées à leurs valeurs par défaut. Ceci provoquera des erreurs si l'une des valeurs omises est définie par « NOT NULL DEFAULT NULL ».

En conclusion, je ne peux que vous conseiller de n'utiliser les datasets au format XML à plat que si vous n'avez pas besoin des valeurs NULL.

Vous pouvez créer une instance de dataset au format XML à plat dans votre cas de test de base de données en appelant la méthode createFlatXmlDataSet($filename):

class MonCasDeTest extends PHPUnit_Extensions_Database_TestCase
{
    public function getDataSet()
    {
        return $this->createFlatXmlDataSet('maFixtureAuFormatXMLaPlat.xml');
    }
}

Il existe un autre dataset XML davantage structuré, qui est un peu plus verbeux à écrire mais qui évite les problèmes de NULL du dataset au format XML à plat. Dans le noeud racine <dataset> vous pouvez indiquer les balises <table>, <column>, <row>, <value> et <null />. Un dataset équivalent à celui défini précédemment pour le livre d'or en format XML à plat ressemble à :

<?xml version="1.0" ?>
<dataset>
    <table name="livre_d_or">
        <column>id</column>
        <column>contenu</column>
        <column>utilisateur</column>
        <column>date_creation</column>
        <row>
            <value>1</value>
            <value>Hello Poum !</value>
            <value>joe</value>
            <value>2010-04-24 17:15:23</value>
        </row>
        <row>
            <value>2</value>
            <value>J'aime !</value>
            <null />
            <value>2010-04-26 12:14:20</value>
        </row>
    </table>
</dataset>

Tout <table> défini possède un nom et nécessite la définition de toutes les colonnes avec leurs noms. Il peut contenir zéro ou tout nombre positif d'éléments <row> imbriqués. Ne définir aucun élément <row> signifie que la table est vide. Les balises <value> et <null /> doivent être indiquées dans l'ordre des éléments <column>précédemment donnés. La balise <null /> signifie évidemment que la valeur est NULL.

Vous pouvez créer une instance de dataset xml dans votre cas de test de base de données en appelant la méthode createXmlDataSet($filename) :

class MonCasdeTest extends PHPUnit_Extensions_Database_TestCase
{
    public function getDataSet()
    {
        return $this->createXMLDataSet('maFixtureyXml.xml');
    }
}

Ce nouveau format XML est spécifique au serveur de bases de données MySQL. Sa gestion a été ajoutée dans PHPUnit 3.5. Les fichiers écrits ce format peuvent être générés avec l'utilitaire mysqldump. Contrairement aux datasets CSV, que mysqldump gère également, un unique fichier de ce format XML peut contenir des données pour de multiples tables. Vous pouvez créer un fichier dans ce format en invoquant mysqldump de cette façon :

mysqldump --xml -t -u [nom_utilisateur] --password=[mot_de_passe] [base_de_donnees] > /chemin/vers/fichier.xml
        

Ce fichier peut être utilisé dans votre case de test de base de données en appelant la méthode createMySQLXMLDataSet($nomdefichier):

class MonCasDeTest extends PHPUnit_Extensions_Database_TestCase
{
    public function getDataSet()
    {
        return $this->createMySQLXMLDataSet('/chemin/vers/fichier.xml');
    }
}

Nouveau depuis PHUnit 3.4, la possibilité d'indiquer un dataset via le format populaire YAML. Pour que cela fonctionne, vous devez installer PHPUnit 3.4 avec PEAR ainsi que sa dépendance optionnelle Symfony YAML. Vous pouvez ensuite écrire un dataset YAML pour l'exemple du livre d'or:

livre_d_or:
  -
    id: 1
    contenu: "Hello Poum !"
    utilisateur: "joe"
    date_creation: 2010-04-24 17:15:23
  -
    id: 2
    contenu: "J'aime !"
    utilisateur:
    date_creation: 2010-04-26 12:14:20

C'est simple, pratique et ça règle le problème de NULL que pose le dataset équivalent au format XML à plat. Un NULL en YAML s'exprime simplement en donnant le nom de la colonne dans indiquer de valeur. Une chaîne vide est indiquée par colonne1: "".

Le dataset YAML ne possède pas actuellement de méthode de fabrique pour le cas de tests de base de données, si bien que vous devez l'instancier manuellement :

class LivredOrYamlTest extends PHPUnit_Extensions_Database_TestCase
{
    protected function getDataSet()
    {
        return new PHPUnit_Extensions_Database_DataSet_YamlDataSet(
            dirname(__FILE__)."/_files/livre_d_or.yml"
        );
    }
}

Un autre dataset au format fichier est basé sur les fichiers CSV. Chaque table du dataset est représenté par un fichier CSV. Pour notre exemple de livre d'or, nous pourrions définir un fichier livre_d_or-table.csv:

id,contenu,utilisateur,date_creation
1,"Hello Poum !","joe","2010-04-24 17:15:23"
2,"J'aime !","nancy","2010-04-26 12:14:20"

Bien que ce soit très pratique à éditer avec Excel ou LibreOffice, vous ne pouvez pas indiquer de valeurs NULL avec le dataset CSV. Une colonne vide conduira à ce que la valeur vide par défaut de la base de données soit insérée dans la colonne.

Vous pouvez créer un dataset CSV en appelant :

class CsvLivredOrTest extends PHPUnit_Extensions_Database_TestCase
{
    protected function getDataSet()
    {
        $dataSet = new PHPUnit_Extensions_Database_DataSet_CsvDataSet();
        $dataSet->addTable('guestbook', dirname(__FILE__)."/_files/livre_d_or.csv");
        return $dataSet;
    }
}

Il n'existe pas (encore) de DataSet basé sur les tableau dans l'extension base de données de PHPUnit, mais vous pouvez implémenter facilement la vôtre. Notre exemple du Livre d'or devrait ressembler à :

class LivredOrTableauTest extends PHPUnit_Extensions_Database_TestCase
{
    protected function getDataSet()
    {
        return new MyApp_DbUnit_ArrayDataSet(array(
            'livre_d_or' => array(
                array('id' => 1, 'contenu' => 'Hello Poum !', 'utilisateur' => 'joe', 'date_creation' => '2010-04-24 17:15:23'),
                array('id' => 2, 'contenu' => 'J\'aime !',   'utilisateur' => null,  'date_creation' => '2010-04-26 12:14:20'),
            ),
        ));
    }
}

Un DataSet PHP possède des avantages évidents sur les autres datasets utilisant des fichiers :

Pour que ce dataset ressemble aux DataSets au format XML à plat, CSV et YAML, les clefs de la première ligne spécifiée définissent les noms de colonne de la table, dans le cas précédent, ce serait « contenu », « utilisateur » et « date_creation ».

L'implémentation de ce DataSet tableau est simple et évidente:

class MyApp_DbUnit_ArrayDataSet extends PHPUnit_Extensions_Database_DataSet_AbstractDataSet
{
    /**
     * @var array
     */
    protected $tables = array();

    /**
     * @param array $data
     */
    public function __construct(array $data)
    {
        foreach ($data AS $tableName => $rows) {
            $columns = array();
            if (isset($rows[0])) {
                $columns = array_keys($rows[0]);
            }

            $metaData = new PHPUnit_Extensions_Database_DataSet_DefaultTableMetaData($tableName, $columns);
            $table = new PHPUnit_Extensions_Database_DataSet_DefaultTable($metaData);

            foreach ($rows AS $row) {
                $table->addRow($row);
            }
            $this->tables[$tableName] = $table;
        }
    }

    protected function createIterator($reverse = FALSE)
    {
        return new PHPUnit_Extensions_Database_DataSet_DefaultTableIterator($this->tables, $reverse);
    }

    public function getTable($tableName)
    {
        if (!isset($this->tables[$tableName])) {
            throw new InvalidArgumentException("$tableName ne correspond pas à une table dans la base de données actuelle.");
        }

        return $this->tables[$tableName];
    }
}

Pour les assertions de base de données, vous n'avez pas seulement besoin de datasets basés sur des fichiers mais aussi de Datasets basé sur des requêtes/du SQL qui contiennent le contenu constaté de la base de données. C'est là que le DataSet Query s'illustre :

$ds = new PHPUnit_Extensions_Database_DataSet_QueryDataSet($this->getConnection());
$ds->addTable('livre_d_or');

Ajouter une table juste par son nom est un moyen implicite de définir la table de données avec la requête suivante :

$ds = new PHPUnit_Extensions_Database_DataSet_QueryDataSet($this->getConnection());
$ds->addTable('livre_d_or', 'SELECT * FROM livre_d_or');

Vous pouvez utiliser ceci en indiquant des requêtes arbitraires pour vos tables, par exemple en restreignant les lignes, les colonnes ou en ajoutant des clauses ORDER BY:

$ds = new PHPUnit_Extensions_Database_DataSet_QueryDataSet($this->getConnection());
$ds->addTable('livre_d_or', 'SELECT id, contenu FROM livre_d_or ORDER BY date_creation DESC');

La section relative aux assertions de base de données montrera plus en détails comment utiliser le Query DataSet.

En accédant à la connexion de test, vous pouvez créer automatiquement un DataSet constitué de toutes les tables et de leur contenu de la base de données indiquée comme second paramètre de la méthode fabrique de connexion.

Vous pouvez, soit créer un dataset pour la base de données complète comme montré dans la méthode testLivredOr(), soit le restreindre à un ensemble de noms de tables avec une liste blanche comme montré dans la méthode testLivredOrFiltre().

class MonLivredOrSqlTest extends PHPUnit_Extensions_Database_TestCase
{
    /**
     * @return PHPUnit_Extensions_Database_DB_IDatabaseConnection
     */
    public function getConnection()
    {
        $base_de_donnees = 'ma_base_de_donnee';
        $pdo = new PDO('mysql:...', $utilisateur, $mot_de_passe);
        return $this->createDefaultDBConnection($pdo, $base_de_donnees);
    }

    public function testLivredOr()
    {
        $dataSet = $this->getConnection()->createDataSet();
        // ...
    }

    public function testLivredOrFiltre()
    {
        $nomTables = array('livre_d_or');
        $dataSet = $this->getConnection()->createDataSet($nomTables);
        // ...
    }
}

J'ai évoqué les problèmes de NULL avec les DataSet au format XML à plat et CSV, mais il y existe un contournement légèrement compliqué pour que ces deux types de datasets fonctionnent avec NULLs.

Le DataSet de remplacement est un décorateur pour un dataset existant et vous permet de remplacer des valeurs dans toute colonne du dataset par une autre valeur de remplacement. Pour que notre exemple de livre d'or fonctionne avec des valeurs NULL nous indiquons le fichier comme ceci:

<?xml version="1.0" ?>
<dataset>
    <livre_d_or id="1" contenu="Hello Poum !" utilisateur="joe" date_creation="2010-04-24 17:15:23" />
    <livre_d_or id="2" contenu="J'aime !" utilisateur="##NULL##" date_creation="2010-04-26 12:14:20" />
</dataset>

Nous enrobons le DataSet au format XML à plat dans le DataSet de remplacement :

class ReplacementTest extends PHPUnit_Extensions_Database_TestCase
{
    public function getDataSet()
    {
        $ds = $this->createFlatXmlDataSet('maFixtureEnXMLaPlat.xml');
        $rds = new PHPUnit_Extensions_Database_DataSet_ReplacementDataSet($ds);
        $rds->addFullReplacement('##NULL##', null);
        return $rds;
    }
}

Si vous avez un fichier de fixture conséquent vous pouvez utiliser le filtre de DataSet pour des listes blanches ou noires des tables et des colonnes qui peuvent être contenues dans un sous-dataset. C'est particulièrement commode en combinaison avec le DataSet de base de données pour filtrer les colonnes des datasets.

class DataSetFilterTest extends PHPUnit_Extensions_Database_TestCase
{
    public function testLivredOrAvecFiltredInclusion()
    {
        $nomTables = array('livre_d_or');
        $dataSet = $this->getConnection()->createDataSet();

        $filterDataSet = new PHPUnit_Extensions_Database_DataSet_DataSetFilter($dataSet);
        $filterDataSet->addIncludeTables(array('livre_d_or'));
        $filterDataSet->setIncludeColumnsForTable('livre_d_or', array('id', 'contenu'));
        // ..
    }

    public function testLivredOrAvecFiltredExclusion()
    {
        $nomTables = array('livre_d_or');
        $dataSet = $this->getConnection()->createDataSet();

        $filterDataSet = new PHPUnit_Extensions_Database_DataSet_DataSetFilter($dataSet);
        $filterDataSet->addExcludeTables(array('foo', 'bar', 'baz')); // ne garder que la table livre_d_or !
        $filterDataSet->setExcludeColumnsForTable('livre_d_or', array('utilisateur', 'date_creationd'));
        // ..
    }
}

Le DataSet composite est très utile pour agréger plusieurs datasets déjà existants dans un unique dataset. Quand plusieurs datasets contiennent la même table, les lignes sont ajoutées dans l'ordre indiqué. Par exemple, si nous avons deux datasets fixture1.xml :

<?xml version="1.0" ?>
<dataset>
    <livre_d_or id="1" contenu="Hello Poum !" utilisateur="joe" date_creation="2010-04-24 17:15:23" />
</dataset>

et fixture2.xml:

<?xml version="1.0" ?>
<dataset>
    <livre_d_or id="2" contenu="J'aime !" utilisateur="##NULL##" date_creation="2010-04-26 12:14:20" />
</dataset>

En utiliser le DataSet composite, nous pouvons agréger les deux fichiers de fixture:

class CompositeTest extends PHPUnit_Extensions_Database_TestCase
{
    public function getDataSet()
    {
        $ds1 = $this->createFlatXmlDataSet('fixture1.xml');
        $ds2 = $this->createFlatXmlDataSet('fixture2.xml');

        $compositeDs = new PHPUnit_Extensions_Database_DataSet_CompositeDataSet();
        $compositeDs->addDataSet($ds1);
        $compositeDs->addDataSet($ds2);

        return $compositeDs;
    }
}