atoum's documentation

1. Introduction

1.1. What is atoum ?

Atoum is a unit test framework, similar to PHPUnit or SimpleTest, however:

  • It is more modern and makes use of PHP's latest features.
  • It is simpler to use and master.
  • It is more intuitive and its syntax is as close as possible to the English natural language

1.2. Download & Install

For now, atoum is not tagged with a version number. If you want to use atoum, just download the last stable version. atoum aims to provide backward compatibility anyway.

You can install atoum several ways :

1.2.1. PHAR

atoum is distributed as a PHAR archive, an archive format dedicated to PHP, available since PHP 5.3.

1.2.1.1. Installation

You can download the latest stable version of atoum directly from the official website : http://downloads.atoum.org/nightly/mageekguy.atoum.phar

1.2.1.2. Updating

Updating atoum's PHAR is easy thanks to its command line tools :

  1. php -d phar.readonly=0 mageekguy.atoum.phar --update

To update atoum, PHP needs to be able to update PHAR archives, which is disabled by default, this is why you have to specify the option -d phar.readonly=0.

If a newer version of atoum exists, it will be downloaded and installed in the archive itself :

  1. php -d phar.readonly=0 mageekguy.atoum.phar --update
  2. Checking if a new version is available... Done !
  3. Update to version 'nightly-1568-201210311708'... Done !
  4. Enable version 'nightly-1568-201210311708'... Done !
  5. Atoum has been updated from version 'old-version' to 'nightly-1568-201210311708' successfully !

If no newer version is available, atoum will just stop without doing anything.

  1. php -d phar.readonly=0 mageekguy.atoum.phar --update
  2. Checking if a new version is available... Done !
  3. There is no new version available !

atoum won't ask you for confirmation before proceeding with the update as it is very easy to go back to a previous version.

1.2.1.3. Listing available versions present in atoum's archive

To show the list of versions contained in its archive, you'll use the --list-available-versions (or the shorter -lav) argument.

  1. php mageekguy.atoum.phar -lav
  2. nightly-941-201201011548
  3. * nightly-1568-201210311708

Available versions will be shown. The one prefixed with a * is active.

1.2.1.4. Updating the current version

To activate a different version of atoum, use the --enable-version (or the shorter -ev) argument with the name of the version you want to activate.

  1. php -d phar.readonly=0 mageekguy.atoum.phar -ev DEVELOPMENT

Updating the current version of atoum needs PHP to be able to update PHAR archives, which is disabled by default, this is why you have to specify the option -d phar.readonly=0.

1.2.1.5. Removing older versions

If you want to remove a version of atoum from the archive, use the --delete-version (or shorter -dv) argument followed by the name of the version you want to remove.

  1. php -d phar.readonly=0 mageekguy.atoum.phar -dv nightly-941-201201011548

The version will be removed.

You cannot remove the active version.

Removing a version of atoum needs PHP to be able to update PHAR archives, which is disabled by default, this is why you have to specify the option -d phar.readonly=0.

1.2.2. Composer

Composer is a tool for dependency management in PHP.

Start by downloading and installing Composer

  1. curl -s https://getcomposer.org/installer | php

Then, create a composer.json file at the root of your project, containing

  1. {
  2.     "require": {
  3.         "atoum/atoum": "dev-master"
  4.     }
  5. }

Finally execute :

  1. php composer.phar install

1.2.3. Installer

