3. Launching tests

3.1. Executable

Atoum has an executable that allow you to launch your tests from the command line.

3.1.1. Using the phar archive

If you are using the phar archive, then the archive is itself the executable.

3.1.1.1. linux / mac

$ php path/to/mageekguy.atoum.phar

3.1.1.2. windows

C:\> X:\Path\To\php.exe X:\Path\To\mageekguy.atoum.phar

3.1.2. Using the source

If you are using the source, the executable is located in path/to/atoum/bin.

3.1.2.1. linux / mac

$ php path/to/bin/atoum
 
# OU #
 
$ ./path/to/bin/atoum

3.1.2.2. windows

C:\> X:\Path\To\php.exe X:\Path\To\bin\atoum\bin

3.1.3. Examples in the remainder of the Documentation

In the following examples, the commands used to launch the tests with Atoum will be written in the form:

$ ./bin/atoum

This is the exact command you would use if you have installed Atoum with composer under Linux

3.2. Files to execute

3.2.1. By File

In order to launch tests on a file, you only need to use the -f or --files option.

$ ./bin/atoum -f tests/units/MyTest.php

3.2.2. By Directory

In order to launch tests on a directory, you only need to use the -d or --directories option.

$ ./bin/atoum -d tests/units

3.3. Filters

Once you have told Atoum which files it must execute, you will be able to filter to will really be executed.

3.3.1. By Namespace

In order to filter on a namespace, that is to execute the tests solely on a given namespace, you only need need to use the -ns or --namespace option.

$ ./bin/atoum -d tests/units -ns mageekguy\\atoum\\tests\\units\\asserters

3.3.2. Class or method

In order to filter on a class or a method, that is to executre only the tests of a particular class or method, you need only to use the -m or --methods options.

$ ./bin/atoum -d tests/units -m mageekguy\\atoum\\tests\\units\\asserters\\string::testContains

You can replace the class or method name by * to signify all.

If you replace the method name by *, it reslults in filtering by class.

$ ./bin/atoum -d tests/units -m mageekguy\\atoum\\tests\\units\\asserters\\string::*

If you replace the class name by ##**##, it results in filtering by methods.

$ ./bin/atoum -d tests/units -m *::testContains

3.3.3. Tags

Just as numerous tools such as Behat, Atoum allows you to tag your unit tests and to execute only those with (a) specific tag(s)

In order for this to happen, one must begin by defining (a) tag(s) for (a) class(es) of unit tests.

It can easily be done thanks to the annotation or the anchor @tags:

<?php
 
namespace vendor\project\tests\units;
 
require_once __DIR__ . '/mageekguy.atoum.phar';
 
use mageekguy\atoum;
 
/**
 * @tags thisIsOneTag thisIsTwoTag thisIsThreeTag
 */
class foo extends atoum\test
{
    public function testBar()
    {
        ...
    }
}

It is also possible to tag test methods.

<?php
 
namespace vendor\project\tests\units;
 
require_once __DIR__ . '/mageekguy.atoum.phar';
 
use mageekguy\atoum;
 
class foo extends atoum\test
{
    /**
     * @tags thisIsOneMethodTag thisIsTwoMethodTag thisIsThreeMethodTag
     */
    public function testBar()
    {
        ...
    }
}

Once the necessary tags have been defined, tests can be executed with or without the required tags by using the option --tags or -t for its shorthand version.

$ ./bin/atoum -d tests/units -t thisIsOneTag

Warning, this instruction only makes sense if there is one or more class of unit tests and if at least one of them is tagged with the specified tag. In the opposite case, no test will be performed.

It is possible to define several tags:

$ ./bin/atoum -d tests/units -t thisIsOneTag thisIsThreeTag

In that last case, the tests classes having been tagged with thisIsOneTag or with thisIsThreeTag will be the only one executed.

3.4. Configuration files

3.4.1. Code Coverage

By default, if PHP can make use of the Xdebug extension, Atoum will indicate in command line mode the code coverage percentage for the tests just executed.

If the code coverage percentage is 100%, Atoum merely indicate it, but if it is not the case, it will display the global coverage percentage as well as that of each tested class method.

