テストアノテーション
**********

.[perex]
アノテーションは、テストが [コマンドラインテストランナー |running-tests] によってどのように扱われるかを決定します。これらはテストファイルの先頭に記述されます。

アノテーションでは大文字と小文字は区別されません。また、テストが通常の PHP スクリプトとして手動で実行される場合、何の効果もありません。

例：

```php
/**
 * TEST: Basic database query test.
 *
 * @dataProvider files/databases.ini
 * @exitCode 56
 * @phpVersion < 5.5
 */

require __DIR__ . '/../bootstrap.php';
```


TEST .[filter]
--------------
これは実際にはアノテーションではなく、失敗時またはログに出力されるテストのタイトルを指定するだけです。


@skip .[filter]
---------------
テストはスキップされます。テストを一時的に無効にするのに役立ちます。


@phpVersion .[filter]
---------------------
対応する PHP バージョンで実行されていない場合、テストはスキップされます。アノテーションは `@phpVersion [operator] version` として記述します。演算子は省略でき、デフォルトは `>=` です。例：

```php
/**
 * @phpVersion 5.3.3
 * @phpVersion < 5.5
 * @phpVersion != 5.4.5
 */
```


@phpExtension .[filter]
-----------------------
リストされているすべての PHP 拡張機能が読み込まれていない場合、テストはスキップされます。1 つのアノテーションに複数の拡張機能をリストするか、複数回使用できます。

```php
/**
 * @phpExtension pdo, pdo_pgsql, pdo_mysql
 * @phpExtension json
 */
```


@dataProvider .[filter]
-----------------------
テストファイルを複数回実行したいが、異なる入力データで実行したい場合、このアノテーションが役立ちます。（[TestCase |TestCase#dataProvider] の同名のアノテーションと混同しないでください。）

`@dataProvider file.ini` として記述します。ファイルへのパスはテストファイルからの相対パスと見なされます。テストは INI ファイル内のセクションの数だけ実行されます。INI ファイル `databases.ini` を想定します。

```ini
[mysql]
dsn = "mysql:host=127.0.0.1"
user = root
password = ******

[postgresql]
dsn = "pgsql:host=127.0.0.1;dbname=test"
user = postgres
password = ******

[sqlite]
dsn = "sqlite::memory:"
```

そして、同じディレクトリにあるテスト `database.phpt`：

```php
/**
 * @dataProvider databases.ini
 */

$args = Tester\Environment::loadData();
```

テストは 3 回実行され、`$args` には常に `mysql`、`postgresql`、または `sqlite` セクションの値が含まれます。

アノテーションを疑問符付きで `@dataProvider? file.ini` として記述するバリアントもあります。この場合、INI ファイルが存在しない場合、テストはスキップされます。

アノテーションの可能性はこれで終わりではありません。INI ファイル名の後に、特定のセクションに対してテストが実行される条件を指定できます。INI ファイルを拡張します。

```ini
[mysql]
dsn = "mysql:host=127.0.0.1"
user = root
password = ******

[postgresql 8.4]
dsn = "pgsql:host=127.0.0.1;dbname=test"
user = postgres
password = ******

[postgresql 9.1]
dsn = "pgsql:host=127.0.0.1;dbname=test;port=5433"
user = postgres
password = ******

[sqlite]
dsn = "sqlite::memory:"
```

そして、条件付きのアノテーションを使用します。

```php
/**
 * @dataProvider  databases.ini  postgresql, >=9.0
 */
```

テストは `postgresql 9.1` セクションに対して 1 回だけ実行されます。他のセクションは条件フィルタを通過しません。

同様に、INI ファイルの代わりに PHP スクリプトを参照できます。これは配列または Traversable を返す必要があります。ファイル `databases.php`：

```php
return [
	'postgresql 8.4' => [
		'dsn' => '...',
		'user' => '...',
	],

	'postgresql 9.1' => [
		'dsn' => '...',
		'user' => '...',
	],
];
```


@multiple .[filter]
-------------------
`@multiple N` として記述します。ここで `N` は整数です。テストは正確に N 回実行されます。


@testCase .[filter]
-------------------
アノテーションにはパラメータがありません。[TestCase |TestCase] クラスとしてテストを作成する場合に使用します。この場合、コマンドラインテストランナーは個々のメソッドを個別のプロセスで並行して複数のスレッドで実行します。これにより、テストプロセス全体が大幅に高速化される可能性があります。


@exitCode .[filter]
-------------------
`@exitCode N` として記述します。ここで `N` は実行されたテストのリターンコードです。たとえば、テストで `exit(10)` が呼び出された場合、アノテーションを `@exitCode 10` として記述し、テストが別のコードで終了した場合、それは失敗と見なされます。アノテーションが指定されていない場合、リターンコード 0（ゼロ）が検証されます。


@httpCode .[filter]
-------------------
アノテーションは、PHP バイナリが CGI の場合にのみ適用されます。それ以外の場合は無視されます。`@httpCode NNN` として記述します。ここで `NNN` は期待される HTTP コードです。アノテーションが指定されていない場合、HTTP コード 200 が検証されます。`NNN` がゼロに評価される文字列、たとえば `any` として記述された場合、HTTP コードは検証されません。


@outputMatch および @outputMatchFile .[filter]
-------------------------------------------
アノテーションの機能は、アサーション `Assert::match()` および `Assert::matchFile()` と同じです。ただし、パターンはテストが標準出力に出力したテキスト内で検索されます。これは、テストが致命的なエラーで終了すると予想され、その出力を検証する必要がある場合に役立ちます。


@phpIni .[filter]
-----------------
テストの INI 設定値を設定します。たとえば、`@phpIni precision=20` として記述し、コマンドラインからパラメータ `-d precision=20` を介して値を指定した場合と同じように機能します。