openapi_first 2.3.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 851414a9f2a8d64df210a610ed9577ad6608c85173a06221b96c3d390dcca1e5
-  data.tar.gz: 815e970727a8e683740b622768ccd031a138e4ef4ca38c8aebcd73bf2a7f4230
+  metadata.gz: be641d2241f6650f7eb0c9bc4a5d78552f2945ee7a030e6003fa0567cb547c85
+  data.tar.gz: 3a7d5911b1c8b30074068a299f8841b791b447240141ca3303814a72bb7424ec
 SHA512:
-  metadata.gz: 8696eaabb5455c0e009233a3f8099198aa222cb1a442ef53314e5ed756373f41eff3747f69c0036cb43c708a746b21289866b9d7cfeace5649a68a686ad302ef
-  data.tar.gz: 9bb2db9c0443eb75299c755a79a0e9c6d696bc27a5683bc8fe4994e3e7e965e336afe855bbe41666346697668ae312697f5b0e307ec89a13c1c9ecf6c4087134
+  metadata.gz: 65b5e1196c0f9900a8444a7282da2f3ebda189605dc5da0b2bcba3ae96cc5e74acc4550ff57d2aebcea0e41b299c13ffa7641268317ca285997626316a785776
+  data.tar.gz: 43f9452d4b33c0b2a0d1211a629bbbc2c1081b5c23c96d878d73eca2561ade654af0c2040ce992527eba6853acee230551f3a2c0bade8b5a2d142a075cbd10fb

data/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Unreleased
 
