初めに🌸
Claude Codeに90ユースケース分のユニットテストを生成させ、全部グリーンになったあとレビューして見つけた話です。ただし原因はAI固有のものではなく、例外クラスの設計とPHPUnitのAPIの噛み合わせにあります。手で書いていても同じ穴を踏みます。
TL:DR
- 「開発者向け」と「外部向け」の2つのメッセージを持つ例外クラスがある
-
parent::__construct()に渡しているのは開発者向けのほうだけ - つまり
getMessage()は外部向けメッセージを返さない -
expectExceptionMessage()はgetMessage()への部分一致なので、既定文言に引っかかって通ってしまう - 実装から外部向けメッセージを丸ごと削除しても、テストはグリーンのまま
環境: PHP 8.3 / PHPUnit 10
発端
ユースケース1本分のテストをテンプレートとして手で書き、それを参照実装として指定したうえで、残る全90ユースケースのユニットテストをClaude Codeにまとめて生成させました。実行したところ、全部グリーンになりました。
ただ、グリーンだからといってAIの出力が正しいとは限りません。むしろ「通ることを目的に書かれたテスト」が混ざるのは、生成させる以上は当然起こることだと思っています。なので通ったあとに全件レビューを回しました。
そこで、例外まわりの検証が足りていないテストに気づきました。たとえばこういうものです。
public function testThrowsNotFoundExceptionWhenOrderMissing(): void
{
$this->expectException(NotFoundException::class);
$this->expectExceptionMessage('見つかりません');
$service->find('ORD-001');
}
実装側はこうなっています。
throw new NotFoundException(
externalMessage: '注文番号が見つかりませんでした: ' . $orderNumber
);
一見、噛み合っています。「見つかりません」は確かにメッセージに含まれている。
でも、このテストは実装が組み立てたメッセージを一切見ていません。
問題の例外クラス
原因は例外クラスの設計にありました。メッセージが2つあります。
final class NotFoundException extends RuntimeException
{
public function __construct(
private string $messageForDevelopers = 'リクエストされたリソースが見つかりませんでした',
private string $externalMessage = 'Not found',
) {
// ここに渡しているのは messageForDevelopers のほう
parent::__construct($this->messageForDevelopers);
}
public function externalMessage(): string
{
return $this->externalMessage;
}
}
-
messageForDevelopers… ログ用。parent::__construct()に渡されるのでgetMessage()はこれを返す -
externalMessage… APIレスポンスとしてユーザーに返る文言。getMessage()からは到達できない
呼び出し側は名前付き引数で externalMessage だけを指定していました。つまり messageForDevelopers は既定値のままです。
そして既定値は 'リクエストされたリソースが見つかりませんでした'。
――「見つかりません」を含んでいます。
再現
final class OrderService
{
/** @param string[] $existingOrderNumbers */
public function __construct(private array $existingOrderNumbers = []) {}
public function find(string $orderNumber): string
{
if (!in_array($orderNumber, $this->existingOrderNumbers, true)) {
throw new NotFoundException(
externalMessage: '注文番号が見つかりませんでした: ' . $orderNumber
);
}
return $orderNumber;
}
}
これに対して先ほどのテストを流します。
PHPUnit 10.0.19 by Sebastian Bergmann and contributors.
. 1 / 1 (100%)
OK (1 test, 2 assertions)
通ります。ただし通っているのは既定の開発者向け文言に対してであって、'注文番号が見つかりませんでした: ORD-001' は検証されていません。
実装を壊してみる
テストの価値は「通ること」ではなく「壊れたときに落ちること」で決まります。確かめてみましょう。
externalMessage の指定を丸ごと削除します。API利用者には 'Not found' しか返らなくなる、明確な退行です。
public function find(string $orderNumber): string
{
if (!in_array($orderNumber, $this->existingOrderNumbers, true)) {
throw new NotFoundException(); // 退行: externalMessage を消した
}
return $orderNumber;
}
同じテストを流します。
. 1 / 1 (100%)
OK (1 test, 2 assertions)
グリーンのままです。
このテストは、最初から何も守っていませんでした。
なぜ気づきにくいのか
「もっと丁寧なアサーションを使えば防げたのでは」と思うかもしれません。しかしPHPUnitの例外系アサーションは、どれも同じ壁にぶつかります。
| API | 見ているもの |
|---|---|
expectException() |
例外クラス |
expectExceptionMessage() |
getMessage() への部分一致 |
expectExceptionMessageMatches() |
getMessage() への正規表現 |
expectExceptionCode() |
getCode() |
expectExceptionObject() |
上記のクラス・メッセージ・コードをまとめて指定するショートカット |
一番丁寧に見える expectExceptionObject() も、実装は次の3行に展開されるだけです。
$this->expectException($exception::class);
$this->expectExceptionMessage($exception->getMessage());
$this->expectExceptionCode($exception->getCode());
PHPUnitの例外アサーションは、例外の独自プロパティに構造的に到達できません。 externalMessage のような独自メッセージを持たせた時点で、標準APIの射程から外れます。
さらに厄介なのが、既定メッセージが「それらしい日本語」であることです。'リクエストされたリソースが見つかりませんでした' は、見つかりません にも リソース にも リクエスト にも部分一致します。アサーションを短く書くほど、既定文言に吸い込まれて通ってしまう。
部分一致は書くのが楽なので、AIに生成させると特にここに寄ります。
対策
1. 独自プロパティは自分で検証する
public function testThrowsNotFoundExceptionWithOrderNumberInExternalMessage(): void
{
$service = new OrderService([]);
try {
$service->find('ORD-001');
$this->fail('NotFoundException が投げられませんでした');
} catch (NotFoundException $e) {
$this->assertSame(
'注文番号が見つかりませんでした: ORD-001',
$e->externalMessage()
);
}
}
expectException 系ではなく try-catch で受けて、assertSame で完全一致を取ります。先ほどの壊した実装に対してはこうなります。
1) OrderServiceFixedTest::testThrowsNotFoundExceptionWithOrderNumberInExternalMessage
Failed asserting that two strings are identical.
--- Expected
+++ Actual
@@ @@
-'注文番号が見つかりませんでした: ORD-001'
+'Not found'
意図した通りレッドになりました。
2. 部分一致より完全一致
短い部分一致は既定文言に吸い込まれます。特に既定値が汎用的な日本語の場合は assertSame を基本にしたほうが安全です。
3. 検証用ヘルパーを共通化する
同じ例外クラスを何十箇所でも使うなら、テスト側にヘルパーを置くほうが確実です。
protected function assertThrowsWithExternalMessage(
string $expectedMessage,
callable $callable
): void {
try {
$callable();
$this->fail('例外が投げられませんでした');
} catch (NotFoundException $e) {
$this->assertSame($expectedMessage, $e->externalMessage());
}
}
まとめ
例外クラスに独自メッセージを持たせるのは、ログと外部公開の分離としては妥当な設計です。問題はその設計がテスト側に伝わっていないことでした。
-
getMessage()が返すのはどのプロパティなのか、例外クラスの実装で確認する - 既定メッセージが「それらしい日本語」だと、部分一致は簡単に空振りする
- そして最終的な判断基準は「テストが通ったか」ではなく 「実装を壊したときに落ちるか」
自分のプロジェクトの例外クラスに parent::__construct() が複数の引数候補を持っていないか、一度確認してみてください。
検証環境
- PHP 8.3.6
- PHPUnit 10.0.19