Annexe A. Annotations

L'annotation @author est un alias pour l'annotation @group (voir la section intitulée « @group ») et permet de filtrer des tests selon leurs auteurs.

Les opérations de sauvegarde et de restauration des variables globales peuvent être complètement désactivées pour tous les tests d'une classe de cas de test comme ceci :

/**
 * @backupGlobals disabled
 */
class MonTest extends PHPUnit_Framework_TestCase
{
    // ...
}

L'annotation @backupGlobals peut également être utilisée sur les opérations de sauvegarde et de restauration :

/**
 * @backupGlobals disabled
 */
class MonTest extends PHPUnit_Framework_TestCase
{
    /**
     * @backupGlobals enabled
     */
    public function testQuiIntergitAvecDesVariablesGlobales()
    {
        // ...
    }
}

Les opérations de sauvegarde et de restauration pour les attributs statiques des classes peuvent être complètement désactivés pour tous les tests d'une classe de cas de test comme ceci :

/**
 * @backupStaticAttributes disabled
 */
class MonTest extends PHPUnit_Framework_TestCase
{
    // ...
}

L'annotation @backupStaticAttributes peut également être utilisée au niveau d'une méthode de test. Ceci permet une configuration plus fine des opérations de sauvegarde et de restauration:

/**
 * @backupStaticAttributes disabled
 */
class MonTest extends PHPUnit_Framework_TestCase
{
    /**
     * @backupStaticAttributes enabled
     */
    public function testQuiInteragitAvecDesAttributsStatiques()
    {
        // ...
    }
}

Les annotations @codeCoverageIgnore, @codeCoverageIgnoreStart et @codeCoverageIgnoreEnd peuvent être utilisées pour exclure des lignes de code de l'analyse de couverture.

Pour la manière de les utiliser, voir la section intitulée « Ignorer des blocs de code ».

L'annotation @covers peut être utilisée dans le code de test pour indique quelle(s) méthode(s) un test veut tester:

/**
 * @covers CompteBancaire::getBalance
 */
public function testBalanceEstInitiallementAZero()
{
    $this->assertEquals(0, $this->ba->getBalance());
}

Si elle est fournie, seule l'information de couverture de code pour la(les) méthode(s) sera prise en considération.

Tableau A.1, « Annotations pour indiquer quelles méthodes sont couvertes par un test » montre la syntaxe de l'annotation @covers.

L'annotation @coversNothing peut être utilisée dans le code de test pour indiquer qu'aucune information de couverture de code ne sera enregistrée pour le cas de test annoté.

Ceci peut être utilisé pour le test d'intégration. Voir Exemple 10.3, « Un test qui indique qu'aucune méthode ne doit être couverte » pour un exemple.

L'annotation peut être utilisée au niveau de la classe et de la méthode et sera surchargée par toute étiquette @covers.

Une méthode de test peut accepter des paramètres arbitraires. Ces paramètres peuvent être fournis pas une méthode fournisseuse de données ( (provider() dans Exemple 2.4, « Utiliser un fournisseur de données qui renvoie un tableau de tableaux »). La méthode fournisseur de données peut être indiquée en utilisant l'annotation @dataProvider.

Voir la section intitulée « Fournisseur de données » pour plus de détails.

PHPUnit gère la déclaration des dépendances explicites entre les méthodes de test. De telles dépendances ne définissent pas l'ordre dans lequel les méthodes de test doivent être exécutées mais elles permettent de retourner l'instance d'une fixture de test par un producteur et de la passer aux consommateurs dépendants. Exemple 2.2, « Utiliser l'annotation @depends pour exprimer des dépendances » montre comment utiliser l'annotation @depends pour exprimer des dépendances entre méthodes de test.

Voir la section intitulée « Dépendances des tests » pour plus de détails.

Exemple 2.7, « Utiliser l'annotation @expectedException » montre comment utiliser l'annotation @expectedException pour tester si une exception est levée dans le code testé.

Voir la section intitulée « Tester des exceptions » pour plus de détails.

L'annotation @expectedExceptionCode, en conjonction avec @expectedException permet de faire des assertions sur le code d'erreur d'une exception levée ce qui permet de cibler une exception particulière.

class MonTest extends PHPUnit_Framework_TestCase
{
    /**
     * @expectedException     MonException
     * @expectedExceptionCode 20
     */
    public function testExceptionAUnCodeErreur20()
    {
        throw new MonException('Un message', 20);
    }
}

Pour faciliter les tests et réduire la duplication, un raccourci peut être utilisé pour indiquer une constante de classe comme un @expectedExceptionCode en utilisant la syntaxe "@expectedExceptionCode ClassName::CONST".

class MonTest extends PHPUnit_Framework_TestCase 
  {                                                                      
      /**                                                                
        * @expectedException     MonException                             
        * @expectedExceptionCode MaClasse::CODE_ERREUR                      
        */                                                               
      public function testExceptionAUnCodeErreur20()                      
      {                                                                  
        throw new MonException('Un message', 20);
      }                                                                  
  }                                                                      
  class MaClasse                                                          
  {                                                                      
      const CODE_ERREUR = 20;                                              
  }

L'annotation @expectedExceptionMessage fonctionne de manière similaire à @expectedExceptionCode en ce qu'il vous permet de faire une assertion sur le message d'erreur d'une exception.

class MonTest extends PHPUnit_Framework_TestCase
{
    /**
     * @expectedException        MonException
     * @expectedExceptionMessage Un message
     */
    public function testExceptionALeBonMessage()
    {
        throw new MonException('Un message', 20);
    }
}

Le message attendu peut être une partie d'une chaîne d'un message d'exception. Ceci peut être utile pour faire une assertion sur le fait qu'un nom ou un paramètre qui est passé s'affiche dans une exception sans fixer la totalité du message d'exception dans le test.

class MonTest extends PHPUnit_Framework_TestCase
{
     /**
      * @expectedException        MonException
      * @expectedExceptionMessage cassé
      */
     public function testExceptionALeBonMessage()
     {
         $param = "cassé";
         throw new MonException('Paramètre "'.$param.'" incorrect.', 20);
     }
}

Pour faciliter les tests et réduire la duplication, un raccourci peut être utilisé pour indiquer une constante de classe comme un @expectedExceptionCode en utilisant la syntaxe "@expectedExceptionCode ClassName::CONST". Un exemple peut être trouvé dans la section intitulée « @expectedExceptionCode ».

Un test peut être marqué comme appartement à un ou plusieurs groupes en utilisant l'annotation @group comme ceci

class MonTest extends PHPUnit_Framework_TestCase
{
    /**
     * @group specification
     */
    public function testQuelquechose()
    {
    }

    /**
     * @group regresssion
     * @group bug2204
     */
    public function testAutreChose()
    {
    }
}

Des tests peuvent être sélectionnés pour l'exécution en se basant sur les groupes en utilisant les options --group et --exclude-group du lanceur de test en ligne de commandes ou en utilisant les directives respectives du fichier de configuration XML.

L'annotation @requires peut être utilisée pour sauter des tests lorsque des pré-requis communs, comme la version de PHP ou des extensions installées, ne sont pas fournis.

Une liste complète des possibilités et des exemples peuvent être trouvés à Tableau 7.3, « Usages possibles de @requires »

Comme alternative à préfixer vos noms de méthodes de test avec test, vous pouvez utiliser l'annotation @test dans le bloc de documentation d'une méthode pour la marquer comme méthode de test.

/**
 * @test
 */
public function balanceInitialeDoitEtre0()
{
    $this->assertEquals(0, $this->ba->getBalance());
}