13. Annotations

Dans cette section nous listons toutes les annotations utilisables avec atoum.

13.1. Annotation de classe

13.2. Annotation des méthodes

13.3. Data providers

Afin de permettre de tester efficacement vos classes, atoum fourni des data provider (fournisseur de données).

Un data provider est une méthode spécifique d’une classe de test chargée de générer des arguments pour une méthode de test, arguments qui seront utilisés par ladite méthode pour valider des assertions.

Si méthode de test testFoo prend des arguments, mais qu’aucune annotation précisant le data provider n’est présente, atoum va automatiquement rechercher une méthode testFooDataProvider.

Vous pouvez également définir manuellement le nom de la méthode du data provider grâce à l’annotation @dataProvider à ajouter à la méthode de test :

<?php
class calculator extends atoum
{
    /**
     * @dataProvider sumDataProvider
     */
    public function testSum($a, $b)
    {
        $this
            ->if($calculator = new project\calculator())
            ->then
                ->integer($calculator->sum($a, $b))->isEqualTo($a + $b)
        ;
    }

    // ...
}

Bien évidemment, il faut penser a définir les arguments de la méthode de test qui vont recevoir les données retournées par le data provider. Dans le cas contraire, atoum va retourner des erreurs lors de l’exécution des tests.

Un data provider est une méthode protégée qui retourne un tableau ou un itérateur qui contient de simples valeurs :

<?php
class calculator extends atoum
{
    // ...

    // Fourni des données pour testSum().
    protected function sumDataProvider()
    {
        return array(
            array( 1, 1),
            array( 1, 2),
            array(-1, 1),
            array(-1, 2),
        );
    }
}

Lors de l’exécution des test, atoum va appeler la méthode testSum() avec les arguments (1, 1), (1, 2), (-1, 1) et (-1, 2), tels que retournés par la méthode sumDataProvider().

Avertissement

L’isolation des tests ne sera pas utilisée dans ce cas d’utilisation, ce qui signifie que les appels successifs à la méthode testSum() seront exécutés dans le même processus PHP.

13.3.1. Data provider en tant que closure

Vous pouvez également utiliser une closure pour définir un data provider au lieu d’une annotation. Dans votre méthode beforeTestMethod, vous pouvez utiliser l’exemple suivant pour définir une closure :

<?php
class calculator extends atoum
{
   // ...
   public function beforeTestMethod($method)
   {
      if ($method == 'testSum')
      {
         $this->setDataProvider($method, function() {
           return array(
               array( 1, 1),
               array( 1, 2),
               array(-1, 1),
               array(-1, 2),
           );
         });
      }
   }
}

13.3.2. Data provider injecté dans les méthode de test

Il y a aussi, une injection de bouchon dans les paramètres de la méthode de test. Prenons un exemple simple :

<?php
class cachingIterator extends atoum
{
    public function test__construct()
    {
        $this
            ->given($iterator = new \mock\iterator())
            ->then
                ->object($this->newTestedInstance($iterator))
        ;
    }
}

Vous pouvez l’écrire ainsi :

<?php

class cachingIterator extends atoum
{
    public function test__construct(\iterator $iterator)
    {
        $this
            ->object($this->newTestedInstance($iterator))
        ;
    }
}

Dans ce cas, pas besoin de data provider. Cependant, si vous désirez changer le comportement de vos bouchons, cela requiert l’utilisation de beforeTestMethod.

<?php

class cachingIterator extends atoum
{
    public function test__construct(\iterator $iterator)
    {
        $this
            ->object($this->newTestedInstance($iterator))
        ;
    }

    public function beforeTestMethod($method)
    {
        // rend le controlleur orphelin pour le prochain mock généré, ici $iterator
        $this->mockGenerator->orphanize('__construct');
    }
}

13.4. PHP Extensions

Certains des tests peuvent requérir une ou plusieurs extensions PHP. atoum permet de définir cela directement à travers une annotation @extensions. Après l’annotation @extensions, ajouter simplement le nom d’une ou plusieurs extensions, séparés par une virgule.

<?php

namespace vendor\project\tests\units;

class foo extends \atoum
{
    /**
     * @extensions intl
     */
    public function testBar()
    {
        // ...
    }
}

Le test ne sera exécuté que si l’extension intl est présente. Dans le cas contraire, le test sera passé et le message suivant sera affiché.

vendor\project\tests\units\foo::testBar(): PHP extension 'intl' is not loaded

Note

Par défaut, le test est validé lorsqu’il a été passé. Mais vous pouvez utiliser –fail-if-skipped-methods l’option de la ligne de commande afin de faire échouer les tests passés.

13.5. PHP Version

Certains de vos tests peuvent requérir une version spécifique de PHP pour fonctionner (par exemple, pour certains tests ne fonctionnant qu’avec PHP 7). Dire à atoum qu’un test requiert une version spécifique de PHP s’effectue au travers de l’annotation @php.

Par défaut, sans fournir d’opérateur, le test ne sera exécuté que si la version de PHP est supérieure ou égale à la version du tag :

class testedClassname extends atoum\test
{
   /**
    * @php 7.0
    */
   public function testMethod()
   {
      // contenu du test
   }
}

Dans cette exemple, le test ne sera exécuté que si la version de PHP est supérieure ou égale à PHP 7.0. Dans le cas contraire, le test sera passé et le message suivant sera affiché :

vendor\project\tests\units\foo::testBar(): PHP version 5.5.9-1ubuntu4.5 is not >= to 7.0

Note

Par défaut, le test est considéré valide lorsqu’il est passé. Mais vous pouvez utiliser –fail-if-skipped-methods l’option de la ligne de commande afin de faire échouer les tests passés.

En interne, atoum utilise le comparateur de version de PHP pour effectuer la comparaison.

Vous n’êtes pas limité à l’opérateur égal ou supérieur. Vous pouvez passer tout les opérateurs acceptés par version_compare.

Par exemple :

class testedClassname extends atoum\test
{
   /**
    * @php < 5.4
    */
   public function testMethod()
   {
      // contenu du test
   }
}

Va passer le test si la version de PHP est supérieure ou égale à PHP 5.4

vendor\project\tests\units\foo::testBar(): PHP version 5.5.9-1ubuntu4.5 is not < to 5.4

Vous pouvez aussi utiliser de multiples conditions, avec l’annotation @php. Par exemple :

class testedClassname extends atoum\test
{
   /**
    * @php >= 5.4
    * @php <= 7.0
    */
   public function testMethod()
   {
      // contenu du test
   }
}