第5章 コマンドラインのテストランナー

phpunit コマンドを実行すると、PHPUnit のコマンドライン版テストランナーが起動します。 コマンドラインのテストランナーを使用したテストの様子を以下に示します。

phpunit ArrayTest
PHPUnit 3.7.0 by Sebastian Bergmann.

..

Time: 0 seconds


OK (2 tests, 2 assertions)

このように実行すると、PHPUnit のコマンドラインテストランナーは、 まず現在の作業ディレクトリにあるソースファイル ArrayTest.php を探してそれを読み込み、テストケースクラス ArrayTest を探します。 そして、そのクラス内のテストを実行します。

テストがひとつ実行されるたびに、PHPUnit コマンドラインツールはその経過を示す文字を出力します。

.

テストが成功した際に表示されます。

F

テストメソッドの実行中、アサーションに失敗した際に表示されます。

E

テストメソッドの実行中、エラーが発生した際に表示されます。

S

テストが飛ばされた場合に表示されます (第 9 章 を参照ください)。

I

テストが「不完全」あるいは「未実装」とマークされている場合に表示されます (第 9 章 を参照ください)。

PHPUnit は、失敗 (failures)エラー (errors) を区別します。 「失敗」は PHPUnit のアサーションに違反した場合、つまり例えば assertEquals() のコールに失敗した場合などで、 「エラー」は予期せぬ例外や PHP のエラーが発生した場合となります。 この区別は、時に有用です。というのは「エラー」は一般的に「失敗」 より修正しやすい傾向があるからです。 もし大量の問題が発生した場合は、まず「エラー」を最初に片付け、 その後で「失敗」を修正していくのが最良の方法です。

Command-Line switches

以下のコードで、コマンドライン版テストランナーのスイッチの一覧を見てみましょう。

phpunit --help
PHPUnit 3.7.0 by Sebastian Bergmann.

Usage: phpunit [switches] UnitTest [UnitTest.php]
       phpunit [switches] <directory>

  --log-junit <file>        Log test execution in JUnit XML format to file.
  --log-tap <file>          Log test execution in TAP format to file.
  --log-json <file>         Log test execution in JSON format.

  --coverage-clover <file>  Generate code coverage report in Clover XML format.
  --coverage-html <dir>     Generate code coverage report in HTML format.
  --coverage-php <file>     Serialize PHP_CodeCoverage object to file.
  --coverage-text=<file>    Generate code coverage report in text format.
                            Default to writing to the standard output.

  --testdox-html <file>     Write agile documentation in HTML format to file.
  --testdox-text <file>     Write agile documentation in Text format to file.

  --filter <pattern>        Filter which tests to run.
  --testsuite <pattern>     Filter which testsuite to run.
  --group ...               Only runs tests from the specified group(s).
  --exclude-group ...       Exclude tests from the specified group(s).
  --list-groups             List available test groups.
  --test-suffix ...         Only search for test in files with specified
                            suffix(es). Default: Test.php,.phpt

  --loader <loader>         TestSuiteLoader implementation to use.
  --printer <printer>       TestSuiteListener implementation to use.
  --repeat <times>          Runs the test(s) repeatedly.

  --tap                     Report test execution progress in TAP format.
  --testdox                 Report test execution progress in TestDox format.

  --colors                  Use colors in output.
  --stderr                  Write to STDERR instead of STDOUT.
  --stop-on-error           Stop execution upon first error.
  --stop-on-failure         Stop execution upon first error or failure.
  --stop-on-skipped         Stop execution upon first skipped test.
  --stop-on-incomplete      Stop execution upon first incomplete test.
  --strict                  Run tests in strict mode.
  -v|--verbose              Output more verbose information.
  --debug                   Display debugging information during test execution.

  --process-isolation       Run each test in a separate PHP process.
  --no-globals-backup       Do not backup and restore $GLOBALS for each test.
  --static-backup           Backup and restore static attributes for each test.

  --bootstrap <file>        A "bootstrap" PHP file that is run before the tests.
  -c|--configuration <file> Read configuration from XML file.
  --no-configuration        Ignore default configuration file (phpunit.xml).
  --include-path <path(s)>  Prepend PHP's include_path with given path(s).
  -d key[=value]            Sets a php.ini value.

  -h|--help                 Prints this usage information.
  --version                 Prints the version and exits.
