14. Command line options

Most options exist in two forms, a short form of 1 to 6 characters and a longer more explicit form. The two different forms do exactly the same thing and can be used interchangeably.

Some options accept multiple values:

$ ./bin/atoum -f tests/units/MyFirstTest.php tests/units/MySecondTest.php

Note

If you use an option multiple times, only the last one will be used.

# Only test MySecondTest.php
$ ./bin/atoum -f MyFirstTest.php -f MySecondTest.php

# Only test MyThirdTest.php and MyFourthTest.php
$ ./bin/atoum -f MyFirstTest.php MySecondTest.php -f MyThirdTest.php MyFourthTest.php

14.1. Configuration & bootstrap

14.1.1. -af <file> / –autoloader-file <file>

This option lets you specify the path to the autoloader file.

$ ./bin/atoum -af /path/to/autloader.php
$ ./bin/atoum --autoloader-file /path/to/autoloader.php

14.1.2. -bf <file> / –bootstrap-file <file>

This option lets you specify the path to the bootstrap file.

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

14.1.3. -c <file> / –configuration <file>

This option lets you specify the path to the configuration file used for running the tests.

$ ./bin/atoum -c config/atoum.php
$ ./bin/atoum --configuration tests/units/conf/coverage.php

14.1.4. -xc, –xdebug-config

This option lets you specify the path to the XDEBUG_CONFIG variable. This can also be configured with $runner->setXdebugConfig().

Typically te usage will be

$ ./bin/atoum -xc idekey=PHPSTORM

Note

You can ready the Xdebug configuration<https://xdebug.org/docs/remote> on this topic.

14.2. Filtering

14.2.1. -d <directories> / –directories <directories>

This option lets you specify the tests directory(ies) to run. You can also configure it.

$ ./bin/atoum -d tests/units/db/
$ ./bin/atoum --directories tests/units/db/ tests/units/entities/

14.2.2. -f <files> / –files <files>

This option lets you specify the test files to run.

$ ./bin/atoum -f tests/units/db/mysql.php
$ ./bin/atoum --files tests/units/db/mysql.php tests/units/db/pgsql.php

14.2.3. -g <pattern> / –glob <pattern>

This option lets you specify the test files to launch based on a pattern.

$ ./bin/atoum -g ???
$ ./bin/atoum --glob ???

14.2.4. -m <class::method> / –methods <class::methods>

This option lets you filter the classes and methods to launch.

# launch only the method testMyMethod of the class vendor\\project\\test\\units\\myClass
$ ./bin/atoum -m vendor\\project\\test\\units\\myClass::testMyMethod
$ ./bin/atoum --methods vendor\\project\\test\\units\\myClass::testMyMethod

# launch all the test methods in class vendor\\project\\test\\units\\myClass
$ ./bin/atoum -m vendor\\project\\test\\units\\myClass::*
$ ./bin/atoum --methods vendor\\project\\test\\units\\myClass::*

# launch only methods named testMyMethod from all test classes
$ ./bin/atoum -m *::testMyMethod
$ ./bin/atoum --methods *::testMyMethod

Note

Refer to the section on filters by A class or a method for more information.

14.2.5. -ns <namespaces> / –namespaces <namespaces>

This option lets you filter the classes and methods tested, based on namespaces.

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

Note

Refer to the section on filters By namespace for more information.

14.2.6. -t <tags> / –tags <tags>

This option lets you filter the classes and methods to launch based on tags.

$ ./bin/atoum -t OneTag
$ ./bin/atoum --tags OneTag TwoTag

Note

Refer to the section on filters by Tags for more information.

14.2.7. –test-all

This option lets you run the tests in directories defined in the configuration file through $script->addTestAllDirectory('path/to/directory').

$ ./bin/atoum --test-all

14.2.8. –test-it

This option lets you launch atoum own unit tests to check that it runs smoothly on your server. You can also do it in the configuration with $script->testIt();.

$ ./bin/atoum --test-it

14.2.9. -tfe <extensions> / –test-file-extensions <extensions>

This option lets you specify the extensions of test files to run.

$ ./bin/atoum -tfe phpt
$ ./bin/atoum --test-file-extensions phpt php5t

14.3. Debug & loop

14.3.1. –debug

This option allows you to enable debug mode

$ ./bin/atoum --debug

Note

Refer to the section on the Debugging test cases for more information.

14.3.2. -l / –loop

This option allows you to activate the loop mode of atoum.

$ ./bin/atoum -l
$ ./bin/atoum --loop

Note

Refer to the section on the Loop mode for more information.

14.3.3. –disable-loop-mode

This option allow you to force disabling loop mode. This allow you to overwrite a loop mode activated inside a configuration file.

14.3.4. +verbose / ++verbose

This option enable a mode verbose mode of atoum.

$ ./bin/atoum ++verbose

14.4. Coverage & reports

14.4.1. -drt <string> / –default-report-title <string>

This option lets you specify atoum reports default title.

$ ./bin/atoum -drt Title
$ ./bin/atoum --default-report-title "My Title"

Note

If the title contains spaces, you must surround it with quotes.

