atoum

A simple, modern and intuitive unit testing framework for PHP!

Just like SimpleTest or PHPUnit, atoum is a unit testing framework specific to the PHP language.
However, it has been designed from the start with the following ideas in mind:

• Can be implemented rapidly ;
• Simplify test development ;
• Allow for writing reliable, readable, and clear unit tests ;

To accomplish that, it massively uses capabilities provided by PHP 5.3, to give the developer a whole new way of writing unit tests.
Therefore, it can be installed and integrated inside an existing project extremely easily, since it is only a single PHAR archive, which is the one and only entry point for the developper.
Also, thanks to its fluid interface, it allows for writing unit tests in a fashion close to natural language.
It also makes it easier to implement stubbing within tests, thanks to intelligent uses of anonymous functions and closures.
atoum natively, and by default, performs the execution of each unit test within a separate PHP process, to warrant isolation.
Of course, it can be used seamlessly for continuous integration, and given its design, it can be made to cope with specific needs extremely easily.
atoum also accomplishes all of this without affecting performance, since it has been developed to boast a reduced memory footprint while allowing for hastened test execution.
It can also generate unit test execution reports in the Xunit format, which makes it compatible with continuous integration tools such as Jenkins.
atoum also generates code coverage reports, in order to make it possible to supervise unit tests.
Finally, even though it is developed mainly on UNIX, it can also work on Windows.

Why atoum?

Atoum was made because its original author thinks that unit testing must be simple, fast and fun (as possible) to write and execute.

• atoum is really easy to install: clone it from github, download its PHAR or simply use composer,
• atoum provides a high level of security during test execution by isolating each test method in its own PHP process. Of course, this feature is available out of the box, no need to install any additional extension,
• atoum runs tests in a parallelized environment making the suite run as fast as possible by taking advantage of today's multi-core CPUs,
• atoum provides a full-featured set of natural and expressive assertions making tests as readable as possible. Here is an example:

<?php
$this
	->integer(150)
		->isGreaterThan(100)
		->isLowerThanOrEqualTo(200)
;

• atoum supports a BDD-like syntax with a lot of structural keywords:

<?php
$this
	->given($testedInstance = new testedClass())
	->and($testedClass[] = $firstValue = uniqid())
	->then
		->sizeof($testedInstance)->isEqualTo(1)
		->string($testedClass[0])->isEqualTo($firstValue)
;

• atoum provides a dead simple, yet very powerful, mock engine:

<?php
$this
	->given($testedInstance = new testedClass())
	->and($aMock = new \mock\foo\bar()) // here a mock of the class \foo\bar is created dynamically
	->and($this->calling($aMock)->doOtherThing = true) // each call to doOtherThing() by the instance will return true
	->and($testedInstance->setDependency($aMock))
	->then
		->boolean($testedInstance->doSomething())->isTrue()
		->mock($aMock)
			->call('doOtherThing')->withArguments($testedInstance)->once() // Asserts that the doOtherTHing() method of $aMock was called once
;

• atoum provides a clear API to assert on exceptions:

<?php
$this
	->given($testedInstance = new testedClass())
	->and($aMock = new \mock\foo\bar()) // here a mock of the class \foo\bar is created dynamically
	->and($this->calling($aMock)->doOtherThing->throw = $exception = new \exception()) // Call to doOtherThing() will throw an exception
	->and($testedInstance->setDependency($aMock))
	->then
		->exception(function() use ($testedInstance) { $testedInstance->doSomething(); })
			->isIdenticalTo($exception)
;

• atoum also lets you mock native PHP functions. Again, this is available out of the box:

<?php
$this
	->given($this->function->session_start = false)
	->and($session = new testedClass())
	->then
		->exception(function() use ($session) { $session->start(); })
			->isInstanceOf('project\namespace\exception')
			->hasMessage('Unable to start session')
		->function('session_start')->wasCalled()->once()
;

• atoum is able to produce several reports like TAP, clover, xUnit to be easily integrated with Jenkins or any other continuous integration tool,
• atoum supports data providers,
• atoum tests support autorun: just include the atoum runner and launch your test using php path/to/test/file.php,
• atoum's configuration file is exclusively written in PHP (no XML, YAML or any other format) giving you the best flexibility:

