openapi_first 2.9.3 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef8ea95833884daf36e8a33742ce4a6eddfb9343b67de0b5e787ebc377c0691d
-  data.tar.gz: b63916918c1d1116d99c2e071c3e8e752b1cce66cd431dceb5076a3e70688c10
+  metadata.gz: 7687c4d4ac32654b4a2fd8880eeaeb0ca98ab6fac19b8d9a336fe5d5bb94785a
+  data.tar.gz: 6fb04355d69916cfc3d1dce1e21d0f163082878cf1348421a9b1006b070621f3
 SHA512:
-  metadata.gz: 3cbf77e0a4a51b213a90458c1181bd29474f378195210cf76466c24ef832195b32e4cbd8aec7ba97ece0bd7d9a97b6022e02b5288600d8879b82401c398d1ddc
-  data.tar.gz: 8789c3dadcff66b6cbb831dfae948da5adcbcd2788ff40765f39d4a1a0ba238cef1d7df609b4dd57e8ba71653103e21f9fb6a7e1f0a212e45c02d4f8c5e41e39
+  metadata.gz: '0988025dd93f55354b646c8aeb3fe7d0febfd54925d368fd3aa5959067c1a0a948b193158130b5fa7fb91cf51ffe774f9f8f281e76ac3feb318e67ea1b079020'
+  data.tar.gz: f70094cd6b531e42e06f931ed31155385bf9dd97588cad6bc977e961e7fdd497e057a971112fe10a0457d145b8f916cabdad3995c90bc29d78d31e59184211ac

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## 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
+- Add Test::Configuration#skip_coverage to skip test coverage for specific paths + request methods and all responses
+- Deprecate setting minimum_coverage value. Use skip_response_coverage, ignored_unknown_status to configure coverage instead.
+- Update openapi_parameters to make parsing array query parameters more consistent.
+  Now parsing empty array query parameter like `ids=&` or `ids&` both result in an empty array value (`[]`) instead of `nil` or `""`.
+- Fix Test::Coverage.result returning < 100 even if plan is fully covered
+
+## 2.10.0 (yanked)
+
 ## 2.9.3
 
 - Fix OpenapiFirst.load when MultiJson is configured to return symbol keys

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,53 +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.
-
-OpenapiFirst' request validation raises an error when a request is not defined. You can deactivate this during testing:
-
-```ruby
-OpenapiFirst::Test.setup do |test|
-  test.ignore_unknown_requests = true
-end
-```
-
 ## Rack Middlewares
 
 ### Request validation
@@ -197,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

@@ -9,6 +9,7 @@ module OpenapiFirst
         @coverage_formatter = Coverage::TerminalFormatter
         @coverage_formatter_options = {}
         @skip_response_coverage = nil
+        @skip_coverage = nil
         @response_raise_error = true
         @ignored_unknown_status = [404]
         @report_coverage = true
@@ -26,12 +27,12 @@ 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, :minimum_coverage,
+      attr_accessor :coverage_formatter_options, :coverage_formatter, :response_raise_error,
                     :ignore_unknown_requests
-      attr_reader :registry, :apps, :report_coverage, :ignored_unknown_status
+      attr_reader :registry, :apps, :report_coverage, :ignored_unknown_status, :minimum_coverage
 
       # Configure report coverage
       # @param [Boolean, :warn] value Whether to report coverage or just warn.
@@ -44,11 +45,24 @@ module OpenapiFirst
         @report_coverage = value
       end
 
+      # @deprecated Use skip_response_coverage, ignored_unknown_status or skip_coverage to configure coverage
+      def minimum_coverage=(value)
+        warn 'OpenapiFirst::Test::Configuration#minimum_coverage= is deprecated. ' \
+             'Use skip_response_coverage, ignored_unknown_status to configure coverage instead.'
+        @minimum_coverage = value
+      end
+
       def skip_response_coverage(&block)
         return @skip_response_coverage unless block_given?
 
         @skip_response_coverage = block
       end
+
+      def skip_coverage(&block)
+        return @skip_coverage unless block_given?
+
+        @skip_coverage = block
+      end
     end
   end
 end

data/lib/openapi_first/test/coverage/plan.rb

@@ -12,9 +12,11 @@ module OpenapiFirst
       class Plan
         class UnknownRequestError < StandardError; end
 
-        def self.for(oad, skip_response: nil)
+        def self.for(oad, skip_response: nil, skip_route: nil)
           plan = new(definition_key: oad.key, filepath: oad.filepath)
-          oad.routes.each do |route|
+          routes = oad.routes
+          routes = routes.reject { |route| skip_route[route.path, route.request_method] } if skip_route
+          routes.each do |route|
             responses = skip_response ? route.responses.reject(&skip_response) : route.responses
             plan.add_route request_method: route.request_method,
                            path: route.path,
@@ -35,7 +37,7 @@ module OpenapiFirst
         private attr_reader :index
 
         def track_request(validated_request)
-          index[validated_request.request_definition.key].track(validated_request) if validated_request.known?
+          index[validated_request.request_definition.key]&.track(validated_request) if validated_request.known?
         end
 
         def track_response(validated_response)
@@ -51,6 +53,8 @@ module OpenapiFirst
           return 0 if done.zero?
 
           all = tasks.count
+          return 100 if done == all
+
           (done / (all.to_f / 100))
         end
 

data/lib/openapi_first/test/coverage.rb

@@ -19,9 +19,9 @@ module OpenapiFirst
 
         def install = Test.install
 
-        def start(skip_response: nil)
+        def start(skip_response: nil, skip_route: nil)
           @current_run = Test.definitions.values.to_h do |oad|
-            plan = Plan.for(oad, skip_response:)
+            plan = Plan.for(oad, skip_response:, skip_route:)
             [oad.key, plan]
           end
         end

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,8 +40,8 @@ module OpenapiFirst
       yield configuration
 
       configuration.registry.each { |name, oad| register(oad, as: name) }
-      configuration.apps.each { |name, app| observe(app, api: name) }
-      Coverage.start(skip_response: configuration.skip_response_coverage)
+      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?
         raise NotRegisteredError,

data/lib/openapi_first/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi_first
 version: !ruby/object:Gem::Version
-  version: 2.9.3
+  version: 2.11.0
 platform: ruby
 authors:
 - Andreas Haller
@@ -49,7 +49,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.5.1
+        version: 0.6.1
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -59,7 +59,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.5.1
+        version: 0.6.1
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -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