You will also be able to install atoum with its dedicated script:

  1. curl https://raw.github.com/atoum/atoum-installer/master/installer | php -- --phar
  2. php mageekguy.atoum.phar -v
  3. atoum version nightly-xxxx-yyyymmddhhmm by Frédéric Hardy (phar:///path/to/mageekguy.atoum.phar)

This script lets you install atoum locally (in a project, see the previous example) or as a system-wide utility:

  1. curl https://raw.github.com/atoum/atoum-installer/master/installer | sudo php -- --phar --global
  2. which atoum
  3. /usr/local/bin/atoum

Options are available and let you tweak the installation process : see the documentation for more details.

1.2.4. Github

If you want to use atoum directly from its sources, you can clone or fork its git repository on github : git://github.com/atoum/atoum.git

1.2.5. Symfony 1 plugin

If you want to use atoum in a symfony 1 project, you can do so thanks to the sfAtoumPlugin plugin

Install instructions are available on the project's page.

1.2.6. Symfony2 bundle

If you want to use atoum in a Symfony2 project, you can do so thanks to the atoum Bundle.

Install instructions are available on the project's page.

1.2.7. Zend Framework 2 component

A library is available to use atoum with Zend Framework 2. Documentation and examples are available at the following address : https://github.com/blanchonvincent/zend-framework-test-atoum.

You'll find every install instructions there.

1.3. A quick overview of atoum's philosophy

1.3.1. Very basic example

atoum wants you to write a test class for each class you want to test. As an example, if you want to test the famous HelloTheWorld class, you'll have to write the test\units\HelloTheWorld test class.

NOTE : atoum is, of course, namespaces aware. As an example, to test the Hello\The\World class, you'll write the \Hello\The\tests\units\World class.

Here is the code of your HelloTheWorld class that we'll be using as a first example. This class will be located in PROJECT_PATH/classes/HelloTheWorld.php

  1. <?php
  2. /**
  3.  * The class to be tested
  4.  */
  5. class HelloTheWorld
  6. {
  7.     public function getHiAtoum ()
  8.     {
  9.         return "Hi atoum !";
  10.     }
  11. }

Now, let's write our first test class. This class will be located in PROJECT_PATH/tests/HelloTheWorld.php

  1. <?php
  2. //Your test classes are in a dedicated namespace
  3. namespace tests\units;
  4.  
  5. //You have to include your tested class
  6. require_once __DIR__.'/../classes/HelloTheWorld.php';
  7.  
  8. //You now include atoum, using its phar archive
  9. require_once __DIR__.'/atoum/mageekguy.atoum.phar';
  10.  
  11. use \mageekguy\atoum;
  12.  
  13. /**
  14.  * Test class for \HelloTheWorld
  15.  * Test classes extend from atoum\test
  16.  */
  17. class HelloTheWorld extends atoum\test
  18. {
  19.     public function testGetHiAtoum ()
  20.     {
  21.         //new instance of the tested class
  22.         $helloToTest = new \HelloTheWorld();
  23.  
  24.         $this->assert
  25.                     //we expect the getHiAtoum method to return a string
  26.                     ->string($helloToTest->getHiAtoum())
  27.                     //and the string should be Hi atoum !
  28.                     ->isEqualTo('Hi atoum !');
  29.     }
  30. }

Now, let's launch the tests

  1. php -f ./test/HelloTheWorld.php

You will see something like this

  1. > atoum version nightly-941-201201011548 by Frédéric Hardy (phar:///home/documentation/projects/tests/atoum/mageekguy.atoum.phar/1)
  2. > PHP path: /usr/bin/php5
  3. > PHP version:
  4. => PHP 5.3.6-13ubuntu3.3 with Suhosin-Patch (cli) (built: Dec 13 2011 18:37:10)
  5. => Copyright (c) 1997-2011 The PHP Group
  6. => Zend Engine v2.3.0, Copyright (c) 1998-2011 Zend Technologies
  7. =>     with Xdebug v2.1.2, Copyright (c) 2002-2011, by Derick Rethans
  8. > tests\units\HelloTheWorld...
  9. [S___________________________________________________________][1/1]
  10. => Test duration: 0.01 second.
  11. => Memory usage: 0.00 Mb.
  12. > Total test duration: 0.01 second.
  13. > Total test memory usage: 0.00 Mb.
  14. > Code coverage value: 100.00%
  15. > Running duration: 0.16 second.
  16. Success (1 test, 1/1 method, 2 assertions, 0 error, 0 exception) !

We've just tested that the getHiAtoum method :

  • returns a string;
  • and that this string is the expected 'Hi atoum !' string.

All tests passed. You're done, your code is rock solid !

1.3.2. Rule of Thumb

The basics when you’re testing things using atoum are the following :

  • Tell atoum what you want to work on (a variable, an object, a string, an integer, …)
  • Tell atoum the state the element is expected to be in (is equal to, is null, exists, …).

1.4. Using atoum with your favorite IDE

1.5. Sublime Text 2

A SublimeText 2 plugin enables you to launch tests and see the results directly in the editor.

Required instructions to install the plugin are available here the author's blog.

1.6. VIM

atoum is bundled with a plugin dedicated to VIM.

It enables you to launch tests without leaving VIM, and to get the matching report in the editor's screen.

You can navigate through potential errors, directly going to the line where assertions failed thanks to matching key strokes.

1.6.1. Installing the VIM plugin

If you're not using the PHAR archive, you'll find the plugin in resources/vim/atoum.vba.

If you're using the PHAR archive, you can ask atoum to extract the file with the command line

  1. php mageekguy.atoum.phar --extractResourcesTo path/to/a/directory

Once you have the atoum.vba file, use VIM to edit its content

  1. vim path/to/atoum.vba

And ask VIM to install the plugin with

  1. :source %

1.6.2. Using atoum and VIM

Of course, to work properly, the plugin needs to be correctly installed, and you're supposed to be editing a test case based on atoum.

The following command line asks for tests execution:

  1. :Atoum

Tests are launched and a report, based on your atoum configuration in ftplugin/php/atoum.vim of your .vim directory, is generated in a new screen.

Feel free to link this command with a shortcut of your own. i.e. adding the following line to your .vimrc file :

  1. nnoremap *.php :Atoum

The F12 function key will now trigger the :Atoum command.

1.6.3. Managing atoum's configuration file

You can specify another configuration file by adding the following line to your .vimrc file:

  1. call atoum#defineConfiguration('/path/to/project/directory', '/path/to/atoum/configuration/file', '.php')

The atoum#defineConfiguration function enables you to define the configuration file to use based on your unit test directory.

it takes 3 arguments :

  • The path to the unit tests directory
  • The path to the atoum's configuration file to be considered
  • The extension of the unit test files that will be concerned

If you want to know more about the plugin, you can use the embedded help in VIM thanks to the following command :

  1. :help atoum