<?php
$script->addDefaultArguments('--test-it', '-ncc');

$runner->addTestsFromDirectory(__DIR__ . '/tests/units/classes');

$testGenerator = new mageekguy\atoum\test\generator();
$testGenerator
	->setTestClassesDirectory(__DIR__ . '/tests/units/classes');
	->setTestClassNamespace('mageekguy\atoum\tests\units');
	->setTestedClassesDirectory(__DIR__ . '/classes');
	->setTestedClassNamespace('mageekguy\atoum')
	->setRunnerPath(__DIR__ . '/scripts/runner.php')
;

$runner->setTestGenerator($testGenerator);

• atoum provides an automatic test template generator,
• atoum provides a loop mode to easily retrigger failed tests,
• atoum is full of other interesting features that you will discover over the time.

Prerequisites to use atoum

atoum absolutely requires PHP 5.3.3 or later to work. On UNIX, in order to check whether you have the right PHP version, you just need to run the following command in your terminal:

# php -v | grep -oi 'php 5\.\(3\.\([3-9]\|[1-9][0-9]\{1,\}\)\|[4-9]\.[0-9]\+\)'

If PHP 5.3.x or equivalent gets displayed, then you have the right PHP version installed. Should you want to use atoum using its PHAR archive, you also need PHP to be able to access the phar module, which is normally available by default.
On UNIX, in order to check whether you have this module or not, you just need to run the following command in your terminal:

# php -m | grep -i phar

If Phar or equivalent gets displayed, then the module is properly installed.
Generating reports in the Xunit format requires the xml module.
On UNIX, in order to check whether you have this module or not, you just need to run the following command in your terminal:

# php -m | grep -i xml

If Xml or equivalent gets displayed, then the module is properly installed.
Should you wish to monitor the coverage rate of your code by the unit tests, the Xdebug 2.2 module will be required.
On UNIX, in order to check whether you have this module or not, you just need to run the following command in your terminal:

# php -v | grep -oi 'xdebug v2.2.[0-9]*'

If Xdebug v2.2.x or equivalent gets displayed, then the module is properly installed.

A unit testing framework that can be made operational in 5 minutes!

Step 1: Install atoum

atoum's source code is available via the github repository.
To check if atoum works correctly with your configuration, you can execute all its unit tests.
To do that, you just need to run the following command in your terminal:

# php atoum.phar --test-it

You can also install it using composer.
Firstly, add in your composer.json the atoum's repository:

"repositories": [
	{
		"url": "https://github.com/mageekguy/atoum.git",
		"type": "git"
	}
]

Secondly, just do php composer.phar install in the root directory of your project.

Step 2: Write your tests

Using your preferred text editor, create the file path/to/project/tests/units/helloWorld.php and add the following code:

<?php

namespace vendor\project\tests\units;

require_once 'path/to/atoum.phar';

include_once 'path/to/project/classes/helloWorld.php';

use \mageekguy\atoum;
use \vendor\project;

class helloWorld extends atoum\test
{
	public function testSay()
	{
		$helloWorld = new project\helloWorld();

		$this->string($helloWorld->say())->isEqualTo('Hello World!')
		;
	}
}

Step 3: Run your test with the commandline

Launch your terminal and run the following command:

# php path/to/test/file[enter]

You should get the following result, or something equivalent:

> PHP path: /usr/local/bin/php
> PHP version:
=> PHP 5.6.4 (cli) (built: Dec 31 2014 14:27:59)
=> Copyright (c) 1997-2014 The PHP Group
=> Zend Engine v2.6.0, Copyright (c) 1998-2014 Zend Technologies
> vendor\project\tests\units\helloWorld...
[E___________________________________________________________][1/1]
=> Test duration: 0.00 second.
=> Memory usage: 0.00 Mb.
> Total test duration: 0.00 second.
> Total test memory usage: 0.00 Mb.
> Running duration: 0.08 second.
Failure (1 test, 1/1 method, 0 void method, 0 skipped method, 0 uncompleted method, 0 failure, 1 error, 0 exception)!
> There is 1 error:
=> vendor\project\tests\units\helloWorld::testSay():
==> Error E_USER_ERROR