openapi_first 2.10.1 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79f9fda1c73303674f66f87ff97d6749e085fb6a01ca1f9d604e53a9f9a1abd7
-  data.tar.gz: b15c401b9e9b83fc091e597b09765a3ec518005c79f4406af4abe4fa1a8b7735
+  metadata.gz: 7687c4d4ac32654b4a2fd8880eeaeb0ca98ab6fac19b8d9a336fe5d5bb94785a
+  data.tar.gz: 6fb04355d69916cfc3d1dce1e21d0f163082878cf1348421a9b1006b070621f3
 SHA512:
-  metadata.gz: 84bbbc5bf681ec5f62ef7b66d68be805add8a4b013ea87d9081718677bcf617c89ffab7d61d660d1b498f99532b05106591837353d62a3355febaa739a80e631
-  data.tar.gz: 9c5771ee2b8a55e85d2841ce5d0e0058eec81df545f5eaf168176c41cd6e66c83436fffc19b6de156f444e1f58c010e8e443b0736fe6d08940774311c1ed87a3
+  metadata.gz: '0988025dd93f55354b646c8aeb3fe7d0febfd54925d368fd3aa5959067c1a0a948b193158130b5fa7fb91cf51ffe774f9f8f281e76ac3feb318e67ea1b079020'
+  data.tar.gz: f70094cd6b531e42e06f931ed31155385bf9dd97588cad6bc977e961e7fdd497e057a971112fe10a0457d145b8f916cabdad3995c90bc29d78d31e59184211ac

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 2.11.0
+
+- OpenapiFirst::Test.observe now works with `Rack::URLMap` (returned by `Rack::Builder.app`) and probably all objects that respond to `.call`
+
 ## 2.10.1
 
 - Don't try to track coverage for skipped requests

data/README.md

@@ -4,31 +4,34 @@ openapi_first is a Ruby gem for request / response validation and contract-testi
 
 ## Usage
 
-Use an OAD to validate incoming requests in production:
+Use an OAD to validate incoming requests:
 ```ruby
 use OpenapiFirst::Middlewares::RequestValidation, 'openapi/openapi.yaml'
 ```
 