$ php tests/units/classes/template.php
> atoum version DEVELOPMENT by Frederic Hardy (/Users/fch/Atoum)
> PHP path: /usr/local/bin/php
> PHP version:
=> PHP 5.3.8 (cli) (built: Sep 21 2011 23:14:37)
=> Copyright (c) 1997-2011 The PHP Group
=> Zend Engine v2.3.0, Copyright (c) 1998-2011 Zend Technologies
=>     with Xdebug v2.1.1, Copyright (c) 2002-2011, by Derick Rethans
> mageekguy\atoum\tests\units\template...
[SSSSSSSSSSSSSSSSSSSSSSSSSSS_________________________________][27/27]
=> Test duration: 15.63 seconds.
=> Memory usage: 8.25 Mb.
> Total test duration: 15.63 seconds.
> Total test memory usage: 8.25 Mb.
> Code coverage value: 92.52%
=> Class mageekguy\atoum\template: 91.14%
==> mageekguy\atoum\template::setWith(): 80.00%
==> mageekguy\atoum\template::resetChildrenData(): 25.00%
==> mageekguy\atoum\template::addToParent(): 0.00%
==> mageekguy\atoum\template::unsetAttribute(): 0.00%
=> Class mageekguy\atoum\template\data: 96.43%
==> mageekguy\atoum\template\data::__toString(): 0.00%
> Running duration: 2.36 seconds.
Success (1 test, 27 methods, 485 assertions, 0 error, 0 exception) !

It is however possible to obtain a more precise representation of the code coverage percentage by the tests in the form of an HTML report. In order to obtain it, one only needs to base it on the configuration files models included in Atoum. If you are using the PHAR archive, it must be extracted by using the following command:

php mageekguy.atoum.phar -er /path/to/destination/directory

Once the extraction has been perfomed, you should be able to see a directory named "resources/configuration.runner" in the directory "/path/to/destination/directory".

If you are using Atoum with a github repository clone or with composer, the models can be found in "/path/to/atoum/resources/configurations/runner.

In this directory are, among other interesting things, an Atoum configuration file model named "coverage.php.dist" that you will need to copy at the location of your choosing under, for example, the name "coverage.php".

Once the copy has been performed, modify it with you prefered editor in order to define:

• the directory in wich HTML files shall be generated.
• the URL from which the report will be accessible.

For example:

$coverageField = new atoum\report\fields\runner\coverage\html(
    'Code coverage de mon projet',
    '/path/to/destination/directory'
);
 
$coverageField->setRootUrl('http://url/of/web/site');

Once this is all done, the configuration file can be used at tests execution time as follows:

$ ./bin/atoum -c path/to/coverage.php -d tests/units

One the tests have been executed, Atoum will generate the code coverage report in HTML format in the directory previously defined. It then will be readable using your favorite browser.

3.4.2. Notifications

atoum is able to warn you when the tests are performed using several notification system: Growl, Notification Center, Libnotify.

3.4.2.1. Growl

This feature uses the growlnotify utility. To check if the command is available, run:

$ which growlnotify && echo $?
/path/to/growlnotify
0

Then you will have to add the following lines to your configuration file:

<?php
$images = '/path/to/atoum/resources/images/logo';
 
$notifier = new \mageekguy\atoum\report\fields\runner\result\notifier\image\growl();
$notifier
    ->setSuccessImage($images . DIRECTORY_SEPARATOR . 'success.png')
    ->setFailureImage($images . DIRECTORY_SEPARATOR . 'failure.png')
;
 
$report = $script->AddDefaultReport();
$report->addField($notifier, array(atoum\runner::runStop));

3.4.2.2. Mac OS X Notification Center

This feature uses the terminal-notifier utility. To check if the command is available, run:

$ which terminal-notifier && echo $?
/path/to/terminal-notifier
0

Then you will have to add the following lines to your configuration file:

<?php
$notifier = new \mageekguy\atoum\report\fields\runner\result\notifier\terminal();
 
$report = $script->AddDefaultReport();
$report->addField($notifier, array(atoum\runner::runStop));

On OS X, you can define a command to be executed when the user clicks on the notification.

<?php
$coverage = new atoum\report\fields\runner\coverage\html(
    'Code coverage',
    $path = sys_get_temp_dir() . '/coverage_' . time()
);
$coverage->setRootUrl('file://' . $path);
 
