repo_zf1/documentation/manual/fr/module_specs/Zend_Test-PHPUnit-Db-Quickstart.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.test.phpunit.db.quickstart">
    <title>Quickstart</title>

    <sect3 id="zend.test.phpunit.db.quickstart.testcase">
        <title>Configurer un cas de tests Database</title>

        <para>
            Nous allons à présent écrire des tests pour la base de données Bug de la
            documentation sur <classname>Zend_Db_Table</classname>. 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
            <classname>Zend_Test_PHPUnit_DatabaseTestCase</classname>. Cette classe étend elle-
            même PHPUnit Database Extension, qui étend alors
            <classname>PHPUnit_Framework_TestCase</classname>. 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.
        </para>

        <note>
            <para>
                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.
            </para>
        </note>

        <programlisting language="php"><![CDATA[
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'
        );
    }
}
]]></programlisting>

        <para>
            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 :
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Vous ne pouvez retourner directement un objet <classname>Zend_Db_Adapter_Abstract</classname>
                    depuis <methodname>getConnection()</methodname>, mais un objet spécifique à PHPUnit
                    qui est généré grâce à la méthode <methodname>createZendDbConnection()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    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.
                </para>
            </listitem>

            <listitem>
                <para>
                    Les tests vident la base durant <methodname>setUp()</methodname> et y
                    insèrent les données en provenance de <methodname>getDataSet()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Les jeux de données (DataSets) doivent implémenter
                    <classname>PHPUnit_Extensions_Database_DataSet_IDataSet</classname>.
                    Il en existe quelques uns, basés sur <acronym>XML</acronym> 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.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.test.phpunit.db.quickstart.dataset">
        <title>Spécifier un jeu de données (DataSet)</title>

        <para>
            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 <acronym>XML</acronym> :
        </para>

        <programlisting language="xml"><![CDATA[
<?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>
]]></programlisting>

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

        <programlisting language="sql"><![CDATA[
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 ;
]]></programlisting>
    </sect3>

    <sect3 id="zend.test.phpunit.db.quickstart.initial-tests">
        <title>Quelques tests initiaux</title>

        <para>
            Maintenant que nous avons écrits les deux méthodes obligatoires pour
            <classname>Zend_Test_PHPUnit_DatabaseTestCase</classname> 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
        </para>

        <programlisting language="php"><![CDATA[
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
        );
    }
}
]]></programlisting>

        <para>
            Au dessus de la ligne <methodname>$bugsTable->insert($data);</methodname>, 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 
            <classname>Zend_Test_PHPUnit_Db_DataSet_QueryDataSet</classname> 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 <acronym>SQL</acronym> statement. Cet état actuel
            est alors comparé à un état contenu dans un fichier  <acronym>XML</acronym>
            "bugsInsertIntoAssertions.xml". Ce fichier <acronym>XML</acronym> est le même que celui des données
            d'origine, à l'exception qu'il contient lui les données supplémentaires attendues:
        </para>

        <programlisting language="xml"><![CDATA[
<?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>
]]></programlisting>

        <para>
            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:
        </para>

        <programlisting language="php"><![CDATA[
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
        );
    }
}
]]></programlisting>

        <para>
            Ici nous créons un objet représentant un jeu de données pour une table, instance de
            <classname>Zend_Test_PHPUnit_Db_DataSet_DbTableDataSet</classname>. Il prend en paramètre
            un objet <classname>Zend_Db_Table_Abstract</classname> 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 <methodname>addTable()</methodname> plusieurs fois.
        </para>

        <para>
            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.
        </para>

        <para>
            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.
        </para>

        <programlisting language="php"><![CDATA[
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
        );
    }
}
]]></programlisting>

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