PHPUnit の使い方

PHPUnit をインストールする方法はいろいろありますが、Composer を使っている場合は Composer を使ってインストールするのが楽だと思います。 Composer を使って PHPUnit をインストールするには、下記のコマンドを実行するだけです。 基本的には開発環境で使うツールだと思うので、--dev オプションを付けておきましょう。 Composer の使い方がわからないという方は、まずは「Composer の使い方（その１：概要）」を参考にしてください。

php composer.phar require --dev "phpunit/phpunit"

.\vendor\bin\phpunit -h

# XAMPP の場合、phpunit とだけ入力すると、"C:\xampp\php\phpunit.bat" が動くので注意
phpunit -h

アサーションメソッドとは、テストしたいことが、正しいかどうかを判定するためのメソッドです。 テストメソッドの中で、アサーションメソッドを呼び出していく形で、テストを作成します。 アサーションメソッドのメソッド名は全て assert から始まります。

どんなメソッドがあるかは、ここでは記載しません。 あまりにも大量にありますので、公式のドキュメントを見てもらった方が良いと思います。

• 1. アサーション — PHPUnit latest Manual

各テストメソッドが呼ばれる際、その前処理と後処理を共通化したい場合、PHPUnit では setUp() と tearDown() というメソッドが用意されています。 このメソッドと同じ名前のメソッドをテストクラスに定義すると、各テストメソッドが呼ばれる際に自動的に呼んでくれます。 setUp() が前処理、tearDown() が後処理です。

<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

final class HogeTest extends TestCase
{
	public function setUp(): void
	{
		// 前処理
	}

	public function testHogeHoge(): void
	{
		$stack = [];
		$this->assertSame(0, count($stack));
	}

	public function tearDown(): void
	{
		// 後処理
	}
}

1つのファイルを実行する場合は、実行したいファイル名を指定します。 指定できるのは1つだけです。

.\vendor\bin\phpunit .\tests\HogeTest.php

複数のファイルを実行する場合は、実行したいディレクトリ名を指定します。 指定できるのは1つだけです。

.\vendor\bin\phpunit .\tests

デフォルトでは出力内容には色が付いていないので白黒な画面になってしまうと思われますが、この出力内容に色を付けることができます。 色を付けるには --colors オプションを付けます。 --colors オプションで指定できる値は下記の3つです。

• never：出力を色分けしません。これは、--colors オプション自体が未指定の場合のデフォルトです。
• auto：ターミナルが色をサポートしていない場合や、出力をコマンドにパイプしたりファイルにリダイレクトしたりする場合を除き、出力に色を使います。 --colors オプションでだけを指定して、値を何も指定しなかった場合は、auto を指定していることと同じになります。
• always：ターミナルが色をサポートしていない場合や、 出力をコマンドにパイプしたりファイルにリダイレクトしたりする場合も含めて、常に出力に色を使います。

# 値を省略した場合は --colors=auto と同じ
.\vendor\bin\phpunit --colors .\tests

PHPUnit 9.5.9 by Sebastian Bergmann and contributors.

..                                                                  2 / 2 (100%)

Time: 00:00.012, Memory: 4.00 MB

OK (2 tests, 10 assertions)

デフォルトでは、どこかのテストでエラーが発生しても、全てのテストの実行が終了するまで止まりません。 どこかのテストでエラーが発生するということは、それを使っている他の個所もまたエラーになるということです。 エラーが1つでも見つかったのなら、すぐにその時点で実行を止めて、エラーの個所を教えて欲しいと感じるでしょう。 全てのテストが終わるまで待っているのは、かなりの時間のロスになります。

注意しないといけないのは、最初に発生したエラーの発生個所がエラーの本当の原因ではない可能性があるということです。 あくまでテストの実行順的に最初に発生したというだけなので、エラーの本当の原因はさらに別の個所で発生したエラーである、という可能性があります。

エラーが発生した時点で停止させるには、--stop-on-failure オプションを使用します。

.\vendor\bin\phpunit --stop-on-failure .\tests

CakePHP や Laravel などの PHP フレームワークを使用しているアプリケーションのコードを PHPUnit でテストしたいとしましょう。 フレームワークは、アプリケーションの実行に必要な様々な処理を、初期化処理として自動的に行ってくれています。 言い換えれば、そのアプリケーションのコードは、単体では正しく動作しないということです。 フレームワークと組み合わせて初めて正しく動作するのです。

そのような何かに依存したコードを PHPUnit 上で動かすためには、その依存しているものが行っている前処理と同じ処理を、テストの前に実行しておく必要があります。

PHPUnit のテストの前に実行される処理は、PHP ファイルで、--bootstrap オプションで指定できます。

