Merge pull request #54 from studio-design/feature/auto-assert-test-response

New Feature: ValidatesOpenApiSchema trait に auto_assert オプションを追加し、HTTP レスポンスを自動検証

Author: wadakatu

README.md

@@ -85,6 +85,11 @@ return [
     // Maximum number of validation errors to report per response.
     // 0 = unlimited (reports all errors).
     'max_errors' => 20,
+
+    // Automatically validate every TestResponse produced by Laravel HTTP
+    // helpers (get(), post(), etc.) against the OpenAPI spec. Defaults to
+    // false for backward compatibility.
+    'auto_assert' => false,
 ];
 ```
 
@@ -223,6 +228,42 @@ $validator = new OpenApiResponseValidator(maxErrors: 1);
 
 For Laravel, set the `max_errors` key in `config/openapi-contract-testing.php`.
 
+#### Auto-assert every response
+
+Forgetting `$this->assertResponseMatchesOpenApiSchema($response)` in a test means the contract is silently unchecked. Enable `auto_assert` to validate every response produced by Laravel's HTTP helpers automatically — just include the trait:
+
+```php
+// config/openapi-contract-testing.php
+return [
+    'default_spec' => 'front',
+    'auto_assert'  => true,
+];
+```
+
+```php
+use Studio\OpenApiContractTesting\Laravel\ValidatesOpenApiSchema;
+
+class GetPetsTest extends TestCase
+{
+    use ValidatesOpenApiSchema;
+
+    public function test_list_pets(): void
+    {
+        // Contract is checked automatically — no explicit assert call needed.
+        $this->get('/api/v1/pets')->assertOk();
+    }
+}
+```
+
+Notes:
+
+- Defaults to `false` so existing test suites keep their explicit-assert behavior.
+- Auto-assert hooks into `MakesHttpRequests::createTestResponse()`. Responses you construct manually (outside `$this->get()`, `$this->post()`, etc.) are not touched.
+- Idempotency is keyed on the `(spec, method, path)` tuple. Calling `assertResponseMatchesOpenApiSchema($response)` after auto-assert with the matching signature is a no-op. Calling it with a different `method`/`path` — or a different `#[OpenApiSpec]` — runs validation again.
+- When auto-assert fails, the exception is thrown from inside `$this->get(...)`, so any chained assertion on the same line (`$this->get(...)->assertOk()`) will not run. This is usually what you want — the schema failure takes precedence over status-code checks.
+- `auto_assert` accepts boolean-compatible values (`true`/`false`/`"1"`/`"0"`/`"true"`/`"false"`) so `'auto_assert' => env('OPENAPI_AUTO_ASSERT')` works. Unrecognized values fail the test loudly with a clear message, not silently.
+- Streamed responses (`StreamedResponse`, binary downloads) cause `getContent()` to return `false`, which fails auto-assert with a clear message. If you use `auto_assert=true` on tests that exercise streams, scope the config change per-test or fall back to explicit manual asserts.
+
 ## Coverage Report
 
 After running tests, the PHPUnit extension prints a coverage report. The output format is controlled by the `console_output` parameter (or `OPENAPI_CONSOLE_OUTPUT` environment variable).

composer.json

@@ -11,7 +11,7 @@
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.94",
-        "illuminate/testing": "^11.0 || ^12.0",
+        "orchestra/testbench": "^9.0 || ^10.0 || ^11.0",
         "phpstan/phpstan": "^2.0",
         "symfony/http-foundation": "^6.4 || ^7.0 || ^8.0"
     },

src/Laravel/ValidatesOpenApiSchema.php

@@ -4,28 +4,79 @@
 
 namespace Studio\OpenApiContractTesting\Laravel;
 
+use const FILTER_NULL_ON_FAILURE;
+use const FILTER_VALIDATE_BOOLEAN;
+
 use Illuminate\Testing\TestResponse;
 use JsonException;
 use Studio\OpenApiContractTesting\HttpMethod;
 use Studio\OpenApiContractTesting\OpenApiCoverageTracker;
 use Studio\OpenApiContractTesting\OpenApiResponseValidator;
 use Studio\OpenApiContractTesting\OpenApiSpecResolver;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use WeakMap;
 