14.4.2. -ebpc, –enable-branch-and-path-coverage

This option to enable branch and path coverage scoring. You can also do it by configuration.

$ ./bin/atoum -ebpc
$ ./bin/atoum --enable-branch-and-path-coverage

14.4.3. -ft / –force-terminal

This option lets you force the output to the terminal.

$ ./bin/atoum -ft
$ ./bin/atoum --force-terminal

14.4.4. -sf <file> / –score-file <file>

This option lets you specify the path to the output file created by atoum.

$ ./bin/atoum -sf /path/to/atoum.score
$ ./bin/atoum --score-file /path/to/atoum.score

14.4.5. -ncc / –no-code-coverage

This option lets you disable the generation of the code coverage report.

$ ./bin/atoum -ncc
$ ./bin/atoum --no-code-coverage

14.4.6. -nccfc <classes> / –no-code-coverage-for-classes <classes>

This option lets you disable the generation of the code coverage report for one or more class.

$ ./bin/atoum -nccfc vendor\\project\\db\\mysql
$ ./bin/atoum --no-code-coverage-for-classes vendor\\project\\db\\mysql vendor\\project\\db\\pgsql

Note

It’s important to double each backslash to avoid them being interpreted by the shell.

14.4.7. -nccfns <namespaces> / –no-code-coverage-for-namespaces <namespaces>

This option lets you disable the generation of the code coverage report for one or more namespaces.

$ ./bin/atoum -nccfns vendor\\outside\\lib
$ ./bin/atoum --no-code-coverage-for-namespaces vendor\\outside\\lib1 vendor\\outside\\lib2

Note

It’s important to double each backslash to avoid them being interpreted by the shell.

14.4.8. -nccid <directories> / –no-code-coverage-in-directories <directories>

This option lets you disable the generation of the code coverage report for one or more directories.

$ ./bin/atoum -nccid /path/to/exclude
$ ./bin/atoum --no-code-coverage-in-directories /path/to/exclude/1 /path/to/exclude/2

14.4.9. -nccfm <method> / –no-code-coverage-for-methods <method>

This option lets you disable the generation of the code coverage report for one or more methods.

$ ./bin/atoum -nccfm foo\\test\\units\\myClass::testMyMethod foo\\test\\units\\myClassToo::testMyMethod
$ ./bin/atoum --no-code-coverage-for-methods foo\\test\\units\\myClass::testMyMethod foo\\test\\units\\myClassToo::testMyMethod

14.4.10. -udr / –use-dot-report

This option lets you get only execution progression with dots.

$ bin/atoum -udr
$ bin/atoum --use-dot-report
............................................................ [60/65]
.....                                                        [65/65]
Success (1 test, 65/65 methods, 0 void method, 0 skipped method, 872 assertions)!

14.4.11. -ulr / –use-light-report

This option lets you reduce the output generated by atoum.

$ ./bin/atoum -ulr
$ ./bin/atoum --use-light-report

[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][  59/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 118/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 177/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 236/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 295/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 354/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 413/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 472/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 531/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 590/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 649/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 708/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 767/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 826/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 885/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][ 944/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][1003/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][1062/1141]
[SSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSSS>][1121/1141]
[SSSSSSSSSSSSSSSSSSSS________________________________________][1141/1141]
Success (154 tests, 1141/1141 methods, 0 void method, 0 skipped method, 16875 assertions) !

14.4.12. -utr / –use-tap-report

This option lets you to produce tap report

$ ./bin/atoum -utr
$ ./bin/atoum --use-tap-report

14.5. Failure & success

14.5.1. -fivm / –fail-if-void-methods

This option makes the test suite fail if there is at least one void test method.

$ ./bin/atoum -fivm
$ ./bin/atoum --fail-if-void-methods

14.5.2. -fism / –fail-if-skipped-methods

This option makes the test suite fail if there is at least one skipped test method

$ ./bin/atoum -fism
$ ./bin/atoum --fail-if-skipped-methods

14.6. Other arguments

14.6.1. -mcn <integer> / –max-children-number <integer>

This option lets you set the maximum number of processes launched to run the tests.

$ ./bin/atoum -mcn 5
$ ./bin/atoum --max-children-number 3

14.6.2. -p <file> / –php <file>

This option lets you specify the path to the php executable used to run your tests.

$ ./bin/atoum -p /usr/bin/php5
$ ./bin/atoum --php /usr/bin/php5

By default, the value is search amongst the following values (in order):

  • PHP_BINARY constant
  • PHP_PEAR_PHP_BIN environment variable
  • PHPBIN environment variable
  • constant PHP_BINDIR + ‘/php’

14.6.3. -h / –help

This option lets you display a list of available options.

$ ./bin/atoum -h
$ ./bin/atoum --help

14.6.4. –init <directory>

This command initialize some configuration files.

$ ./bin/atoum --init path/to/configuration/directory

14.6.5. -v / –version

This option lets you display the current version of atoum.

$ ./bin/atoum -v
$ ./bin/atoum --version

atoum version DEVELOPMENT by Frédéric Hardy (/path/to/atoum)

New in version 3.3.0: Dot report added