phpunit UnitTest

UnitTest という名前のクラスで定義されている テストを実行します。このクラスは、UnitTest.php という名前のファイルの中に定義されているものとします。

UnitTest は、PHPUnit_Framework_TestCase を継承したクラスであるか、あるいは PHPUnit_Framework_Test オブジェクト、例えば PHPUnit_Framework_TestSuite のインスタンスを返す public static suite() というメソッドを保持するクラスでなければなりません。

phpunit UnitTest UnitTest.php

UnitTest という名前のクラスで定義されているテストを実行します。 このクラスは、指定したファイルの中で定義されているものとします。

--log-junit

JUnit XML フォーマットを使用して、テストの実行結果のログを作成します。 詳細は 第 18 章 を参照ください。

--log-tap

Test Anything Protocol (TAP) フォーマットを使用して、テストの実行結果のログを作成します。 詳細は 第 18 章 を参照ください。

--log-json

JSON フォーマットを使用して、ログファイルを作成します。 詳細は 第 18 章 を参照ください。

--coverage-html

コードカバレッジレポートを HTML 形式で作成します。詳細は 第 14 章 を参照ください。

この機能は、tokenizer 拡張モジュールおよび Xdebug 拡張モジュールがインストールされている場合にのみ使用可能となることに注意しましょう。

--coverage-clover

テスト結果から XML 形式のログファイルを作成し、 コードカバレッジ情報もそこに含めます。 詳細は 第 18 章 を参照ください。

この機能は、tokenizer 拡張モジュールおよび Xdebug 拡張モジュールがインストールされている場合にのみ使用可能となることに注意しましょう。

--coverage-php

シリアライズした PHP_CodeCoverage オブジェクトを生成し、 コードカバレッジ情報もそこに含めます。

この機能は、tokenizer 拡張モジュールおよび Xdebug 拡張モジュールがインストールされている場合にのみ使用可能となることに注意しましょう。

--coverage-text

テストを実行したときに、ログファイルあるいはコマンドライン出力で 可読形式のコードカバレッジ情報を生成します。 詳細は 第 18 章 を参照ください。

この機能は、tokenizer 拡張モジュールおよび Xdebug 拡張モジュールがインストールされている場合にのみ使用可能となることに注意しましょう。

--testdox-html and --testdox-text

実行したテストについて、HTML あるいはプレーンテキスト形式のドキュメントを生成します 詳細は 第 15 章 を参照ください。

--filter

指定した正規表現パターンにマッチする名前のテストのみを実行します。 パターンがデリミタで囲まれていない場合は、PHPUnit はパターンをデリミタ / で囲みます。

マッチするテスト名は、次のいずれかのフォーマットになります。

TestNamespace\TestCaseClass::testMethod

デフォルトのテスト名のフォーマットは、テストメソッドの中でマジック定数 __METHOD__ を使うのと同等です。

TestNamespace\TestCaseClass::testMethod with data set #0

テストがデータプロバイダーを持つ場合、データを処理するたびに、 現在のインデックスをデフォルトのテスト名の後に続けたものを取得します。

TestNamespace\TestCaseClass::testMethod with data set "my named data"

テストが持つデータプロバイダーが名前つきセットを使う場合、データを処理するたびに、 現在の名前をデフォルトのテスト名の後に続けたものを取得します。 名前つきデータセットの例は 例 5.1 を参照ください。

例 5.1: 名前つきデータセット

<?php
namespace TestNamespace;

class TestCaseClass extends \PHPUnit_Framework_TestCase
{
    /**
     * @dataProvider provider
     */
    public function testMethod($data)
    {
        $this->assertTrue($data);
    }

    public function provider()
    {
        return array(
           'my named data' => array(true),
           'my data'       => array(true)
        );
    }
}
?>


/path/to/my/test.phpt

PHPT のテストのテスト名は、ファイルシステムのパスになります。

有効なフィルターパターンの例は、例 5.2 を参照ください。

例 5.2: フィルターパターンの例

  • --filter 'TestNamespace\\TestCaseClass::testMethod'

  • --filter 'TestNamespace\\TestCaseClass'

  • --filter TestNamespace

  • --filter TestCaseClass

  • --filter testMethod

  • --filter '/::testMethod .*"my named data"/'

  • --filter '/::testMethod .*#5$/'

  • --filter '/::testMethod .*#(5|6|7)$/'