+use function filter_var;
+use function get_debug_type;
 use function is_numeric;
 use function is_string;
+use function sprintf;
 use function str_contains;
 use function strtolower;
+use function strtoupper;
+use function var_export;
 
 trait ValidatesOpenApiSchema
 {
     use OpenApiSpecResolver;
     private static ?OpenApiResponseValidator $cachedValidator = null;
     private static ?int $cachedMaxErrors = null;
 
+    /** @var null|WeakMap<TestResponse, array<string, true>> */
+    private static ?WeakMap $validatedResponses = null;
+
     public static function resetValidatorCache(): void
     {
         self::$cachedValidator = null;
         self::$cachedMaxErrors = null;
+        self::$validatedResponses = null;
+    }
+
+    /**
+     * Overrides Laravel's MakesHttpRequests::createTestResponse hook so every
+     * HTTP test call runs schema validation when auto_assert is enabled.
+     * When the library is used outside Laravel, this method is never called.
+     *
+     * Method and path are resolved from the Request passed in by Laravel
+     * rather than from app('request'), so auto-assert stays independent of
+     * container state and sees the exact values the framework dispatched.
+     *
+     * @param Response $response
+     * @param null|Request $request
+     */
+    protected function createTestResponse($response, $request = null): TestResponse
+    {
+        $testResponse = parent::createTestResponse($response, $request);
+
+        $method = $request !== null ? HttpMethod::tryFrom(strtoupper($request->getMethod())) : null;
+        $path = $request?->getPathInfo();
+
+        $this->maybeAutoAssertOpenApiSchema($testResponse, $method, $path);
+
+        return $testResponse;
+    }
+
+    protected function maybeAutoAssertOpenApiSchema(
+        TestResponse $response,
+        ?HttpMethod $method = null,
+        ?string $path = null,
+    ): void {
+        if (!$this->isAutoAssertEnabled()) {
+            return;
+        }
+
+        $this->assertResponseMatchesOpenApiSchema($response, $method, $path);
     }
 
     protected function openApiSpec(): string
@@ -49,6 +100,9 @@ protected function assertResponseMatchesOpenApiSchema(
         ?HttpMethod $method = null,
         ?string $path = null,
     ): void {
+        $resolvedMethod = $method !== null ? $method->value : app('request')->getMethod();
+        $resolvedPath = $path ?? app('request')->getPathInfo();
+
         $specName = $this->resolveOpenApiSpec();
         if ($specName === '') {
             $this->fail(
@@ -59,8 +113,16 @@ protected function assertResponseMatchesOpenApiSchema(
             );
         }
 
-        $resolvedMethod = $method !== null ? $method->value : app('request')->getMethod();
-        $resolvedPath = $path ?? app('request')->getPathInfo();
+        // Idempotency key includes the spec so that validating the same
+        // response against a different spec (or a different method/path on
+        // the same spec) still runs — auto-assert's no-op only applies to
+        // exact repeats.
+        $signature = $specName . ':' . $resolvedMethod . ' ' . $resolvedPath;
+
+        if (self::isAlreadyValidated($response, $signature)) {
+            return;
+        }
+        self::markValidated($response, $signature);
 
         $content = $response->getContent();
         if ($content === false) {
@@ -82,6 +144,8 @@ protected function assertResponseMatchesOpenApiSchema(
         // Record coverage for any matched endpoint, including those where body
         // validation was skipped (e.g. non-JSON content types). "Covered" means
         // the endpoint was exercised in a test, not that its body was validated.
+        // Note: under auto_assert, this records coverage for every Laravel HTTP
+        // call — including responses with no explicit contract-test intent.
         if ($result->matchedPath() !== null) {
             OpenApiCoverageTracker::record(
                 $specName,
@@ -97,6 +161,20 @@ protected function assertResponseMatchesOpenApiSchema(
         );
     }
 
+    private static function isAlreadyValidated(TestResponse $response, string $signature): bool
+    {
+        return self::$validatedResponses !== null &&
+            isset(self::$validatedResponses[$response][$signature]);
+    }
+
+    private static function markValidated(TestResponse $response, string $signature): void
+    {
+        self::$validatedResponses ??= new WeakMap();
+        $signatures = self::$validatedResponses[$response] ?? [];
+        $signatures[$signature] = true;
+        self::$validatedResponses[$response] = $signatures;
+    }
+
     private static function getOrCreateValidator(): OpenApiResponseValidator
     {
         $maxErrors = config('openapi-contract-testing.max_errors', 20);
@@ -110,6 +188,30 @@ private static function getOrCreateValidator(): OpenApiResponseValidator
         return self::$cachedValidator;
     }
 
+    private function isAutoAssertEnabled(): bool
+    {
+        $raw = config('openapi-contract-testing.auto_assert', false);
+
+        if ($raw === true) {
+            return true;
+        }
+        if ($raw === false || $raw === null) {
+            return false;
+        }
+
+        $parsed = filter_var($raw, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
+        if ($parsed === null) {
+            $this->fail(sprintf(
+                'openapi-contract-testing.auto_assert must be a boolean (or a boolean-compatible value '
+                . 'like "true"/"false"/"1"/"0"), got %s: %s.',
+                get_debug_type($raw),
+                var_export($raw, true),
+            ));
+        }
+
+        return $parsed;
+    }
+
     /** @return null|array<string, mixed> */
     private function extractJsonBody(TestResponse $response, string $content, string $contentType): ?array
     {

src/Laravel/config.php

@@ -8,4 +8,10 @@
     // Maximum number of validation errors to report per response.
     // 0 = unlimited (reports all errors).
     'max_errors' => 20,
+
+    // When true, every TestResponse produced by Laravel HTTP test helpers
+    // (get(), post(), etc.) is validated against the OpenAPI spec at creation
+    // time, without requiring an explicit assertResponseMatchesOpenApiSchema()
+    // call in each test. Defaults to false for backward compatibility.
+    'auto_assert' => false,
 ];

tests/Helpers/LaravelConfigMock.php

@@ -4,6 +4,11 @@
 
 namespace Studio\OpenApiContractTesting\Laravel;
 
+use Illuminate\Container\Container;
+
+use function array_key_exists;
+use function class_exists;
+
 /**
  * Namespace-level config() mock for unit testing.
  *
@@ -21,9 +26,34 @@
  * in ValidatesOpenApiSchema.php (i.e., no "use function config" import).
  * Adding such an import would bypass namespace resolution and break this mock.
  *
- * Test values are read from $GLOBALS['__openapi_testing_config'].
+ * Resolution order:
+ * 1. A unit-test override in $GLOBALS['__openapi_testing_config'] wins — unit
+ *    tests set this explicitly to control what the trait sees.
+ * 2. When a Laravel container is bootstrapped and has a "config" binding (i.e.
+ *    integration tests using orchestra/testbench), delegate to the framework's
+ *    config() helper via a variable function. The variable call avoids both
+ *    PHP namespace resolution (which would recurse into this mock) and any
+ *    future auto-import of the global \config() by cs-fixer's
+ *    global_namespace_import rule (which would add a "use function config;"
+ *    and re-break this mock for the same reason as a manual import).
+ * 3. Otherwise (pure unit tests with no booted app), return the provided
+ *    default. The container-bound check avoids swallowing real binding errors:
+ *    only an unbootstrapped container falls through here.
  */
 function config(string $key, mixed $default = null): mixed
 {
-    return $GLOBALS['__openapi_testing_config'][$key] ?? $default;
+    if (
+        isset($GLOBALS['__openapi_testing_config']) &&
+        array_key_exists($key, $GLOBALS['__openapi_testing_config'])
+    ) {
+        return $GLOBALS['__openapi_testing_config'][$key];
+    }
+
+    if (class_exists(Container::class) && Container::getInstance()->bound('config')) {
+        $globalConfig = 'config';
+
+        return $globalConfig($key, $default);
+    }
+
+    return $default;
 }