Stagehand_TestRunner User Guide¶

This user guide describes the versions from Stagehand_TestRunner 2.7.0 to Stagehand_TestRunner 2.17.1.

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.
    • Specifies the test file suffix.
  • Reporting Test Results
    • Colors test results.
    • Notifies test results to Growl.
    • Logs test results into the specified file in the JUnit XML format.
    • Prints detailed progress report.
  • Testing Framework Specific Features
    • PHPUnit
      • Configures the PHPUnit runtime environment by the XML configuration file.
    • CIUnit
      • Specifies the path of your CIUnit tests directory.
    • CakePHP
      • Specifies the path of your app folder.
      • Specifies the path of your CakePHP libraries folder.
  • Available Features

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: As of the version 2.9.0, 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: As of the version 2.9.0, 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: As of the version 2.8.0, 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.¶

(Stagehand_TestRunner >= 2.8.0)

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.

tests/prepare.php:

<?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.¶

(Stagehand_TestRunner >= 2.11.0)

phpunitrunner --stop-on-failure ...

Stops the test run when the first failure or error is raised.

Specifies the test file pattern.¶

(Stagehand_TestRunner >= 2.16.0)

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$

Specifies the test file suffix.¶

deprecated in Stagehand_TestRunner 2.16.0

(Stagehand_TestRunner >= 2.14.0)

phpunitrunner --test-file-suffix=SUFFIX ...

Specifies the suffix of your test files by a regular expression literal. The regular expression literal must not contain .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 to Growl.¶

phpunitrunner -g ...
phpunitrunner -g --growl-password=PASSWORD ...

NOTE: To use this feature, Net_Growl 0.7.0 or greater is required.

Notifies test results to Growl. If the password is required, it can be specified by the --growl-password option.

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. As of the version 2.10.0, 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.¶

(Stagehand_TestRunner >= 2.14.0)

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 and <selenium> element are not supported.

NOTE: As of the version 2.16.0, the <selenium> element has been supported.

CIUnit¶

(Stagehand_TestRunner >= 2.16.0)

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¶

(Stagehand_TestRunner >= 2.14.0)

NOTE: As of the version 2.14.1, 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¶

	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	>= 2.10.0
Runs only the tests in the specified classes.	>= 2.8.0	>= 2.10.0
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 to Growl.	Yes	Yes	Yes	Yes
Logs test results into the specified file in the JUnit XML format.	Yes	>= 2.10.0	Yes
Prints detailed progress report.	Yes		Yes
Stops on the first failure or error.	>= 2.11.0	>= 2.11.0	>= 2.11.0
Specifies the test file pattern.	>= 2.16.0	>= 2.16.0		>= 2.16.0
Specifies the test file suffix.	>= 2.14.0	>= 2.14.0		>= 2.14.0