.\vendor\bin\phpunit --bootstrap=.\tests\bootstrap.php .\tests

設定ファイルを使用する方法は2つあります。

.\vendor\bin\phpunit -c .\custom_phpunit.xml

.\vendor\bin\phpunit

設定ファイルのフォーマットは XML です。 phpunit タグをルートとし、その中に設定内容のタグを記述していきます。 XMLなのでコメントも書けます。

どんな設定項目があるかは、ここでは記載しません。 あまりにも大量にありますので、公式のドキュメントを見てもらった方が良いと思います。

• 3. XML 設定ファイル — PHPUnit latest Manual

ここでは簡単な例だけ記載しておきます。

<?xml version="1.0" encoding="UTF-8"?>
<phpunit colors="true">

	<testsuites>
		<testsuite name="all">
			<directory>tests</directory>
		</testsuite>
	</testsuites>

</phpunit>

テストスイートを定義するには、設定ファイル内で、testsuites タグの中に、testsuite タグで定義していきます。 testsuite タグの name 属性でテストスイートの名前を指定できます。 この名前は、テストスイートを実行する際に使用する名前になります。

ファイルを指定する場合は、file タグを使用し、ディレクトリを指定する場合は、directory タグを使用します。

定義したテストスイートの一覧は設定ファイルを見てもわかりますが、--list-suits オプションを使用すると一覧表示してくれます。

.\vendor\bin\phpunit --list-suites

PHPUnit 9.5.9 by Sebastian Bergmann and contributors.

Available test suite(s):
 - model
 - money

定義したテストスイートを実行するには、--testsuite オプションで、実行したいテストスイートの名前を指定します。

ちなみに、--testsuite オプションを使用しない場合は、定義している全てのテストスイートが実行されます。 複数のテストスイートで重複しているテストがある場合、そのテストは1度だけ実行されますので、重複は気にしなくても良いでしょう。

.\vendor\bin\phpunit --testsuite money

グループはアノテーションとして定義します。 アノテーションというのは、PHP のドキュメンテーションコメントに @アノテーション名 引数 形式でコメントを書くことで、メタデータを定義するものです。 PHPDoc などで @param や、@return などが良く使われているので、見慣れているのはないでしょうか。

グループを定義するには、PHP のメソッドやクラスのドキュメンテーションコメントに @group グループ名 の形式で記載するだけです。 簡単に定義できるからと言って、むやみやたらにグループを作っていると、あっという間に管理できなくなるので注意しましょう。

グループのアノテーションは @group の他にも、@author 、@ticket などがあります。 これらは、@group のエイリアス（別名）ですので、@group と同じように使用できます。

定義したグループの一覧を表示するには、--list-groups オプションを使用します。

.\vendor\bin\phpunit --list-groups

PHPUnit 9.5.9 by Sebastian Bergmann and contributors.

Available test group(s):
 - #1234
 - bug2204
 - default
 - hogehoge
 - my
 - regresssion

定義したグループを実行するには、--group オプションで、実行したいグループの名前を指定します。

.\vendor\bin\phpunit --group bug2204

コードカバレッジを出力するには、まずテスト対象のコードがどこにあるか指定する必要があります。 テストコードの場所ではなく、実際のソースコードの場所です。 指定する方法は2つあります。

.\vendor\bin\phpunit --coverage-filter .\src

<?xml version="1.0" encoding="UTF-8"?>
<phpunit colors="true">

	<testsuites>
		<testsuite name="all">
			<directory>tests</directory>
		</testsuite>
	</testsuites>

	<coverage>
		<include>
			<directory>src</directory>
		</include>
	</coverage>

</phpunit>

カバレッジレポートをHTMLで出力するには、--coverage-html オプションで出力先ディレクトリを指定します。 指定したディレクトリの中に、カバレッジレポートがHTMLファイルとして出力されます。

HTMLで出力する --coverage-html オプションの他にも、テキストとして出力する --coverage-text オプションや、XMLファイルとして出力する --coverage-xml オプションなどもあります。

.\vendor\bin\phpunit --coverage-html coverage

Composer スクリプトから実行した場合に出力内容に色を付ける場合、--colors オプションを付けていても、色がちゃんとつかない場合があります。 設定ファイルで colors="true" を指定しても色がちゃんと付きません。 そもそも設定ファイルの colors 属性は xs:boolean 型なので、true か false のどちらかしか指定できません。 その場合は、--colors オプションの値に always を指定してみましょう。

{
	"name": "hoge/hoge",
	"require-dev": {
		"phpunit/phpunit": "^9.5"
	},
	"scripts": {
		"test": "phpunit --colors=always"
	}
}