openapi_first 0.7.0.alpha1 → 3.1.0.beta1

data/lib/openapi_first/test/configuration.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    # Helper class to setup tests
+    class Configuration
+      def initialize
+        @minimum_coverage = 100
+        @coverage_formatter = Coverage::TerminalFormatter
+        @coverage_formatter_options = {}
+        @skip_response_coverage = nil
+        @skip_coverage = nil
+        @response_raise_error = true
+        @ignored_unknown_status = Set.new([401, 404, 500])
+        @ignore_unknown_response_status = false
+        @report_coverage = true
+        @ignore_unknown_requests = false
+      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)
+        Test.register(oad, as:)
+      end
+
+      # Observe a rack app
+      def observe(app, api: :default)
+        Observe.observe(app, api:)
+      end
+
+      attr_accessor :coverage_formatter_options, :coverage_formatter, :response_raise_error,
+                    :ignore_unknown_requests, :ignore_unknown_response_status, :minimum_coverage
+      attr_reader :report_coverage, :ignored_unknown_status
+
+      # Set ignored unknown status codes.
+      # @param [Array<Integer>] status Status codes that are okay not to cover in an OAD
+      def ignored_unknown_status=(status)
+        @ignored_unknown_status = status.to_set
+      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)
+          raise ArgumentError, "'report_coverage' must be one of #{allowed_values}, but was #{value.inspect}"
+        end
+
+        @report_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
+
+      alias ignore_unknown_response_status? ignore_unknown_response_status
+
+      def ignore_response?(validated_response)
+        return false if validated_response.known?
+
+        return true if ignored_unknown_status.include?(validated_response.status)
+
+        ignore_unknown_response_status? && validated_response.error.type == :response_status_not_found
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      CoveredRequest = Data.define(:key, :error) do
+        def valid? = error.nil?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      CoveredResponse = Data.define(:key, :error) do
+        def valid? = error.nil?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'route_task'
+require_relative 'response_task'
+require_relative 'request_task'
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      # This stores the coverage data for one API description
+      # A plan can be #done? and has several #tasks which can be #finished?
+      class Plan
+        class UnknownRequestError < StandardError; end
+
+        def self.for(oad, skip_response: nil, skip_route: nil)
+          plan = new(definition_key: oad.key, filepath: oad.filepath)
+          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,
+                           requests: route.requests,
+                           responses:
+          end
+          plan
+        end
+
+        def initialize(definition_key:, filepath: nil)
+          @routes = []
+          @index = {}
+          @api_identifier = filepath || definition_key
+          @filepath = filepath
+        end
+
+        attr_reader :api_identifier, :filepath, :routes
+        private attr_reader :index
+
+        def track_request(validated_request)
+          index[validated_request.key]&.track(validated_request)
+        end
+
+        def track_response(validated_response)
+          index[validated_response.key]&.track(validated_response)
+        end
+
+        def done?
+          tasks.all?(&:finished?)
+        end
+
+        def coverage
+          done = tasks.count(&:finished?)
+          return 0 if done.zero?
+
+          all = tasks.count
+          return 100 if done == all
+
+          (done / (all.to_f / 100))
+        end
+
+        def tasks
+          index.values
+        end
+
+        def add_route(request_method:, path:, requests:, responses:)
+          request_tasks = requests.to_a.map do |request|
+            index[request.key] = RequestTask.new(request)
+          end
+          response_tasks = responses.to_a.map do |response|
+            index[response.key] = ResponseTask.new(response)
+          end
+          @routes << RouteTask.new(path:, request_method:, requests: request_tasks, responses: response_tasks)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      # @visibility private
+      class RequestTask
+        extend Forwardable
+
+        def_delegators :@request, :path, :request_method, :content_type
+
+        def initialize(request_definition)
+          @request = request_definition
+          @requested = false
+          @last_error_message = nil
+        end
+
+        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?
+          @requested == true
+        end
+
+        def any_valid_request?
+          @valid == true
+        end
+
+        def finished?
+          requested? && any_valid_request?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      # @visibility private
+      class ResponseTask
+        extend Forwardable
+
+        def_delegators :@response, :status, :content_type, :key
+
+        def initialize(response_definition)
+          @response = response_definition
+          @responded = false
+          @last_error_message = nil
+        end
+
+        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?
+          @responded == true
+        end
+
+        def any_valid_response?
+          @valid == true
+        end
+
+        def finished?
+          responded? && any_valid_response?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      RouteTask = Data.define(:path, :request_method, :requests, :responses) do
+        def finished?
+          requests.all?(&:finished?) && responses.all?(&:finished?)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      # This is the default formatter
+      class TerminalFormatter
+        def initialize(verbose: false, focused: true)
+          @verbose = verbose
+          @focused = focused && !verbose
+        end
+
+        def format(coverage_result)
+          coverage = coverage_result.coverage
+          @out = StringIO.new
+          if coverage.zero?
+            @out.puts 'API Coverage did not detect any API requests for the registered API descriptions. ' \
+                      'Make sure to observe your application using OpenapiFirst::Test.'
+          end
+          coverage_result.plans.each { |plan| format_plan(plan) } if coverage.positive?
+          @out.string
+        end
+
+        private attr_reader :out, :verbose, :focused
+
+        private
+
+        def puts(string)
+          @out.puts(string)
+        end
+
+        def print(string)
+          @out.print(string)
+        end
+
+        def format_plan(plan) # rubocop:disable Metrics/PerceivedComplexity
+          puts ['', "API validation coverage for #{plan.api_identifier}: #{plan.coverage}%"]
+          return if plan.done? && !verbose
+
+          requested_routes_count = plan.routes.count { |route| route.requests.any?(&:requested?) }
+          focused_route = requested_routes_count <= 1 && focused
+
+          plan.routes.each do |route|
+            next if route.finished? && !verbose
+
+            next if route.requests.none?(&:requested?) && focused_route
+
+            format_requests(route.requests)
+
+            format_responses(route.responses)
+          end
+        end
+
+        def format_requests(requests)
+          requests.each do |request|
+            if request.finished?
+              puts green "✓ #{request_label(request)}"
+            else
+              puts red "❌ #{request_label(request)} – #{explain_unfinished_request(request)}"
+            end
+          end
+        end
+
+        def format_responses(responses)
+          responses.each do |response|
+            if response.finished?
+              puts green "  ✓  #{response_label(response)}" if verbose
+            else
+              puts red "  ❌ #{response_label(response)} – #{explain_unfinished_response(response)}"
+            end
+          end
+        end
+
+        def green(text)
+          "\e[32m#{text}\e[0m"
+        end
+
+        def red(text)
+          "\e[31m#{text}\e[0m"
+        end
+
+        def orange(text)
+          "\e[33m#{text}\e[0m"
+        end
+
+        def request_label(request)
+          name = "#{request.request_method.upcase} #{request.path}" # TODO: add required query parameters?
+          name << " (#{request.content_type})" if request.content_type
+          name
+        end
+
+        def explain_unfinished_request(request)
+          return 'No requests tracked!' unless request.requested?
+
+          return if request.any_valid_request?
+
+          "All requests invalid! (#{request.last_error_message.inspect})"
+        end
+
+        def response_label(response)
+          name = +''
+          name += response.status.to_s
+          name += "(#{response.content_type})" if response.content_type
+          name
+        end
+
+        def explain_unfinished_response(response)
+          return 'No responses tracked!' unless response.responded?
+
+          "All responses invalid! (#{response.last_error_message.inspect})" unless response.any_valid_response?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      # Class that allows tracking requests and response for OAD definitions.
+      # For each definition it builds a plan and forwards tracking to the correct plan.
+      class Tracker
+        attr_reader :plans_by_key
+
+        def initialize(definitions, skip_response: nil, skip_route: nil)
+          @plans_by_key = definitions.values.to_h do |oad|
+            plan = Plan.for(oad, skip_response:, skip_route:)
+            [oad.key, plan]
+          end
+        end
+
+        def track_request(key, request)
+          @plans_by_key[key]&.track_request(request)
+        end
+
+        def track_response(key, response)
+          @plans_by_key[key]&.track_response(response)
+        end
+
+        def plans
+          @plans_by_key.values
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/test/coverage.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'coverage/plan'
+require_relative 'coverage/tracker'
+require_relative 'coverage/covered_request'
+require_relative 'coverage/covered_response'
+require 'drb'
+
+module OpenapiFirst
+  module Test
+    # The Coverage module is about tracking request and response validation
+    # to assess if all parts of the API description have been tested.
+    # Currently it does not care about unknown requests that are not part of any API description.
+    module Coverage
+      autoload :TerminalFormatter, 'openapi_first/test/coverage/terminal_formatter'
+
+      Result = Data.define(:plans, :coverage)
+
+      class << self
+        def start(skip_response: nil, skip_route: nil)
+          return if @drb_uri
+
+          tracker = Tracker.new(Test.definitions, skip_response:, skip_route:)
+
+          # We need a custom DRbServer (not using DRb.start_service) because otherwise
+          # we'd conflict with Rails's DRb server
+          @drb_uri = DRb::DRbServer.new(nil, tracker).uri
+        end
+
+        # Clear current coverage run
+        def reset
+          @tracker = nil
+
+          return unless @drb_uri
+
+          service = DRb.fetch_server(@drb_uri)
+          service&.stop_service
+          @drb_uri = nil
+        end
+
+        def track_request(request, oad)
+          return unless request.known?
+
+          # The call to `track_request` may happen remotely in the main process that started
+          # the coverage collection.
+          # To make this work we need to keep arguments trivial, which is the reason the request
+          # is wrapped in a CoveredRequest data object.
+          tracker&.track_request(
+            oad.key,
+            CoveredRequest.new(
+              key: request.request_definition.key,
+              error: request.error
+            )
+          )
+        end
+
+        def track_response(response, _request, oad)
+          return unless response.known?
+
+          # The call to `track_response` may happen remotely in the main process that started
+          # the coverage collection.
+          # To make this work we need to keep arguments trivial, which is the reason the response
+          # is wrapped in a CoveredResponse data object.
+          tracker&.track_response(
+            oad.key,
+            CoveredResponse.new(
+              key: response.response_definition.key,
+              error: response.error
+            )
+          )
+        end
+
+        def result
+          Result.new(plans:, coverage:)
+        end
+
+        private
+
+        def current_run
+          tracker.plans_by_key
+        end
+
+        # Returns all plans (Plan) that were registered for this run
+        def plans
+          tracker&.plans || []
+        end
+
+        def tracker
+          return unless @drb_uri
+
+          @tracker ||= DRbObject.new_with_uri(@drb_uri)
+        end
+
+        def coverage
+          return 0 if plans.empty?
+
+          plans.sum(&:coverage) / plans.length
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/test/methods.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'minitest_helpers'
+require_relative 'plain_helpers'
+
+module OpenapiFirst
+  module Test
+    # Methods to use in integration tests
+    module Methods
+      def self.included(base)
+        base.include(DefaultApiMethod)
+        base.include(AssertionMethod)
+      end
+
+      def self.[](application_under_test = nil, api: nil)
+        mod = Module.new do
+          def self.included(base)
+            base.include OpenapiFirst::Test::Methods::AssertionMethod
+          end
+        end
+
+        if api
+          mod.define_method(:openapi_first_default_api) { api }
+        else
+          mod.include(DefaultApiMethod)
+        end
+
+        if application_under_test
+          mod.define_method(:app) { OpenapiFirst::Test.app(application_under_test, api: openapi_first_default_api) }
+        end
+
+        mod
+      end
+
+      # Default methods
+      module DefaultApiMethod
+        # This is the default api that is used by assert_api_conform
+        # :default is the default name that is used if you don't pass an `api:` option to `OpenapiFirst::Test.register`
+        # This is overwritten if you pass an `api:` option to `include OpenapiFirst::Test::Methods[…]`
+        def openapi_first_default_api
+          klass = self.class
+          if klass.respond_to?(:metadata) && klass.metadata[:api]
+            klass.metadata[:api]
+          else
+            :default
+          end
+        end
+      end
+
+      # @visibility private
+      module AssertionMethod
+        def self.included(base)
+          if Test.minitest?(base)
+            base.include(OpenapiFirst::Test::MinitestHelpers)
+          else
+            base.include(OpenapiFirst::Test::PlainHelpers)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/test/minitest_helpers.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    # Assertion methods for Minitest
+    module MinitestHelpers
+      # :nocov:
+      def assert_api_conform(status: nil, api: openapi_first_default_api)
+        api = OpenapiFirst::Test[api]
+        request = respond_to?(:last_request) ? last_request : @request
+        response = respond_to?(:last_response) ? last_response : @response
+
+        if status
+          assert_equal status, response.status,
+                       "Expected status #{status}, but got #{response.status} " \
+                       "from #{request.request_method.upcase} #{request.path}."
+        end
+
+        validated_request = api.validate_request(request, raise_error: false)
+        validated_response = api.validate_response(request, response, raise_error: false)
+
+        assert validated_request.valid?, validated_request.error&.exception_message
+        assert validated_response.valid?, validated_response.error&.exception_message
+      end
+      # :nocov:
+    end
+  end
+end

data/lib/openapi_first/test/observe.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'callable'
+
+module OpenapiFirst
+  module Test
+    class ObserveError < Error; end
+
+    # @visible private
+    module Observed; end
+
+    # 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)
+
+        app.prepend(mod)
+        app.include(Observed)
+      end
+    end
+  end
+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