openapi_first 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 851414a9f2a8d64df210a610ed9577ad6608c85173a06221b96c3d390dcca1e5
-  data.tar.gz: 815e970727a8e683740b622768ccd031a138e4ef4ca38c8aebcd73bf2a7f4230
+  metadata.gz: 131c3511b96fc2a420b9c0a1b2e4deeb5b24d8602ad6210e5a60ed1a46fe6257
+  data.tar.gz: f6b7a44491e9aedf68498b2200a46e6048b9036360447a34c077c7476da8fc70
 SHA512:
-  metadata.gz: 8696eaabb5455c0e009233a3f8099198aa222cb1a442ef53314e5ed756373f41eff3747f69c0036cb43c708a746b21289866b9d7cfeace5649a68a686ad302ef
-  data.tar.gz: 9bb2db9c0443eb75299c755a79a0e9c6d696bc27a5683bc8fe4994e3e7e965e336afe855bbe41666346697668ae312697f5b0e307ec89a13c1c9ecf6c4087134
+  metadata.gz: 498b7341aa473504c5fa13dd95e92d7d1e2317d690ddbd88fac36974c05b10cccd8ae8b9dccc025036151aab484304e14f053003668b576c547ac1c7c0716d4b
+  data.tar.gz: 5cb776022d6e0fb684b3c30e7dd507a6591e5bc0b34bc384347a28e2b5030f20c976fa6f92b9b3e81c8d8ec6912d46e6b0ee053189267de320ccf418e7d88f4f

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 2.4.0
+
+- Support less verbose test setup without the need to call `OpenapiFirst::Test.report_coverage`, which will be called `at_exit`:
+  ```ruby
+  OpenapiFirst::Test.setup do |test|
+    test.register('openapi/openapi.yaml')
+    test.minimum_coverage = 100 # Setting this will lead to an `exit 2` if coverage is below minimum
+  end
+  ```
+- Add `OpenapiFirst::Test::Setup#minimum_coverage=` to control exit behaviour (exit 2 if coverage is below minimum)
+- Add `verbose` option to `OpenapiFirst::Test.report_coverage(verbose: true)`
+  to see all passing requests/responses
+
 ## 2.3.0
 
 ### New feature

data/README.md

@@ -129,9 +129,11 @@ This can be useful in a test or staging environment, especially if you are adopt
 use OpenapiFirst::Middlewares::ResponseValidation, spec: 'openapi.yaml' if ENV['RACK_ENV'] == 'test'
 
 # Pass `raise_error: false` to not raise an error:
-use OpenapiFirst::Middlewares::ResponseValidation, raise_error: true, spec: 'openapi.yaml'
+use OpenapiFirst::Middlewares::ResponseValidation, raise_error: false, spec: 'openapi.yaml'
 ```
 
+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.
+
 ## Contract Testing
 
 ### Coverage
@@ -149,21 +151,17 @@ Here is how to set it up for RSpec in your `spec/spec_helper.rb`:
   require 'openapi_first'
   OpenapiFirst::Test.setup do |test|
     test.register('openapi/openapi.yaml')
+    test.minimum_coverage = 100 # Setting this will lead to an `exit 2` if coverage is below minimum
   end
   ```
 2. Wrap your app with silent request / response validation. This validates all requets/responses you do during your test run. (✷1)
   ```ruby
   config.before type: :request do
     def app
-      OpenapiFirst::Test::(App)
+      OpenapiFirst::Test.app(App)
     end
   end
   ```
-3. Check coverage after your test suite has finished
-  ```ruby
-  # Prints a coverage report to the terminal
-  config.after(:suite) { OpenapiFirst::Test.report_coverage }
-  ```
 
 (✷1): Instead of using `OpenapiFirstTest.app` to wrap your application, you can use the 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.
 

data/lib/openapi_first/response.rb

@@ -26,8 +26,12 @@ module OpenapiFirst
     attr_reader :status, :content_type, :content_schema, :headers, :headers_schema, :key
 
     def validate(response)