$notifier = new \mageekguy\atoum\report\fields\runner\result\notifier\terminal();
$notifier->setCallbackCommand('open 'file://' . $path . '/index.html);
 
$report = $script->AddDefaultReport();
$report
    ->addField($coverage, array(atoum\runner::runStop))
    ->addField($notifier, array(atoum\runner::runStop))
;

The example above shows how to automatically open the code coverage report when the user clicks on the notification.

3.4.2.3. Libnotify

This feature uses the notify-send utility. To check if the command is available, run:

$ which notify-send && echo $?
/path/to/notify-send
0

Then you will have to add the following lines to your configuration file:

<?php
$images = '/path/to/atoum/resources/images/logo';
 
$notifier = new \mageekguy\atoum\report\fields\runner\result\notifier\image\libnotify();
$notifier
    ->setSuccessImage($images . DIRECTORY_SEPARATOR . 'success.png')
    ->setFailureImage($images . DIRECTORY_SEPARATOR . 'failure.png')
;
 
$report = $script->AddDefaultReport();
$report->addField($notifier, array(atoum\runner::runStop));

3.5. Bootstrap file

Atoum can use a bootstrap file which will be executed before each test method thus allowing the initialization of the tests execution environment.

Using it makes it possible for example to define a class autoloading function, to read a configuration file or to perform any other operation necessary to the proper tests execution.

The bootstrap file definition can be done in 2 differents manners, either by using the command line or via a configuration file

When using the command line, the -bf or the --bootstrap-file option followed by the relative or absolute path to the bootstrap file intended to be used.

$ ./bin/atoum -bf path/to/bootstrap/file

In a configuration file, Atoum is configured via the $runner variable, which is itself defined in bootstrap file.

Moreover, both files are not included at the same time since the configuration file is included by Atoum before the tests execution but after the launching of the tests, when the ##bootstrap file, should it be defined, is the first and foremost file included by Atoum.

Finally the bootstrap can help avoid systematically loading the /scripts/runner.php file or the Atoum PHAR archive in the test classes.

However, in this case, it won't possible to execute directly a test file via the PHP executable when using the command line.

In order to do this, one must include the scripts/runner.php or the Atoum PHAR archive in the bootstrap file and systematically execute the tests using the command line via scripts/runner/.php ou the PHAR archive.

The bootstrap file must at mininum contain this:

<?php
 
// if the PHAR archive is used:
require_once path/to/mageekguy.atoum.phar;
 
// or if the source is used:
// require_once path/atoum/scripts/runner.php

3.6. Command line options

Most of the options exist come in 2 flavours, the short version (1 to 6 characters) and the more explicit long version. Both flavours do the exact same thing and you can use them indifferently.

Certain options can accept multiple values:

$ ./bin/atoum -f tests/units/MyFirstTest.php tests/units/MySecondTest.php

# Only tests "MySecondTest.php"
$ ./bin/atoum -f MyFirstTest.php -f MySecondTest.php
 
# Only tests "MyThirdTest.php" and "MyFourthTest.php"
$ ./bin/atoum -f MyFirstTest.php MySecondTest.php -f MyThirdTest.php MyFourthTest.php

3.6.1. -bf <file> / --bootstrap-file <file>

Specifies to the path to the bootstrap file.

$ ./bin/atoum -bf /path/to/bootstrap.php
$ ./bin/atoum --bootstrap-file /path/to/bootstrap.php

3.6.2. -c <file> / --configuration <file>

Specifies which configuration to use to launch the tests.

$ ./bin/atoum -c config/atoum.php
$ ./bin/atoum --configuration tests/units/conf/coverage.php

3.6.3. -d <directories> / --directories <directories>

Specifies one or more directories containing tests to be launched.

$ ./bin/atoum -d tests/units/db/
$ ./bin/atoum --directories tests/units/db/ tests/units/entities/

3.6.4. --debug

Turns debug mode on

$ ./bin/atoum --debug

3.6.5. -drt <string> / --default-report-title <string>

Specifies the title used in reports generated by Atoum.

$ ./bin/atoum -drt Title
$ ./bin/atoum --default-report-title "My Title"

3.6.6. -f <files> / --files <files>

Specifies tests files to launch.

$ ./bin/atoum -f tests/units/db/mysql.php
$ ./bin/atoum --files tests/units/db/mysql.php tests/units/db/pgsql.php

3.6.7. -ft / --force-terminal

Forces output to stdout.

$ ./bin/atoum -ft
$ ./bin/atoum --force-terminal

3.6.8. -g <pattern> / --glob <pattern>

Filters tests files to launch by pattern(s).

$ ./bin/atoum -g ???
$ ./bin/atoum --glob ???

3.6.9. -h / --help

Lists the available options.

$ ./bin/atoum -h
$ ./bin/atoum --help

3.6.10. -l / --loop

Activates Atoum's loop mode.

$ ./bin/atoum -l
$ ./bin/atoum --loop

3.6.11. -m <class::method> / --methods <class::methods>

Filters classes and methods to launch.

# Launches only the method "testMyMethod" of class "vendor\\project\\test\\units\\myClass"
$ ./bin/atoum -m vendor\\project\\test\\units\\myClass::testMyMethod
$ ./bin/atoum --methods vendor\\project\\test\\units\\myClass::testMyMethod
 
# Launches all the test methods on class "vendor\\project\\test\\units\\myClass"
$ ./bin/atoum -m vendor\\project\\test\\units\\myClass::*
$ ./bin/atoum --methods vendor\\project\\test\\units\\myClass::*
 
# Launches only the method "testMyMethod" of all test classes
$ ./bin/atoum -m *::testMyMethod
$ ./bin/atoum --methods *::testMyMethod

3.6.12. -mcn <integer> / --max-children-number <integer>

Defines the maximum number of simulaneous processes launched to execute tests.

$ ./bin/atoum -mcn 5
$ ./bin/atoum --max-children-number 3

3.6.13. -ncc / --no-code-coverage

Deactivates the code coverage reporting.

$ ./bin/atoum -ncc
$ ./bin/atoum --no-code-coverage

3.6.14. -nccfc <classes> / --no-code-coverage-for-classes <classes>

Deactivates code coverage reporting for one or more classes.

$ ./bin/atoum -nccfc vendor\\project\\db\\mysql
$ ./bin/atoum --no-code-coverage-for-classes vendor\\project\\db\\mysql vendor\\project\\db\\pgsql

3.6.15. -nccfns <namespaces> / --no-code-coverage-for-namespaces <namespaces>

Deactivates code coverage reporting for one or more namespaces.

$ ./bin/atoum -nccfns vendor\\outside\\lib
$ ./bin/atoum --no-code-coverage-for-namespaces vendor\\outside\\lib1 vendor\\outside\\lib2

3.6.16. -nccid <directories> / --no-code-coverage-in-directories <directories>

Deactivates code coverage reporting for one or more directories.

$ ./bin/atoum -nccid /path/to/exclude
$ ./bin/atoum --no-code-coverage-in-directories /path/to/exclude/1 /path/to/exclude/2

3.6.17. -ns <namespaces> / --namespaces <namespaces>

Filters the class(es) and method(s) by namespace(s).

$ ./bin/atoum -ns mageekguy\\atoum\\tests\\units\\asserters
$ ./bin/atoum --namespaces mageekguy\\atoum\\tests\\units\\asserters

3.6.18. -p <file> / --php <file>

Specifies the path to the php executable used to launch the test(s).

$ ./bin/atoum -p /usr/bin/php5
$ ./bin/atoum --php /usr/bin/php5

By default the seeked value is looked up among the following values (in that order):

• PHP_BINARY constant.
• PHP_PEAR_PHP_BIN environment variable.
• PHPBON environment variable.
• PHP_BINDIR + '/php' constant.

3.6.19. -sf <file> / --score-file <file>

specifies a path to the score file generated by Atoum.

$ ./bin/atoum -sf /path/to/atoum.score
$ ./bin/atoum --score-file /path/to/atoum.score

3.6.20. -t <tags> / --tags <tags>

Filters class(es) and method(s) to launch by tag.

$ ./bin/atoum -t OneTag
$ ./bin/atoum --tags OneTag TwoTag

3.6.21. --test-all

Launches the tests found in the directories defined in the configuration file via $script->addTestAllDirectory('path/to/directory').

$ ./bin/atoum --test-all

3.6.22. --test-it

Launches the Atoum unit tests in order to verify that they can execute properly on your machine.

$ ./bin/atoum --test-it

3.6.23. -tfe <extensions> / --test-file-extensions <extensions>

Specifies the extension(s) of the test files to launch.

$ ./bin/atoum -tfe phpt
$ ./bin/atoum --test-file-extensions phpt php5t

3.6.24. -ulr / --use-light-report

Ligthens the report output generated by Atoum.

$ ./bin/atoum -ulr
$ ./bin/atoum --use-light-report
 
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][  59/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 118/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 177/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 236/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 295/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 354/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 413/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 472/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 531/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 590/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 649/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 708/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 767/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 826/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 885/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 944/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][1003/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][1062/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][1121/1141]
[SSSSSSSSSSSSSSSSSSSS________________________________________][1141/1141]
Success (154 tests, 1141/1141 methods, 0 void method, 0 skipped method, 16875 assertions) !

3.6.25. -v / --version

This option displays the current version of Atoum.

$ ./bin/atoum -v
$ ./bin/atoum --version
 
atoum version DEVELOPMENT by Frédéric Hardy (/path/to/atoum)