12. Configuration & bootstraping

When atoum start, several steps will be involved, some of them can be influenced by some special files.

We can have a simplified view of theses special and optional files with:

  1. Load the autoloader file
  2. Load the configuration file
  3. Load the bootstrap file

Note

You can use atoum –init to generate theses files.

12.1. Autoloader file

The autoloader file is the way you will define how the class to test will be found by atoum.

The default name of the file is .autoloader.atoum.php, atoum will load it automatically if this file is located in the current directory. You can define it through the cli with --autoloader-file or -af (see the cli options). The purpose of the autoloading file is to find the way to load the classes mandatory to run the tests. You can find more information about autoloading in the php manual.

If the autoloader file doesn’t exist, atoum will try to load vendor/autoload.php from composer. So most of the time, you will have nothing to do ;).

12.2. Configuration file

The configuration file is the way you can configure how atoum works. The default name of the file is .atoum.php, atoum will load it automatically if this file is located in the current directory. You can define it through the cli with -c.

Note

atoum configuration support inheritance of configuration files. So if you have in one of the parent directory a .atoum.php it will also be loaded. So you can have a default configuration to have the loop or debug mode activated by default.

12.2.1. Existing example

atoum provides basic configuration files as examples. Following atoum installation types, there is several way to see them:

12.2.1.1. From phar installation

If you use the PHAR archive, it must retrieve them by using the following command:

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

Once the extraction is done, you should have in the “directory/path/to/destination/directory” a directory called “resources/configurations/runner”.

12.2.1.2. From composer installation

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

12.2.2. Code coverage

By default, if PHP has the extension Xdebug, atoum indicates in command line report, the rate of tests code coverage. Some change in the behaviour of coverage can be adapt through the cli options.

If the coverage rate is 100%, atoum merely indicated. But otherwise, it displays the overall coverage and that of each method of the class tested in the form of a percentage.

$ 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) !

However, it is possible to get a more accurate representation of the rate of code coverage by tests, in HTML report. These can be found from report extensions.

12.2.2.1. Custom coverage reports

In this directory, there is, among other interesting things, a template of configuration file for atoum named coverage.php.dist that you need to copy to the location of your choice. Rename the coverage.php.

After copying the file, just have to change it with the editor of your choice to define the directory where the HTML files will be generated and the URL from which the report should be accessible.

For example:

$coverageField = new atoum\report\fields\runner\coverage\html(
    'Code coverage of my project',
    '/path/to/destination/directory'
);

$coverageField->setRootUrl('http://url/of/web/site');

Note

It is also possible to change the title of the report using the first argument to the constructor of the class mageekguy\atoum\report\fields\runner\coverage\html.

Once this is done, you just have to use the configuration file (or include it in your configuration file) when running the tests, as follows:

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

Once the tests run, atoum generate the code coverage report in HTML format in the directory that you set earlier, and it will be readable using the browser of your choice.

Note

The calculation of code coverage by tests as well as the generation of the corresponding report may slow significantly the performance of the tests. Then it can be interesting, not to systematically use the corresponding configuration file, or disable them temporarily using the -ncc argument.

12.2.3. Using standard reports

atoum come with a lot of standard reports: tap, xunit, html, cli, phing, vim, … There is also some fun reports too. You will find the most important of them here.

Note

If you want to go further, there is an extension dedicated to the reports called reports-extension.

12.2.3.1. Report configuration

12.2.3.1.1. Branch and path coverage

You can enable the coverage of branch and path inside the configuration with enableBranchAndPathCoverage. This will improve the value of the code coverage by not only checking the method in the code called, but also that each branch is called. To make it simple, if you have an if the coverage report will change if you check the else. You can also enabled it with cli option –epbc.

$script->enableBranchAndPathCoverage();
=> Class Foo\Bar: Line: 31.46%
# with branch and path coverage
=> Class Foo\Bar: Line: 31.46% Path: 1.50% Branch: 26.06%
12.2.3.1.2. Disabling coverage for a class

If you want to exclude some class from coverage, you can use $script->noCodeCoverageForClasses(\myClass::class).

12.2.3.2. HTML report

By default atoum provide a basic html report. For advanced html report, you should use the reports-extension.

<?php
$report = $script->addDefaultReport();
$coverageField = new atoum\report\fields\runner\coverage\html('Your Project Name', __DIR__ . '/reports');
// Please replace in next line http://url/of/web/site by the root url of your code coverage web site.
$coverageField->setRootUrl('http://url/of/web/site');
$report->addField($coverageField);

12.2.3.3. CLI report

The CLI report is the report you have when you launch the test. there is several options available

  • hideClassesCoverageDetails: Will disable the coverage of the class.
  • hideMethodsCoverageDetails: Will disable the coverage of the methods.
