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