こんな「困った」時の話
「異常時に例外を投げる、正常に完了したらvoidとなる」というようなメソッドがあるとします。
こんな時に、PHPUnitでどのように単体テストを書けばいいでしょうか？
PHPUnitでは、1つもassertionがないテストを「Risky」としてマークします。これは賢いのですが、しかし「返り値をとれないメソッド」=assertionを置けないテストケースについてRiskyになってしまうのが困る・・・と悩んでいました。
結論: @doesNotPerformAssertions を使えそう
テストケースのアノテーションに @doesNotPerformAssertions を入れると、「これはリスキーじゃないぞ」という事を示すことができそうです。
以下、「こうやって対処してきた」「これからは@doesNotPerformAssertionsを使いたいかも」という話をします。
いろいろな書き方
例えば、「(内容をバリデーションして)引き渡されたデータに誤りがあれば例外を投げる、問題がなければ何もしない」というメソッド denyIfInvalidData() があったとします。
微妙い例①
例えば「AssertTrue(true)をして無理矢理やるなどしていました。
public function testDenyIfInvalidDataValidData()
{
$data = ['requiredKey' => true];
$this->subject->denyIfInvalidData($validData);
// ここまで到達したらOK
$this->assertTrue(true);
}
気持ち悪いな〜〜という思いがあります。
微妙い例②
次に思いつくのが、「catchブロックに到達しなかったらOKでは」という発想です。
public function testDenyIfInvalidDataValidData()
{
$data = ['requiredKey' => true];
try {
$this->subject->denyIfInvalidData($validData);
} catch (\InvalidArgumentException $e) {
$this->fail('問題ないデータなのに拒絶されている');
} finally {
$this->assertFalse(!isset($e), '例外が発生している');
}
}
これで、「例外が生じていなければOK」という流れは作ることができました。
しかしどうにも冗長だし、 Test as documentation の観点から「簡潔さ」が実現できていないように思います。(「例外が生じていないこと」に、なぜアサーションを2つも書かなければ行けないのでしょう？)
微妙い例③ -> 悪い例
「返り値がない」ので、 null 扱いができますね・・・PHPerのみなさん・・・
public function testDenyIfInvalidDataValidData()
{
$data = ['requiredKey' => true];
$this->assertNull(
$this->subject->denyIfInvalidData($validData);
'問題ないデータなのに拒絶されている'
);
}
「動き上の問題はない」と思われるのですが、これはPHPStan・Phan・PhpStorm等のコードを解析ツールに掛けると警告されるやり方です。そのくらい「悪い」と言えるでしょう。
PHPStan: Result of function method (void) is used.
Phan: PhanTypeVoidAssignment
PhpStorm: 'void' method METHOD result used.
これでいいのでないか、という例
@doesNotPerformAssertions を利用すると、こうなります
/**
* @doesNotPerformAssertions
*/
public function testDenyIfInvalidDataValidData()
{
$data = ['requiredKey' => true];
$this->subject->denyIfInvalidData($validData);
}
記述量的にももちろん冗長さがないし、これなら「何を言いたいのか」というのがちゃんと際立つのではないでしょうか。
実行結果は OK (1 test, 0 assertions) となり、問題なくグリーンとなります。
もしこのアノテーションを付けていなかった場合、 OK, but incomplete, skipped, or risky tests!sky tests! となりグリーンとはなりません。
@doesNotPerformAssertions とは何なのか
それでは、コイツは一体何者なのでしょうか？
今回話題に上げている内容の正にそのままなのですが、「テストケースがRiskyとして扱われる事を回避する」ためのものです。
https://phpunit.readthedocs.io/ja/latest/annotations.html?highlight=doesNotPerformAssertions#doesnotperformassertions
ズバリですね。「リスキーとみなさない」という表現は何とも消極的な気はしますが、「異常が無いことを保証する」という点で単体テストの本義は十分に果たせると思いますし、またSUTの実行も勿論走るのでカバレッジにも寄与することと思います。
関連するIssue
長らくPHPUnitに触れてきたのに今まで何で気づいてなかったん・・？という感はあるのですが、私がこの「ヒント」に辿り着けたのは以下の議論を発見できたからでした。
https://github.com/sebastianbergmann/phpunit-documentation/issues/171
おわり
そもそも「単体テストをする」という意味で言えば「返り値を見る」という方がシンプルそうだし、そのように予め設計する〜というのも1つの考え方なのかもしれません。
とはいえreturn voidが「絶対に利用すべきでない」というものでもないはずですし、プロダクトコードにせよテストコードにせよ「筆者の気持ちがわかる」ような記述を心懸けながらパワフルで意義深いコードを書いていければ良いかな〜と思いました。