+## 2.5.0
+
+### New feature
+- Add option to skip certain responses in coverage calculation
+  ```ruby
+  require 'openapi_first'
+  OpenapiFirst::Test.setup do |s|
+    test.register('openapi/openapi.yaml')
+    test.skip_response_coverage { it.status == '401' }
+  end
+  ```
+
+### Minor changes
+- OpenapiFirst::Test.report_coverage now includes fractional digits when returning a coverage value to avoid reporting "0% / no requests made" even though some requests have been made.
+- Show details about invalid requests / responses in coverage report
+
+## 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
@@ -147,23 +149,20 @@ Here is how to set it up for RSpec in your `spec/spec_helper.rb`:
 1. Register all OpenAPI documents to track coverage for and start tracking. This should go at the top of you test helper file before loading application code.
   ```ruby
   require 'openapi_first'
-  OpenapiFirst::Test.setup do |test|
+  OpenapiFirst::Test.setup do |s|
     test.register('openapi/openapi.yaml')
+    test.minimum_coverage = 100 # Setting this will lead to an `exit 2` if coverage is below minimum
+    test.skip_response_coverage { it.status == '500' }
   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/plan.rb

@@ -12,20 +12,25 @@ module OpenapiFirst
       class Plan
         class UnknownRequestError < StandardError; end
 
-        def initialize(oad)
-          @oad = oad
-          @routes = []
-          @index = {}
-          @filepath = oad.filepath
+        def self.for(oad, skip_response: nil)
+          plan = new(filepath: oad.filepath)
           oad.routes.each do |route|
-            add_route request_method: route.request_method,
-                      path: route.path,
-                      requests: route.requests,
-                      responses: route.responses
+            responses = skip_response ? route.responses.reject(&skip_response) : route.responses
+            plan.add_route request_method: route.request_method,
+                           path: route.path,
+                           requests: route.requests,
+                           responses:
           end
+          plan
         end
 
-        attr_reader :filepath, :oad, :routes
+        def initialize(filepath:)
+          @routes = []
+          @index = {}
+          @filepath = filepath
+        end
+
+        attr_reader :filepath, :routes
         private attr_reader :index
 
         def track_request(validated_request)
@@ -45,15 +50,13 @@ module OpenapiFirst
           return 0 if done.zero?
 
           all = tasks.count
-          (done / (all.to_f / 100)).to_i
+          (done / (all.to_f / 100))
         end
 
         def tasks
           index.values
         end
 
-        private
-
         def add_route(request_method:, path:, requests:, responses:)
           request_tasks = requests.to_a.map do |request|
             index[request.key] = RequestTask.new(request)

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

@@ -14,13 +14,15 @@ module OpenapiFirst
         def initialize(request_definition)
           @request = request_definition
           @requested = false
+          @last_error_message = nil
         end
 
-        attr_reader :request
+        attr_reader :request, :last_error_message
 
         def track(validated_request)
           @requested = true
           @valid ||= true if validated_request.valid?
+          @last_error_message = validated_request.error.exception_message unless validated_request.valid?
         end
 
         def requested?

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

@@ -14,13 +14,15 @@ module OpenapiFirst
         def initialize(response_definition)
           @response = response_definition
           @responded = false
+          @last_error_message = nil
         end
 
-        attr_reader :response
+        attr_reader :response, :last_error_message
 
         def track(validated_response)
           @responded = true
           @valid ||= true if validated_response.valid?
+          @last_error_message = validated_response.error.exception_message unless validated_response.valid?
         end
 
         def responded?

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
@@ -80,7 +84,7 @@ module OpenapiFirst
         def explain_unfinished_request(request)
           return 'No requests tracked!' unless request.requested?
 
-          'All requests invalid!' unless request.any_valid_request?
+          "All requests invalid! (#{request.last_error_message.inspect})" unless request.any_valid_request?
         end
 
         def response_label(response)
@@ -93,7 +97,7 @@ module OpenapiFirst
         def explain_unfinished_response(response)
           return 'No responses tracked!' unless response.responded?
 
-          'All responses invalid!' unless response.any_valid_response?
+          "All responses invalid! (#{response.last_error_message.inspect})" unless response.any_valid_response?
         end
       end
     end

data/lib/openapi_first/test/coverage.rb

@@ -13,7 +13,11 @@ module OpenapiFirst
       Result = Data.define(:plans, :coverage)
 
       class << self
-        def start
+        attr_reader :current_run
+
+        def install
+          return if @installed
+
           @after_request_validation = lambda do |validated_request, oad|
             track_request(validated_request, oad)
           end
@@ -26,12 +30,21 @@ module OpenapiFirst
             config.after_request_validation(&@after_request_validation)
             config.after_response_validation(&@after_response_validation)
           end
+          @installed = true
+        end
+
+        def start(skip_response: nil)
+          @current_run = Test.definitions.values.to_h do |oad|
+            plan = Plan.for(oad, skip_response:)
+            [oad.filepath, plan]
+          end
         end
 
-        def stop
+        def uninstall
           configuration = OpenapiFirst.configuration
           configuration.hooks[:after_request_validation].delete(@after_request_validation)
           configuration.hooks[:after_response_validation].delete(@after_response_validation)
+          @installed = nil
         end
 
         # Clear current coverage run
@@ -51,24 +64,18 @@ module OpenapiFirst
           Result.new(plans:, coverage:)
         end
 
-        private
-
         # Returns all plans (Plan) that were registered for this run
         def plans
-          current_run.values
+          current_run&.values
         end
 
+        private
+
         def coverage
-          return 0 if plans.empty?
+          return 0 unless plans
 
           plans.sum(&:coverage) / plans.length
         end
-
-        def current_run
-          @current_run ||= Test.definitions.values.to_h do |oad|
-            [oad.filepath, Plan.new(oad)]
-          end
-        end
       end
     end
   end

data/lib/openapi_first/test.rb

@@ -14,33 +14,73 @@ module OpenapiFirst
 
     # Helper class to setup tests
     class Setup
+      def initialize
+        @minimum_coverage = 0
+        @coverage_formatter = Coverage::TerminalFormatter
+        @coverage_formatter_options = {}
+        @skip_response_coverage = nil
+        yield self
+      end
+
       def register(*)
         Test.register(*)
       end
+
+      attr_accessor :minimum_coverage, :coverage_formatter_options, :coverage_formatter
+
+      def skip_response_coverage(&block)
+        return @skip_response_coverage unless block_given?
+
+        @skip_response_coverage = block
+      end
+
+      # 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?
+        if coverage.positive?
+          Test.report_coverage(
+            formatter: coverage_formatter,
+            **coverage_formatter_options
+          )
+        end
+        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?
+      Coverage.install
+      setup = Setup.new(&)
+      Coverage.start(skip_response: setup.skip_response_coverage)
 
-      raise NotRegisteredError,
-            'No API descriptions have been registered. ' \
-            'Please register your API description via ' \
-            "OpenapiFirst::Test.setup { |test| test.register('myopenapi.yaml') }"
+      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.5.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.5.0
 platform: ruby
 authors:
 - Andreas Haller
 bindir: bin
 cert_chain: []
-date: 2025-02-14 00:00:00.000000000 Z
+date: 2025-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hana
@@ -160,7 +160,8 @@ 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
+summary: OpenAPI based request validation, response validation, contract-testing and
+  coverage
 test_files: []