atoum

| PHP version | atoum version | |-------------|---------------------| | 5.3 -> 5.6 | 1.x -> 3.x | | 7.2 -> 8.1 | 4.X -> 4.1 | | 8.x | 4.1 < 4.X (current) |

🚀 Full PHP 8.0-8.4 Support

atoum now has complete support for modern PHP features, including:

• PHP 8.0: Constructor Property Promotion, Union Types, Named Arguments, Attributes
• PHP 8.1: Readonly Properties, Intersection Types, Enums, Never Return Type
• PHP 8.2: Readonly Classes, DNF Types, Standalone true/false/null types
• PHP 8.3: #[\Override] Attribute, Typed Class Constants
• PHP 8.4: Property Hooks, Asymmetric Visibility, #[\Deprecated] Attribute

All these features are fully supported in the mock generator, ensuring your modern PHP code can be properly tested. See PHP_MODERN_SUPPORT.md for detailed documentation.

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, to give the developer a whole new way of writing unit tests. Therefore, it can be installed and integrated into an existing project extremely easily, since it is only a single PHAR archive, which is the one and only entry point for the developer. Also, thanks to its fluent 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 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 atoum\atoum\test\generator();
$testGenerator
    ->setTestClassesDirectory(__DIR__ . '/tests/units/classes');
    ->setTestClassNamespace('atoum\atoum\tests\units');
    ->setTestedClassesDirectory(__DIR__ . '/classes');
    ->setTestedClassNamespace('atoum\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 >= 8.0.0 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

If PHP 8.0.x or higher 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.3 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'

If Xdebug 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

You just have to download its PHAR archive and store it where you wish, for example under /path/to/project/tests/atoum.phar. This PHAR archive contains the latest development version to pass the totality of atoum's unit tests. atoum's source code is also 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: