New Feature: #[SkipOpenApi] 属性で auto-assert を個別テスト単位でオプトアウト

[wadakatu]

概要

auto-assert モード下で個別テストを契約検証から除外するための #[SkipOpenApi] 属性を追加します。わざと spec 違反を返すテストや、契約が固まっていない実験的エンドポイントを扱うテストで利用できます。

変更内容

反射ベースの属性で method-level / class-level の双方をサポートし、reason パラメータを受け取れます。method-level が class-level を上書きします。

• src/SkipOpenApi.php: 属性クラス（TARGET_CLASS | TARGET_METHOD、reason: string = ''）
• src/SkipOpenApiResolver.php: OpenApiSpecResolver と同じ流儀の reflection ベース resolver trait（shouldSkipOpenApi() / resolveSkipOpenApiReason()）
• src/Laravel/ValidatesOpenApiSchema.php:
  • maybeAutoAssertOpenApiSchema() で skip なら早期 return（検証なし・OpenApiCoverageTracker にも未記録 = 未カバレッジ扱い）
  • assertResponseMatchesOpenApiSchema() 明示呼び出しは 常に走る（option A の意図表明尊重）。ただし #[SkipOpenApi] 付きテストで明示呼び出しすると E_USER_DEPRECATED を発行し、矛盾した意図を可視化
  • 警告ハンドラは $skipWarningHandler static プロパティ経由で差し替え可能（テスタビリティのため）
• tests/Unit/SkipOpenApiResolver{,ClassLevel}Test.php: resolver 単体テスト（no attr / method / class / method-reason override）
• tests/Unit/ValidatesOpenApiSchema{,ClassLevel}SkipTest.php: auto-assert スキップ挙動 + 警告挙動
• tests/Integration/Laravel/AutoAssertIntegrationTest.php: Testbench 経由の method-level skip 統合テスト
• README.md: Auto-assert セクション下に #[SkipOpenApi] の使い方・セマンティクス・警告挙動を追記

設計メモ（レビュー観点）

• option A（緩い）セマンティクス: 属性は auto-assert のみ抑制。明示呼び出しまで抑制すると class-level skip + 一部 method での明示検証という正当パターンが書けなくなるため。
• 警告を E_USER_DEPRECATED に: phpunit.xml.dist は failOnWarning=true のため E_USER_WARNING は使えない。failOnDeprecation はデフォルト false なので deprecation 通知はテストを落とさず PHPUnit サマリに可視化される（Symfony/Laravel でも馴染みのパターン）。
• method-level が class-level を override: 属性は on/off トグルを持たないため net skip 挙動は同じだが、reason は method 側が優先されるよう実装。

品質ゲート

• PHPUnit: 217/217 green（新規 10 テスト）
• PHPStan (level 6): errors なし
• php-cs-fixer: violations なし

関連情報

• Closes [E1] Add #[SkipOpenApi] attribute to opt out of auto-validation per test #40
• Epic: [E1] Auto-validate responses via TestResponse macro hook #39 (auto-assert) に続く機能

[wadakatu]

レビューフィードバック対応 (4 commits)

/pr-review-toolkit:review-pr の指摘を反映しました。

🔴 Critical 対応

• warning の可視性: trigger_error(E_USER_DEPRECATED) は PHPUnit デフォルトでは "1 deprecation" の数字のみ表示され、メッセージ本文は displayDetailsOnTestsThatTriggerDeprecations を明示設定しない限り不可視。CI で見逃されるリスクを解消するため STDERR への直接書き込み + trigger_error の併用 に変更。STDERR 書き込みはどの PHPUnit 設定でも可視。(ce14a79)

🟠 Important 対応

• reflection 重複呼び出し: skip + explicit call の経路で findSkipOpenApiAttribute() が 2〜3 回呼ばれていたため、assertResponseMatchesOpenApiSchema() 冒頭で 1 回だけ resolve して emitSkipOpenApiWarning(SkipOpenApi $attr) に渡す形に。副作用として resolveSkipOpenApiReason() の「attribute なし」と「attribute あり・reason 空」を混同する ambiguity も解消。(277086f)
• テストギャップ:
  • default warning handler (STDERR + trigger_error fallback) 自体のテストが無かった → ValidatesOpenApiSchemaDefaultWarningHandlerTest 新規追加、set_error_handler で E_USER_DEPRECATED を捕捉
  • class-level skip での explicit-call warning 未検証 → class_level_skip_emits_warning_with_class_reason_on_explicit_assert 追加
  • warning message の reason: '...' フォーマット (var_export) 未検証 → warning_message_includes_reason_when_provided 追加
  • 統合テストが GET のみ → POST 版追加
  • ValidatesOpenApiSchemaClassLevelSkipTest に handler setUp/tearDown が無く cross-test contamination リスク → 同ファイルに handler 管理を追加 (a36734c)
• README 不正確さ:
  • 「method-level takes precedence (reason wins)」→ 誤解を招く（属性全体が shadow される） → 「fully shadows」に訂正
  • 「skip で coverage 記録されない」→ explicit call の場合は記録されるので条件付きに訂正
  • 親クラス #[SkipOpenApi] が継承されない制約を新規注記 (dbffbf5)

🟡 その他

• SkipOpenApiResolver の WHAT コメント削除
• $skipWarningHandler docblock から "option A semantics" jargon を平文化

品質ゲート

• PHPUnit: 221/221 green（新規 4 テスト: default handler, reason format, class-level warning, POST skip）
• PHPStan lv6 / php-cs-fixer: 引き続き clean