--testsuite

指定したパターンにマッチする名前のテストスイートのみを実行します。

--group

指定したグループのテストのみを実行します。 あるテストを特定のグループに所属させるには、 @group アノテーションを使用します。

@author アノテーションは @group のエイリアスで、 テストの作者に基づいてテストをフィルタリングします。

--exclude-group

指定したグループをテストの対象外とします。 あるテストを特定のグループに所属させるには、 @group アノテーションを使用します。

--list-groups

使用可能なテストグループの一覧を表示します。

--test-suffix

指定したサフィックスのテストファイルだけを探します。

--loader

PHPUnit_Runner_TestSuiteLoader を実装したクラスのうち、 実際に使用するものを指定します。

標準のテストスイートローダーは、現在の作業ディレクトリおよび PHP の設定項目 include_path で指定されているディレクトリからソースファイルを探します。 PEAR の命名規則に従い、Project_Package_Class クラスがソースファイル Project/Package/Class.php に対応します。

--printer

結果を表示するために使うプリンタクラスを指定します。このプリンタクラスは PHPUnit_Util_Printer を継承し、かつ PHPUnit_Framework_TestListener インターフェイスを実装したものでなければなりません。

--repeat

指定された回数だけ、繰り返しテストを実行します。

--tap

Test Anything Protocol (TAP) を使用して、テストの進行状況を報告します。 詳細は 第 18 章 を参照ください。

--testdox

テストの進行状況を、アジャイルな文書として報告します。 詳細は 第 15 章 を参照ください。

--colors

出力に色を使用します。

--stderr

オプションで、出力先を STDOUT ではなく STDERR にします。

--stop-on-error

最初にエラーが発生した時点で実行を停止します。

--stop-on-failure

最初にエラーあるいは失敗が発生した時点で実行を停止します。

--stop-on-skipped

最初にテストのスキップが発生した時点で実行を停止します。

--stop-on-incomplete

最初に不完全なテストがあらわれた時点で実行を停止します。

--strict

テストを strict モードで実行します。strict モードを有効にすると、

  • 何かを出力するテストは失敗します。

  • アサーションが一つもないテストは失敗し、コードカバレッジ情報も生成しません。

  • PHP_Invoker パッケージがインストールされている場合は、

    • @large とマークされたテストは、 実行時間が 60 秒を超えたら失敗します。 このタイムアウト時間は、XML 設定ファイルの timeoutForLargeTests 属性で変更できます。

    • @medium とマークされたテストは、 実行時間が 10 秒を超えたら失敗します。 このタイムアウト時間は、XML 設定ファイルの timeoutForMediumTests 属性で変更できます。

    • @medium とも @large ともマークされていないテストは、 実行時間が 1 秒を超えたら失敗します。 このタイムアウト時間は、XML 設定ファイルの timeoutForSmallTests 属性で変更できます。

--verbose

より詳細な情報を出力します。例えば、 未完成のテストや省略したテストの名前が表示されます。

--process-isolation

各テストを個別の PHP プロセスで実行します。

--no-globals-backup

$GLOBALS のバックアップ・リストアを行いません。 詳細は 「グローバルな状態」 を参照ください。

--static-backup

ユーザ定義クラスの静的属性のバックアップ・リストアを行います。 詳細は 「グローバルな状態」 を参照ください。

--bootstrap

テストの前に実行される "ブートストラップ" PHP ファイルを指定します。

--configuration, -c

設定を XML ファイルから読み込みます。 詳細は 付録 C を参照ください。

phpunit.xml あるいは phpunit.xml.dist (この順番で使用します) が現在の作業ディレクトリに存在しており、かつ --configuration が使われていない場合、設定が自動的にそのファイルから読み込まれます。

--no-configuration

現在の作業ディレクトリにある phpunit.xml および phpunit.xml.dist を無視します。

--include-path

PHP の include_path の先頭に、指定したパスを追加します。

-d

指定した PHP 設定オプションの値を設定します。

--debug

テスト名などのデバッグ情報を、テストの実行開始時に出力します。

このページの改善案をGitHubで提案してください!