<?php
$script->addDefaultReport() // in default reports there is the cli report
    ->hideClassesCoverageDetails()
    ->hideMethodsCoverageDetails();
12.2.3.3.1. Displaying the logo of atoum
<?php
$report = $script->addDefaultReport();

// This will add the atoum logo before each run.
$report->addField(new atoum\report\fields\runner\atoum\logo());

// This will add a green or red logo after each run depending on its status.
$report->addField(new atoum\report\fields\runner\result\logo());

12.2.3.4. Treemap report

<?php
$report = $script->addDefaultReport();

$coverageHtmlField = new atoum\report\fields\runner\coverage\html('Your Project Name', __DIR__ . '/reports');
// Please replace in next line http://url/of/web/site by the root url of your code coverage web site.
$coverageHtmlField->setRootUrl('http://url/of/web/site');
$report->addField($coverageField);

$coverageTreemapField = new atoum\report\fields\runner\coverage\treemap('Your project name', __DIR__ . '/reports');
$coverageTreemapField
   ->setTreemapUrl('http://url/of/treemap')
   ->setHtmlReportBaseUrl($coverageHtmlField->getRootUrl());

$report->addField($coverageTreemapField);

12.2.4. Notifications

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

12.2.4.1. Growl

This feature requires the presence of the executable growlnotify. To check if it is available, use the following command:

$ which growlnotify

You will have the path to the executable or the message growlnotify not found if it is not installed.

Then just add the following code 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));

12.2.4.2. Mac OS X Notification Center

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

$ which terminal-notifier

You will have the path to the executable or the message terminal-notifier not found if it is not installed.

Note

Visit the project’s Github page to get more information on terminal-notifier.

Then just add the following code 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.

12.2.4.3. Libnotify

This feature requires the presence of the executable notify-send. To check if it is available, use the following command:

$ which notify-send

You will have the path to the executable or the message notify-send not found if it is not installed.

Then just add the following code 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));

12.2.5. Configuration of the test

A lot of possibility to configure how atoum will find and execute the test is available. You can use the arguments in the cli or the configuration file. Because, a simple code will explain a lot more than a long text, just read this:

<?php
$testGenerator = new atoum\test\generator();

// your unit test's directory. (-d)
$testGenerator->setTestClassesDirectory(__DIR__ . '/test/units');

// your unit test's namespace.
$testGenerator->setTestClassNamespace('your\project\namespace\tests\units');

// your unit test's runner.
$testGenerator->setRunnerPath('path/to/your/tests/units/runner.php');

$script->getRunner()->setTestGenerator($testGenerator);
// or
$runner->setTestGenerator($testGenerator);

You can also define the directory of your test with $runner->addTestsFromDirectory(path). atoum will load all the class that can be tested from this directory like you can do with -d argument in cli.

<?php
$runner->addTestsFromDirectory(__DIR__ . '/test/units');

12.3. Bootstrap file

atoum allows the definition of a bootstrap file, which will be run before each test method and which therefore allows to initialize the test execution environment.

The default name of the file is .bootstrap.atoum.php, atoum will load it automatically if this file is located in the current directory. You can define it through the cli with -bf or --bootstrap-file.

This makes possible to define, for example, the reading of a configuration file or perform any other operation necessary for the proper execution of the tests.

The definition of this bootstrap file can be done in two different ways, either in command line, or via a configuration file.

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

Note

A bootstrap file is not a configuration file file and therefore does not have the same opportunities.

In a configuration file, atoum is configurable via the $runner variable, which is not defined in a bootstrap file.

Moreover, they are not included at the same time, since the configurations file is included by atoum before the tests run but after tests launch, while the bootstrap, if it’s define, is the first file included by atoum itself. Finally, the bootstrap file can allow to not have to systematically include the scripts/runner.php file or atoum PHAR archive in test classes. However, in this case, it will not be possible to directly execute a test file directly from the PHP executable in command line. To do this, simply include in the bootstrap the file scripts/runner.php or PHAR archive of atoum and systematically execute tests by command line via scripts/runner.php or PHAR archive.

Therefore, the bootstrap file must at least contain this:

<?php

// if the PHAR archive is used:
require_once path/to/atoum.phar;

// or if sources is used and you want to load the $runner
// require_once path/atoum/scripts/runner.php

12.4. Having fun with atoum

12.4.1. Report

Tests reports can be decorated to be more pleasant or fun to read. To do this in the configuration file of atoum, add the following code

<?php
// Default configuration file is .atoum.php
// ...

$stdout = new \mageekguy\atoum\writers\std\out;
$report = new \mageekguy\atoum\reports\realtime\nyancat;
$script->addReport($report->addWriter($stdout));

You should also try \mageekguy\atoum\reports\realtime\santa reports ;)