Added Test.setup { it.observe } and low-level Test::Callable[]

Added `Test.setup { it.observe }` and low-level `Test::Callable[]` to inject request/response validation in rack app as an alternative to overwrite the `app` method in a test

Author: ahx

CHANGELOG.md

@@ -3,7 +3,9 @@
 ## Unreleased
 
 OpenapiFirst::Test is stricter and more configurable:
-- Added `OpenapiFirst::Test::Configuration#ignored_unknown_status` to configure response status(es) that do not have to be descriped in the API description.
+- Added `Test.setup { it.observe }` and low level `Test::Callable[]` to inject request/response validation in rack app as an alternative to overwrite the `app` method in a test
+- Added `Test.observe(App, api: :my_api)`
+- Added Test::Configuration#ignored_unknown_status` to configure response status(es) that do not have to be descriped in the API description.
 - Changed `OpenapiFirst::Test` to make tests fail if API description is not covered by tests. You can adapt this behavior via `OpenapiFirst::Test.setup` / `skip_response_coverage` or deactivate coverage with `report_coverage = false` or `report_coverage = :warn`
 - Added `OpenapiFirst::Test::Configuration#report_coverage=` to configure the behavior if not all requests/responses of the API under test have been tested.
 - Deprecated `OpenapiFirst::Test::Configuration#minimum_coverage=` use "#report_coverage=true/false/:info" instead to modify the behavior

lib/openapi_first/test.rb

@@ -8,10 +8,21 @@ module OpenapiFirst
   module Test
     autoload :Coverage, 'openapi_first/test/coverage'
     autoload :Methods, 'openapi_first/test/methods'
+    autoload :Callable, 'openapi_first/test/callable'
     extend Registry
 
     class CoverageError < Error; end
 
+    # @visible private
+    module Observed; end
+
+    # Inject request/response validation in a rack app class
+    def self.observe(app, api: :default)
+      mod = Callable[api:]
+      app.prepend(mod) unless app.include?(Observed)
+      app.include(Observed)
+    end
+
     def self.minitest?(base)
       base.include?(::Minitest::Assertions)
     rescue NameError
@@ -31,9 +42,9 @@ def self.setup
 
       install
       yield configuration
-      configuration.registry.each do |name, oad|
-        register(oad, as: name)
-      end
+
+      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)
 
       if definitions.empty?
@@ -61,9 +72,10 @@ def self.handle_exit
       )
       return unless configuration.report_coverage == true
 
-      return if Coverage.result.coverage >= configuration.minimum_coverage
+      coverage = Coverage.result.coverage
+      return if coverage >= configuration.minimum_coverage
 
-      puts 'API Coverage fails with exit 2, because not all described requests and responses have been tested.'
+      puts "API Coverage fails with exit 2, because not all described requests and responses have been tested (#{coverage.round(4)}% covered)." # rubocop:disable Layout/LineLength
 
       exit 2
     end

lib/openapi_first/test/callable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    # Return a Module with a call method that wrapps silent request/response validation to monitor a Rack app
+    # This is used by Openapi::Test.observe
+    module Callable
+      # Returns a Module with a `call(env)` method that wraps super inside silent request/response validation
+      # You can use this like `Application.prepend(OpenapiFirst::Test.app_module)` to monitor your app during testing.
+      def self.[](api: :default)
+        definition = OpenapiFirst::Test[api]
+        Module.new.tap do |mod|
+          mod.define_method(:call) do |env|
+            request = Rack::Request.new(env)
+            definition.validate_request(request, raise_error: false)
+            response = super(env)
+            status, headers, body = response
+            definition.validate_response(request, Rack::Response[status, headers, body], raise_error: false)
+            response
+          end
+        end
+      end
+    end
+  end
+end

lib/openapi_first/test/configuration.rb

@@ -13,15 +13,23 @@ def initialize
         @ignored_unknown_status = [404]
         @report_coverage = true
         @registry = {}
+        @apps = {}
       end
 
       # Register OADs, but don't load them just yet
+      # @param [OpenapiFirst::OAD] oad The OAD to register
+      # @param [Symbol] as The name to register the OAD under
       def register(oad, as: :default)
         @registry[as] = oad
       end
 
+      # Observe a rack app
+      def observe(app, api: :default)
+        @apps[api] = app
+      end
+
       attr_accessor :coverage_formatter_options, :coverage_formatter, :response_raise_error
-      attr_reader :registry, :minimum_coverage, :report_coverage, :ignored_unknown_status
+      attr_reader :registry, :apps, :minimum_coverage, :report_coverage, :ignored_unknown_status
 
       def minimum_coverage=(value)
         warn 'Setting OpenapiFirst::Test::Configuration#minimum_coverage= is deprecated ' \
@@ -30,6 +38,8 @@ def minimum_coverage=(value)
         @minimum_coverage = value
       end
 
+      # Configure report coverage
+      # @param [Boolean, :warn] value Whether to report coverage or just warn.
       def report_coverage=(value)
         allowed_values = [true, false, :warn]
         unless allowed_values.include?(value)

spec/test_spec.rb

@@ -3,6 +3,51 @@
 require 'minitest'
 
 RSpec.describe OpenapiFirst::Test do
+  let(:definition) { OpenapiFirst.load('./examples/openapi.yaml') }
+
+  let(:app) do
+    Class.new do
+      def call(_env)
+        Rack::Response.new.finish
+      end
+    end
+  end
+
+  describe 'Callable[]' do
+    it 'returns a Module that can call the api' do
+      described_class.register(definition, as: :some)
+      mod = described_class::Callable[api: :some]
+      app.prepend(mod)
+
+      expect(definition).to receive(:validate_request)
+      expect(definition).to receive(:validate_response)
+
+      app.new.call({})
+    end
+  end
+
+  describe '.observe' do
+    it 'injects request/response validation in the app' do
+      described_class.register(definition, as: :some)
+      described_class.observe(app, api: :some)
+
+      expect(definition).to receive(:validate_request)
+      expect(definition).to receive(:validate_response)
+
+      app.new.call({})
+    end
+
+    it 'injects request/response validation just once' do
+      described_class.register(definition, as: :some)
+      2.times { described_class.observe(app, api: :some) }
+
+      expect(definition).to receive(:validate_request).once
+      expect(definition).to receive(:validate_response).once
+
+      app.new.call({})
+    end
+  end
+
   describe '.minitest?' do
     it 'detects minitest' do
       test_case = Class.new(Minitest::Test)
@@ -81,6 +126,16 @@
       expect(described_class.definitions[:default].filepath).to eq(OpenapiFirst.load('./examples/openapi.yaml').filepath)
     end
 
+    it 'observes an app' do
+      described_class.setup do |test|
+        test.register(definition, as: :some)
+        test.observe(app, api: :some)
+      end
+
+      expect(definition).to receive(:validate_request)
+      app.new.call({})
+    end
+
     it 'sets up minimum_coverage' do
       described_class.setup do |test|
         test.register('./examples/openapi.yaml')