-      parsed_values = @parser.parse(response)
-      error = @validator.call(parsed_values)
+      parsed_values = nil
+      error = catch FAILURE do
+        parsed_values = @parser.parse(response)
+        nil
+      end
+      error ||= @validator.call(parsed_values)
       ValidatedResponse.new(response, parsed_values:, error:, response_definition: self)
     end
 

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

@@ -5,6 +5,10 @@ module OpenapiFirst
     module Coverage
       # This is the default formatter
       class TerminalFormatter
+        def initialize(verbose: false)
+          @verbose = verbose
+        end
+
         # This takes a list of Coverage::Plan instances and outputs a String
         def format(coverage_result)
           @out = StringIO.new
@@ -12,7 +16,7 @@ module OpenapiFirst
           @out.string
         end
 
-        private attr_reader :out
+        private attr_reader :out, :verbose
 
         private
 
@@ -27,10 +31,10 @@ module OpenapiFirst
         def format_plan(plan)
           filepath = plan.filepath
           puts ['', "API validation coverage for #{filepath}: #{plan.coverage}%"]
-          return if plan.done?
+          return if plan.done? && !verbose
 
           plan.routes.each do |route|
-            next if route.finished?
+            next if route.finished? && !verbose
 
             format_requests(route.requests)
             next if route.requests.none?(&:requested?)
@@ -52,7 +56,7 @@ module OpenapiFirst
         def format_responses(responses)
           responses.each do |response|
             if response.finished?
-              puts green "  ✓  #{response_label(response)}"
+              puts green "  ✓  #{response_label(response)}" if verbose
             else
               puts red "  ❌ #{response_label(response)} – #{explain_unfinished_response(response)}"
             end

data/lib/openapi_first/test.rb

@@ -14,33 +14,58 @@ module OpenapiFirst
 
     # Helper class to setup tests
     class Setup
+      def initialize
+        @minimum_coverage = 0
+        yield self
+      end
+
       def register(*)
         Test.register(*)
       end
+
+      attr_accessor :minimum_coverage
+
+      # This called at_exit
+      def handle_exit
+        coverage = Coverage.result.coverage
+        # :nocov:
+        puts 'API Coverage did not detect any API requests for the registered API descriptions' if coverage.zero?
+        Test.report_coverage if coverage.positive?
+        return unless minimum_coverage > coverage
+
+        puts "API Coverage fails with exit 2, because API coverage of #{coverage}%" \
+             "is below minimum of #{minimum_coverage}%!"
+        exit 2
+        # :nocov:
+      end
     end
 
-    def self.setup
+    def self.setup(&)
       unless block_given?
         raise ArgumentError, "Please provide a block to #{self.class}.setup to register you API descriptions"
       end
 
       Coverage.start
-      setup = Setup.new
-      yield setup
-      return unless definitions.empty?
-
-      raise NotRegisteredError,
-            'No API descriptions have been registered. ' \
-            'Please register your API description via ' \
-            "OpenapiFirst::Test.setup { |test| test.register('myopenapi.yaml') }"
+      setup = Setup.new(&)
+
+      if definitions.empty?
+        raise NotRegisteredError,
+              'No API descriptions have been registered. ' \
+              'Please register your API description via ' \
+              "OpenapiFirst::Test.setup { |test| test.register('myopenapi.yaml') }"
+      end
+
+      @setup ||= at_exit do
+        setup.handle_exit
+      end
     end
 
     # Print the coverage report
     # @param formatter A formatter to define the report.
     # @output [IO] An output where to puts the report.
-    def self.report_coverage(formatter: Coverage::TerminalFormatter)
+    def self.report_coverage(formatter: Coverage::TerminalFormatter, **)
       coverage_result = Coverage.result
-      puts formatter.new.format(coverage_result)
+      puts formatter.new(**).format(coverage_result)
       puts "The overal API validation coverage of this run is: #{coverage_result.coverage}%"
     end
 

data/lib/openapi_first/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: openapi_first
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Andreas Haller
 bindir: bin
 cert_chain: []
-date: 2025-02-14 00:00:00.000000000 Z
+date: 2025-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hana
@@ -160,7 +160,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.5
 specification_version: 4
 summary: Implement HTTP APIs based on OpenApi 3.x
 test_files: []