-Turn your request tests into contract tests against an OAD:
+Turn your request tests into [contract tests](#contract-testing) against an OAD:
 ```ruby
 # spec_helper.rb
 require 'openapi_first'
 OpenapiFirst::Test.setup do |config|
   config.register('openapi/openapi.yaml')
 end
-require 'application' # Load Application code
-OpenapiFirst::Test.observe(Application)
+
+require 'my_app'
+RSpec.configure do |config|
+  config.include OpenapiFirst::Test::Methods[MyApp], type: :request
+end
 ```
 
 ## Contents
 
 <!-- TOC -->
 
-- [Contract testing](#contract-testing)
 - [Rack Middlewares](#rack-middlewares)
   - [Request validation](#request-validation)
   - [Response validation](#response-validation)
-- [Test assertions](#test-assertions)
+- [Contract testing](#contract-testing)
+  - [Test assertions](#test-assertions)
 - [Manual use](#manual-use)
 - [Framework integration](#framework-integration)
 - [Configuration](#configuration)
@@ -41,78 +44,6 @@ OpenapiFirst::Test.observe(Application)
 
 <!-- /TOC -->
 
-## Contract Testing
-
-You can see your OpenAPI API description as a contract that your clients can rely on as how your API behaves. There are two aspects of contract testing: Validation and Coverage. By validating requests and responses, you can avoid that your API implementation processes requests or returns responses that don't match your API description. To make sure your _whole_ API description is implemented, openapi_first can check that all of your API description is covered when you test your API with [rack-test](https://github.com/rack/rack-test).
-
-Here is how to set it up:
-
-1. Register all OpenAPI documents to track coverage for.
-  This should go at the top of your test helper file before loading your application code.
-    ```ruby
-    require 'openapi_first'
-    OpenapiFirst::Test.setup do |config|
-      config.register('openapi/openapi.yaml')
-    end
-    ```
-2. Observe your application. You can do this in one of two ways:
-    - Add an `app` method to your tests, which wraps your application with silent request / response validation. (✷1)
-      ```ruby
-      RSpec.configure do |config|
-        config.include OpenapiFirst::Test::Methods[MyApp], type: :request
-      end
-      ```
-      Or add the `app` method yourself:
-
-      ```ruby
-      def app
-        OpenapiFirst::Test.app(MyApp)
-      end
-      ```
-    - Or inject a Module to wrap (prepend) the `call` method of your Rack app Class.
-
-      NOTE: This is still work in progress. It works with basic Sinatra apps, but does not work with Hanami or Rails out of the box, yet. PRs welcome 🤗
-
-      ```ruby
-      OpenapiFirst::Test.observe(MyApplication)
-      ```
-3. Run your tests. The Coverage feature will tell you about missing or invalid requests/responses.
-
-(✷1): It does not matter what method of openapi_first you use to validate requests/responses. Instead of using `OpenapiFirstTest.app` to wrap your application, you could also use the [middlewares](#rack-middlewares) or [test assertion method](#test-assertions), but you would have to do that for all requests/responses defined in your API description to make coverage work.
-
-### Configure test coverage
-
-OpenapiFirst::Test raises an error when a request is not defined. You can deactivate this with:
-
-```ruby
-OpenapiFirst::Test.setup do |test|
-  # …
-  test.ignore_unknown_requests = true
-end
-```
-
-Exclude certain _responses_ from coverage with `skip_coverage`:
-
-```ruby
-OpenapiFirst::Test.setup do |test|
-  # …
-  test.skip_response_coverage do |response_definition|
-    response_definition.status == '5XX'
-  end
-end
-```
-
-Skip coverage for a request and all responses alltogether of a route with `skip_coverage`:
-
-```ruby
-OpenapiFirst::Test.setup do |test|
-  # …
-  test.skip_coverage do |path, request_method|
-    path == '/bookings/{bookingId}' && requests_method == 'DELETE'
-  end
-end
-```
-
 ## Rack Middlewares
 
 ### Request validation
@@ -222,7 +153,79 @@ use OpenapiFirst::Middlewares::ResponseValidation, 'openapi.yaml', raise_error:
 
 If you are adopting OpenAPI you can use these options together with [hooks](#hooks) to get notified about requests/responses that do match your API description.
 
-## Test assertions
+## Contract Testing
+
+You can see your OpenAPI API description as a contract that your clients can rely on as how your API behaves. There are two aspects of contract testing: Validation and Coverage. By validating requests and responses, you can avoid that your API implementation processes requests or returns responses that don't match your API description. To make sure your _whole_ API description is implemented, openapi_first can check that all of your API description is covered when you test your API with [rack-test](https://github.com/rack/rack-test).
+
+Here is how to set it up:
+
+1. Register all OpenAPI documents to track coverage for.
+  This should go at the top of your test helper file before loading your application code.
+    ```ruby
+    require 'openapi_first'
+    OpenapiFirst::Test.setup do |config|
+      config.register('openapi/openapi.yaml')
+    end
+    ```
+2. Observe your application. You can do this in multiple ways:
+    - Add an `app` method to your tests, which wraps your application with silent request / response validation. (✷1)
+      ```ruby
+      module RequestSpecHelpers
+        def app
+          OpenapiFirst::Test.app(MyApp)
+        end
+      end
+
+      RSpec.configure do |config|
+        config.include RequestSpecHelpers, type: :request
+      end
+      ```
+
+      Or do this by creating a Module and including it to add an "app" method.
+
+      ```ruby
+      RSpec.configure do |config|
+        config.include OpenapiFirst::Test::Methods[MyApp], type: :request
+      end
+      ```
+4. Run your tests. The Coverage feature will tell you about missing or invalid requests/responses.
+
+(✷1): It does not matter what method of openapi_first you use to validate requests/responses. Instead of using `OpenapiFirstTest.app` to wrap your application, you could also use the [middlewares](#rack-middlewares) or [test assertion method](#test-assertions), but you would have to do that for all requests/responses defined in your API description to make coverage work.
+
+### Configure test coverage
+
+OpenapiFirst::Test raises an error when a request is not defined. You can deactivate this with:
+
+```ruby
+OpenapiFirst::Test.setup do |test|
+  # …
+  test.ignore_unknown_requests = true
+end
+```
+
+Exclude certain _responses_ from coverage with `skip_coverage`:
+
+```ruby
+OpenapiFirst::Test.setup do |test|
+  # …
+  test.skip_response_coverage do |response_definition|
+    response_definition.status == '5XX'
+  end
+end
+```
+
+Skip coverage for a request and all responses alltogether of a route with `skip_coverage`:
+
+```ruby
+OpenapiFirst::Test.setup do |test|
+  # …
+  test.skip_coverage do |path, request_method|
+    path == '/bookings/{bookingId}' && requests_method == 'DELETE'
+  end
+end
+```
+
+### Test assertions
 
 openapi_first ships with a simple but powerful Test method to run request and response validation in your tests without using the middlewares. This is designed to be used with rack-test or Ruby on Rails integration tests or request specs.
 

data/lib/openapi_first/error_responses/default.rb

@@ -6,6 +6,7 @@ module OpenapiFirst
     # See also https://www.rfc-editor.org/rfc/rfc9457.html
     class Default
       include OpenapiFirst::ErrorResponse
+
       OpenapiFirst.register_error_response(:default, self)
 
       TITLES = {

data/lib/openapi_first/error_responses/jsonapi.rb

@@ -5,6 +5,7 @@ module OpenapiFirst
     # A JSON:API conform error response. See https://jsonapi.org/.
     class Jsonapi
       include OpenapiFirst::ErrorResponse
+
       OpenapiFirst.register_error_response(:jsonapi, self)
 
       def body

data/lib/openapi_first/response_parser.rb

@@ -23,11 +23,14 @@ module OpenapiFirst
 
     def read_body(rack_response)
       buffered_body = +''
+
       if rack_response.body.respond_to?(:each)
         rack_response.body.each { |chunk| buffered_body.to_s << chunk }
         return buffered_body
       end
       rack_response.body
+    rescue TypeError
+      raise Error, "Cannot not read response body. Response is not string-like, but is a #{rack_response.body.class}."
     end
 
     def build_headers_parser(headers)

data/lib/openapi_first/test/configuration.rb

@@ -27,7 +27,7 @@ module OpenapiFirst
 
       # Observe a rack app
       def observe(app, api: :default)
-        @apps[api] = app
+        (@apps[api] ||= []) << app
       end
 
       attr_accessor :coverage_formatter_options, :coverage_formatter, :response_raise_error,

data/lib/openapi_first/test/observe.rb

@@ -10,14 +10,23 @@ module OpenapiFirst
     # Inject silent request/response validation to observe rack apps during testing
     module Observe
       def self.observe(app, api: :default)
+        definition = OpenapiFirst::Test[api]
+        mod = OpenapiFirst::Test::Callable[definition]
+
+        if app.respond_to?(:call)
+          return if app.singleton_class.include?(Observed)
+
+          app.singleton_class.prepend(mod)
+          app.singleton_class.include(Observed)
+          return
+        end
+
         unless app.instance_methods.include?(:call)
           raise ObserveError, "Don't know how to observe #{app}, because it has no call instance method."
         end
 
         return if app.include?(Observed)
 
-        definition = OpenapiFirst::Test[api]
-        mod = OpenapiFirst::Test::Callable[definition]
         app.prepend(mod)
         app.include(Observed)
       end

data/lib/openapi_first/test/observer_middleware.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    # Middleware that observes requests and responses. This is used to trigger hooks added by OpenapiFirst::Tests.
+    class ObserverMiddleware
+      def initialize(app, options = {})
+        @app = app
+        @definition = OpenapiFirst::Test[options.fetch(:api, :default)]
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+
+        @definition.validate_request(request, raise_error: false)
+        response = @app.call(env)
+        status, headers, body = response
+        @definition.validate_response(request, Rack::Response[status, headers, body], raise_error: false)
+        response
+      end
+    end
+  end
+end

data/lib/openapi_first/test.rb

@@ -40,7 +40,7 @@ module OpenapiFirst
       yield configuration
 
       configuration.registry.each { |name, oad| register(oad, as: name) }
-      configuration.apps.each { |name, app| observe(app, api: name) }
+      configuration.apps.each { |name, apps| apps.each { |app| observe(app, api: name) } }
       Coverage.start(skip_response: configuration.skip_response_coverage, skip_route: configuration.skip_coverage)
 
       if definitions.empty?

data/lib/openapi_first/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
-  VERSION = '2.10.1'
+  VERSION = '2.11.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi_first
 version: !ruby/object:Gem::Version
-  version: 2.10.1
+  version: 2.11.0
 platform: ruby
 authors:
 - Andreas Haller
@@ -134,6 +134,7 @@ files:
 - lib/openapi_first/test/methods.rb
 - lib/openapi_first/test/minitest_helpers.rb
 - lib/openapi_first/test/observe.rb
+- lib/openapi_first/test/observer_middleware.rb
 - lib/openapi_first/test/plain_helpers.rb
 - lib/openapi_first/test/registry.rb
 - lib/openapi_first/validated_request.rb