13. Annotations

In this section we simply list all annotation that you can use with atoum.

13.1. Class’s annotation

13.2. Method’s annotation

13.3. Data providers

To help you to effectively test your classes, atoum provide you some data providers.

A data provider is a method in class test which generate arguments for test method, arguments that will be used by the method to validate assertions.

If a test method testFoo takes arguments and no annotation on a data provider is set, atoum will automatically seek the protected testFooDataProvider method.

However, you can manually set the method name of the data provider through the @dataProvider annotation applied to the relevant test method, as follows :

<?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)
        ;
    }

    // ...
}

Obviously, do not forget to define, at the level of the test method, arguments that correspond to those that will be returned by the data provider. If not, atoum will generate an error when running the tests.

The data provider method is a single protected method that returns an array or an iterator containing data :

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

    // Provides data for testSum().
    protected function sumDataProvider()
    {
        return array(
            array( 1, 1),
            array( 1, 2),
            array(-1, 1),
            array(-1, 2),
        );
    }
}

When running the tests, atoum will call test method testSum() with the arguments (1, 1), (1, 2), (-1, 1) and (-1, 2) returned by the method sumDataProvider().

Warning

The insulation of the tests will not be used in this context, which means that each successive call to the method testSum() will be realized in the same PHP process.

13.3.1. Data provider as closure

You can also use a closure to define a data provider instead of an annotation. In your method beforeTestMethod, you can use this example:

<?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 injected in test method

There is also, an injection of mock in the test method parameters. So take a simple example:

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

You can write this instead:

<?php

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

In this case, no need for data provider. But, if you want to customize the mock you will require it or use beforeTestMethod.

<?php

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

    public function beforeTestMethod($method)
    {
        // orphanize the controller for the next mock generated, here $iterator
        $this->mockGenerator->orphanize('__construct');
    }
}

13.4. PHP Extensions

Some of your tests may require one or more PHP extension(s). Telling atoum that a test requires an extension is easily done through annotations and the tag @extensions. After the tag @extensions, just add one or more extension names, separated by a space.

<?php

namespace vendor\project\tests\units;

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

The test will only be executed if the extension is present. If not the test will be skipped and this message will be displayed.

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

Note

By default the tests will pass when a test is skipped. But you can use the –fail-if-skipped-methods command line option to make the test fail when an extension is not present.

13.5. PHP Version

Some of your tests may require a specific version of PHP to work (for example, the test may only work on PHP 7). Telling atoum that the test requires a version of PHP is done through annotations and the tag @php.

By default, without providing any operator, the tests will only be executed if the PHP version is greater or equal to the version in the tag:

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

With this example the test will only be executed if the PHP version is greater of equal to PHP 7.0. If not the test will be skipped and this message will be displayed:

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

Note

By default the tests will pass when a test is skipped. But you can use the –fail-if-skipped-methods command line option to make the test fail when an extension is not present.

Internally, atoum uses PHP’s version_compare function to do the comparison.

You’re not limited to the greater equal operator. You can pass any version_compare operator.

For example:

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

Will skip the test if the PHP version is greater or equal to 5.4

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

You can also pass multiple conditions, with multiple @php annotations. For example:

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