4. Running tests

4.1. Executable

atoum has an executable that allows you to run your tests from the command line.

4.1.1. With phar archive

If you used the phar archive it is already executable.

4.1.1.1. linux / mac

$ php path/to/atoum.phar

4.1.1.2. windows

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

4.1.2. With sources

If you use sources, the executable should be found in path/to/atoum/bin.

4.1.2.1. linux / mac

$ php path/to/bin/atoum

# OR #

$ ./path/to/bin/atoum

4.1.2.2. windows

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

4.1.3. Examples in the rest of the documentation

In the following examples, the commands to launch tests with atoum will be written with this syntax:

$ ./bin/atoum

This is exactly the command that you might use if you had Composer under Linux.

4.2. Files to run

4.2.1. For specific files

To run a specific file test, simply use the -f option or –files.

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

4.2.2. For a folder

To run a test in a folder, simply use the -d option or –directories.

$ ./bin/atoum -d tests/units

You can find more useful arguments to pass to the command line in the relevant sections.

4.3. Filters

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

4.3.1. By namespace

To filter on the namespace, i.e. execute only test on given namespace, you have to use the option -ns or --namespaces.

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

Note

It’s important to use double backslashes to prevent them from being interpreted by the shell.

4.3.2. A class or a method

To filter on a class or a method, i.e. only run tests of a class or a method, just use the option -m or --methods.

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

Note

It’s important to use double backslashes to prevent them from being interpreted by the shell.

You can replace the name of the class or the method with * to mean all.

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

Using “*” instead of class name mean you can filter by method name.

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

4.3.3. Tags

Like many tools including Behat, atoum allows you to tag your unit tests and run only this with one or more specific tags.

To do this, we must start by defining one or more tags to one or several classes of unit tests.

This is easily done through annotations and the @tags tag:

<?php

namespace vendor\project\tests\units;

require_once __DIR__ . '/atoum.phar';

use mageekguy\atoum;

/**
 * @tags thisIsOneTag thisIsTwoTag thisIsThreeTag
 */
class foo extends atoum\test
{
    public function testBar()
    {
        // ...
    }
}

In the same way, it is also possible to tag test methods.

Note

The tags defined in a method level take precedence over those defined at the class level.

<?php

namespace vendor\project\tests\units;

require_once __DIR__ . '/atoum.phar';

use mageekguy\atoum;

class foo extends atoum\test
{
    /**
     * @tags thisIsOneMethodTag thisIsTwoMethodTag thisIsThreeMethodTag
     */
    public function testBar()
    {
        // ...
    }
}

Once the required tags are defined, just run the tests with the appropriate tags by using the option --tags, or -t in its short version:

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

Be careful, this statement only makes sense if there is one or more classes of unit testing and at least one of them has the specified tag. If not, no test will be executed.

It’s possible to define several tags:

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

In the latter case, the tests that have been tagged with thisIsOneTag, either thisIsThreeTag, classes will be the only to be executed.