Stagehand_TestRunner User Guide¶
This user guide describes Stagehand_TestRunner 2.18.0
English | 日本語
- Stagehand_TestRunner User Guide
- Test Runner Commands
- Running Tests
- Runs tests in the specified directory.
- Runs tests in the specified file.
- Runs only the specified tests in the specified file.
- Runs only the tests in the specified classes.
- Preloads the specified PHP script before running tests.
- Monitors for changes in the specified directories and run tests when changes are detected.
- Stops on the first failure or error.
- Specifies the test file pattern.
- Reporting Test Results
- Testing Framework Specific Features
- Available Features by Testing Framework
Test Runner Commands¶
NOTE: To use each testing framework, each product is required. However, for PHPT, PHPUnit is required.
The following is the relationship between the testing frameworks and the test runner commands:
| UNIX | Windows | |
|---|---|---|
| PHPUnit | phpunitrunner | phpunitrunner.bat |
| CIUnit | ciunitrunner | ciunitrunner.bat |
| SimpleTest | simpletestrunner | simpletestrunner.bat |
| CakePHP | cakerunner | cakerunner.bat |
| PHPT | phptrunner | phptrunner.bat |
| PHPSpec | phpspecrunner | phpspecrunner.bat |
Running Tests¶
Runs tests in the specified directory.¶
phpunitrunner TEST_DIRECTORY phpunitrunner -R TEST_DIRECTORY
Scans the specified directory, and runs tests. If the -R option is specified, all subdirectories are recursively scanned.
NOTE: Multiple files and directories can be specified as test target.
Runs tests in the specified file.¶
phpunitrunner TEST_FILE
Runs tests only for the specified file.
NOTE: Multiple files and directories can be specified as test target.
Runs only the specified tests in the specified file.¶
phpunitrunner -m METHOD1,METHOD2,... TEST_FILE
Runs the specified tests which are included in the specified file. Multiple methods can be specified by a comma delimited list.
NOTE: Fully-qualified method names can be specified such like CLASS::METHOD. And the method names are case-insensitive.
Runs only the tests in the specified classes.¶
phpunitrunner --classes=CLASS1,CLASS2,... TEST_FILE
Runs the tests in the specified classes which are included in the specified file. Multiple classes can be specified by a comma delimited list.
Preloads the specified PHP script before running tests.¶
phpunitrunner -p FILE ...
A script can be specified which makes preparations for a test run, which are the include path, autoloading, and error handling, etc. It is evaluated before the test runner body is loaded.
See a real-world example. The following is a script of Stagehand_AccessControl a product of Piece Framework.
<?php
error_reporting(E_ALL | E_STRICT);
set_include_path(realpath(dirname(__FILE__) . '/../src') . PATH_SEPARATOR .
get_include_path()
);
require_once 'PHPUnit/Framework.php';
require_once 'Stagehand/Autoload.php';
$loader = Stagehand_Autoload::legacyLoader();
$loader->addNamespace('Stagehand');
Stagehand_Autoload::register($loader);
Stagehand_LegacyError_PHPError::enableConversion();
Monitors for changes in the specified directories and run tests when changes are detected.¶
phpunitrunner -a TEST_DIRECTORY phpunitrunner -a -w MONITORING_DIRECTORY1,MONITORING_DIRECTORY2,... TEST_DIRECTORY
For the specified directory, monitors for changes of files and directories. Tests are run as soon as changes are detected. The supported types of changes are as follows:
- Creates files and directories.
- Removes files and directories.
- Changes files.
The default target of monitoring is the test directory, one or more directories can be added by the -w option. Accordingly, it can monitor the production code and configuration files as well as the test code.
The monitoring interval are automatically adjusted based on the actual duration of scanning. The minimum is 5 seconds.
Stops on the first failure or error.¶
phpunitrunner --stop-on-failure ...
Stops the test run when the first failure or error is raised.
Specifies the test file pattern.¶
phpunitrunner --test-file-pattern=PATTERN ...
Specifies the pattern of your test files by a regular expression literal.
The default values are:
| PHPUnit | Test(?:Case)?\.php$ |
|---|---|
| CIUnit | ^test.+\.php$ |
| SimpleTest | Test(?:Case)?\.php$ |
| CakePHP | \.test\.php$ |
| PHPT | - |
| PHPSpec | Spec\.php$ |
Reporting Test Results¶
Colors test results.¶
phpunitrunner -c ...
NOTE: To use this functionality, Console_Color 1.0.2 or greater is required. This functionality is not available in Windows.
It become easier to understand whether each test and all tests were passed or not.
Notifies test results.¶
phpunitrunner -n ... phpunitrunner -n --growl-password=PASSWORD ...
Notifies test results. If the password is required, it can be specified by the --growl-password option.
The command to be used for notifications differs depending on OS you use.
NOTE: The command must be available in your path.
| OS | Command | Prerequisite Software |
|---|---|---|
| Windows | growlnotify | Growl for Windows |
| Mac OS X | growlnotify | Growl |
| Linux | notify-send | the libnotify-bin package (in Ubuntu) |
Logs test results into the specified file in the JUnit XML format.¶
phpunitrunner --log-junit=FILE ... phpunitrunner --log-junit=FILE --log-junit-realtime ...
Logs test results into the specified file in the JUnit XML format. And also, the test results get to be written in real-time by element-by-element by specifying the --log-junit-realtime option.
Prints detailed progress report.¶
phpunitrunner -v ...
By using this feature, the test which is causing the problem can be found easier if the test run is terminated before completion by PHP fatal error etc.
Testing Framework Specific Features¶
PHPUnit¶
Configures the PHPUnit runtime environment by the XML configuration file.¶
phpunitrunner --phpunit-config=FILE ...
Configures the PHPUnit runtime environment by the specified XML configuration file. For more information, see PHPUnit Manual - Appendix C. The XML Configuration File.
NOTE: The <testsuites> element is not supported.
CIUnit¶
Specifies the path of your CIUnit tests directory.¶
ciunitrunner --ciunit-path=DIRECTORY ...
Specifies the path of your CIUnit tests directory. By default, the current working directory is used.
CakePHP¶
NOTE: The SimpleTest package must be placed in the vendors directory as vendors/simpletest.
Specifies the path of your app folder.¶
cakerunner --cakephp-app-path=DIRECTORY ...
Specifies the path of your app folder. By default, the current working directory is used.
Specifies the path of your CakePHP libraries folder.¶
cakerunner --cakephp-core-path=DIRECTORY ...
Specifies the path of your CakePHP libraries folder (/path/to/cake). By default, the cake directory under the parent directory of your app folder is used. (/path/to/app/../cake)
Available Features by Testing Framework¶
| PHPUnit, CIUnit | SimpleTest, CakePHP | PHPT | PHPSpec | |
|---|---|---|---|---|
| Runs tests in the specified directory. | Yes | Yes | Yes | Yes |
| Runs tests in the specified file. | Yes | Yes | Yes | Yes |
| Runs only the specified tests in the specified file. | Yes | Yes | ||
| Runs only the tests in the specified classes. | Yes | Yes | ||
| Colors test results. | Yes | Yes | Yes | Yes |
| Preloads the specified PHP script before running tests. | Yes | Yes | Yes | Yes |
| Monitors for changes in the specified directories and run tests when changes are detected. | Yes | Yes | Yes | Yes |
| Notifies test results. | Yes | Yes | Yes | Yes |
| Logs test results into the specified file in the JUnit XML format. | Yes | Yes | Yes | |
| Prints detailed progress report. | Yes | Yes | ||
| Stops on the first failure or error. | Yes | Yes | Yes | |
| Specifies the test file pattern. | Yes | Yes | Yes | |
| Specifies the test file suffix. | Yes | Yes | Yes |
notification-passed.png (199.1 kB)
