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

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

phpunit ArrayTest
PHPUnit 4.2.0 by Sebastian Bergmann.

..

Time: 0 seconds


OK (2 tests, 2 assertions)

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

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

.

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

F

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

E

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

R

テストが危険だとマークされている場合に表示されます (第 6 章 を参照ください)。

S

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

I

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

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

Command-Line switches

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

phpunit --help
PHPUnit 4.2.0 by Sebastian Bergmann.

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

Code Coverage Options:

  --coverage-clover <file>  Generate code coverage report in Clover XML format.
  --coverage-crap4j <file>  Generate code coverage report in Crap4J XML format.
  --coverage-html <dir>     Generate code coverage report in HTML format.
  --coverage-php <file>     Export PHP_CodeCoverage object to file.
  --coverage-text=<file>    Generate code coverage report in text format.
                            Default: Standard output.
  --coverage-xml <dir>      Generate code coverage report in PHPUnit XML format.

Logging Options:

  --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.
  --testdox-html <file>     Write agile documentation in HTML format to file.
  --testdox-text <file>     Write agile documentation in Text format to file.

Test Selection Options:

  --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

Test Execution Options:

  --report-useless-tests    Be strict about tests that do not test anything.
  --strict-coverage         Be strict about unintentionally covered code.
  --disallow-test-output    Be strict about output during tests.
  --enforce-time-limit      Enforce time limit based on test size.
  --strict                  Run tests in strict mode (enables all of the above).

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

  --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-risky           Stop execution upon first risky test.
  --stop-on-skipped         Stop execution upon first skipped test.
  --stop-on-incomplete      Stop execution upon first incomplete test.
  -v|--verbose              Output more verbose information.
  --debug                   Display debugging information during test execution.

  --loader <loader>         TestSuiteLoader 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.
  --printer <printer>       TestListener implementation to use.

Configuration Options:

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

Miscellaneous Options:

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

--coverage-clover

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

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

--coverage-crap4j

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

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

--coverage-html

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

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

--coverage-php

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

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

--coverage-text

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

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

--log-junit

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

--log-tap

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

--log-json

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

--testdox-html および --testdox-text

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

--filter

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

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

TestNamespace\TestCaseClass::testMethod

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

TestNamespace\TestCaseClass::testMethod with data set #0

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

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

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

例 3.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 のテストのテスト名は、ファイルシステムのパスになります。

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

例 3.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)$/'



データプロバイダーのマッチングに使えるショートカットは、 例 3.3 を参照ください。

例 3.3: フィルターのショートカット

  • --filter 'testMethod#2'

  • --filter 'testMethod#2-4'

  • --filter '#2'

  • --filter '#2-4'

  • --filter 'testMethod@my named data'

  • --filter 'testMethod@my.*data'

  • --filter '@my named data'

  • --filter '@my.*data'



--testsuite

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

--group

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

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

--exclude-group

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

--list-groups

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

--test-suffix

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

--report-useless-tests

何もテストをしないテストについて厳格にチェックします。 詳細は 第 6 章 を参照ください。

--strict-coverage

意図せずカバーしているコードについて厳格にチェックします。 詳細は 第 6 章 を参照ください。

--disallow-test-output

実行中に何かを出力するテストについて厳格にチェックします。 詳細は 第 6 章 を参照ください。

--enforce-time-limit

テストのサイズに応じて、制限時間を設定します。 詳細は 第 6 章 を参照ください。

--strict

テストを strict モードで実行します (--report-useless-tests--strict-coverage--disallow-test-output、 そして --enforce-time-limit を指定するのと同じ動きです)。詳細は 第 6 章 を参照ください。

--process-isolation

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

--no-globals-backup

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

--static-backup

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

--colors

出力に色を使用します。 Windows では、ANSICON あるいは ConEmu を利用します。

--stderr

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

--stop-on-error

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

--stop-on-failure

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

--stop-on-risky

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

--stop-on-skipped

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

--stop-on-incomplete

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

--verbose

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

--debug

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

--loader

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

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

--repeat

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

--tap

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

--testdox

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

--printer

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

--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 設定オプションの値を設定します。

注記

これらのオプションは、引数の後に指定してはいけないことに注意しましょう。

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