openapi_first 2.4.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 131c3511b96fc2a420b9c0a1b2e4deeb5b24d8602ad6210e5a60ed1a46fe6257
-  data.tar.gz: f6b7a44491e9aedf68498b2200a46e6048b9036360447a34c077c7476da8fc70
+  metadata.gz: be641d2241f6650f7eb0c9bc4a5d78552f2945ee7a030e6003fa0567cb547c85
+  data.tar.gz: 3a7d5911b1c8b30074068a299f8841b791b447240141ca3303814a72bb7424ec
 SHA512:
-  metadata.gz: 498b7341aa473504c5fa13dd95e92d7d1e2317d690ddbd88fac36974c05b10cccd8ae8b9dccc025036151aab484304e14f053003668b576c547ac1c7c0716d4b
-  data.tar.gz: 5cb776022d6e0fb684b3c30e7dd507a6591e5bc0b34bc384347a28e2b5030f20c976fa6f92b9b3e81c8d8ec6912d46e6b0ee053189267de320ccf418e7d88f4f
+  metadata.gz: 65b5e1196c0f9900a8444a7282da2f3ebda189605dc5da0b2bcba3ae96cc5e74acc4550ff57d2aebcea0e41b299c13ffa7641268317ca285997626316a785776
+  data.tar.gz: 43f9452d4b33c0b2a0d1211a629bbbc2c1081b5c23c96d878d73eca2561ade654af0c2040ce992527eba6853acee230551f3a2c0bade8b5a2d142a075cbd10fb

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## 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`:

data/README.md

@@ -149,9 +149,10 @@ 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)

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

@@ -84,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)
@@ -97,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

@@ -16,6 +16,9 @@ module OpenapiFirst
     class Setup
       def initialize
         @minimum_coverage = 0
+        @coverage_formatter = Coverage::TerminalFormatter
+        @coverage_formatter_options = {}
+        @skip_response_coverage = nil
         yield self
       end
 
@@ -23,14 +26,25 @@ module OpenapiFirst
         Test.register(*)
       end
 
-      attr_accessor :minimum_coverage
+      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?
-        Test.report_coverage if coverage.positive?
+        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}%" \
@@ -45,8 +59,9 @@ module OpenapiFirst
         raise ArgumentError, "Please provide a block to #{self.class}.setup to register you API descriptions"
       end
 
-      Coverage.start
+      Coverage.install
       setup = Setup.new(&)
+      Coverage.start(skip_response: setup.skip_response_coverage)
 
       if definitions.empty?
         raise NotRegisteredError,

data/lib/openapi_first/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenapiFirst
-  VERSION = '2.4.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.4.0
+  version: 2.5.0
 platform: ruby
 authors:
 - Andreas Haller
 bindir: bin
 cert_chain: []
-date: 2025-02-26 00:00:00.000000000 Z
+date: 2025-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hana
@@ -162,5 +162,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 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: []