openapi_first 3.3.1 → 3.4.1

data/lib/openapi_first/test/configuration.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
+require_relative 'logger'
+
 module OpenapiFirst
   module Test
     # Helper class to setup tests
     class Configuration
       def initialize
         @minimum_coverage = 100
-        @coverage_formatter = Coverage::TerminalFormatter
-        @coverage_formatter_options = {}
+        @coverage_reporter = Coverage::HtmlReporter
+        @coverage_reporter_options = {}
         @skip_response_coverage = nil
         @skip_coverage = nil
         @response_raise_error = true
@@ -17,6 +19,7 @@ module OpenapiFirst
         @ignore_unknown_requests = false
         @ignore_request_error = nil
         @ignore_response_error = nil
+        @logger = Logger.new($stdout)
       end
 
       # Register OADs, but don't load them just yet
@@ -31,10 +34,34 @@ module OpenapiFirst
         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_accessor :coverage_reporter, :coverage_reporter_options, :response_raise_error,
+                    :ignore_unknown_requests, :ignore_unknown_response_status, :minimum_coverage, :logger
       attr_reader :report_coverage, :ignored_unknown_status
 
+      # @deprecated Use {#coverage_reporter} instead.
+      def coverage_formatter
+        warn_coverage_formatter_deprecation
+        coverage_reporter
+      end
+
+      # @deprecated Use {#coverage_reporter=} instead.
+      def coverage_formatter=(value)
+        warn_coverage_formatter_deprecation
+        self.coverage_reporter = value
+      end
+
+      # @deprecated Use {#coverage_reporter_options} instead.
+      def coverage_formatter_options
+        warn_coverage_formatter_deprecation
+        coverage_reporter_options
+      end
+
+      # @deprecated Use {#coverage_reporter_options=} instead.
+      def coverage_formatter_options=(value)
+        warn_coverage_formatter_deprecation
+        self.coverage_reporter_options = value
+      end
+
       # 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)
@@ -55,7 +82,9 @@ module OpenapiFirst
       # Ignore certain errors for certain requests
       # @param block A Proc that will be called with [OpenapiFirst::ValidatedRequest]
       def ignore_request_error(&block)
+        # :nocov:
         raise ArgumentError, 'You have to pass a block' unless block_given?
+        # :nocov:
 
         @ignore_request_error = block
       end
@@ -63,7 +92,9 @@ module OpenapiFirst
       # Ignore certain errors for certain responses
       # @param block A Proc that will be called with [OpenapiFirst::ValidatedResponse, Rack::Request]
       def ignore_response_error(&block)
+        # :nocov:
         raise ArgumentError, 'You have to pass a block' unless block_given?
+        # :nocov:
 
         @ignore_response_error = block
       end
@@ -99,6 +130,16 @@ module OpenapiFirst
 
         true
       end
+
+      private
+
+      def warn_coverage_formatter_deprecation
+        return if @coverage_formatter_warned
+
+        warn 'DEPRECATION WARNING: Test::Configuration#coverage_formatter(_options) is deprecated, ' \
+             'use #coverage_reporter(_options) instead.'
+        @coverage_formatter_warned = true
+      end
     end
   end
 end

data/lib/openapi_first/test/coverage/html_reporter/context.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      class HtmlReporter
+        # Provides the binding and helper methods for the ERB template.
+        class Context
+          NO_REQUESTS_WARNING =
+            'API Coverage did not detect any API requests for the registered ' \
+            'API descriptions. Make sure to observe your application using OpenapiFirst::Test.'
+
+          attr_reader :coverage, :plans, :verbose
+
+          def initialize(coverage_result, verbose)
+            @coverage = coverage_result.coverage
+            @plans = coverage_result.plans
+            @verbose = verbose
+          end
+
+          # Helper for ERB rendering only — exposes this context's binding so the
+          # template can resolve helper methods and instance state.
+          def get_binding # rubocop:disable Naming/AccessorMethodName
+            binding
+          end
+
+          def expand_plan?(plan)
+            verbose || plan.done?
+          end
+
+          def visible_routes(plan)
+            return plan.routes if expand_plan?(plan)
+
+            plan.routes.reject(&:finished?)
+          end
+
+          def any_request_made?(route)
+            route.requests.any?(&:requested?)
+          end
+
+          def route_status(route)
+            return :request_problem if route.requests.none?(&:finished?)
+            return :responses_problem if any_request_made?(route) && route.responses.any? { |r| !r.finished? }
+
+            :ok
+          end
+
+          def uncovered_responses_count(route)
+            route.responses.count { |r| !r.finished? }
+          end
+
+          def request_items(route, plan_verbose:)
+            return [] unless any_request_made?(route) && route.requests.any?(&:content_type)
+
+            plan_verbose ? route.requests : route.requests.reject(&:finished?)
+          end
+
+          def response_items(route, plan_verbose:)
+            return [] unless plan_verbose || any_request_made?(route)
+            return route.responses if plan_verbose || route.responses.any? { |r| !r.finished? }
+
+            []
+          end
+
+          def h(text)
+            ERB::Util.html_escape(text)
+          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 explain_unfinished_response(response, request_made: false)
+            unless response.responded?
+              return request_made ? 'No matching response tracked!' : 'No responses tracked!'
+            end
+
+            "All responses invalid! (#{response.last_error_message.inspect})" unless response.any_valid_response?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openapi_first/test/coverage/html_reporter.css

@@ -0,0 +1,179 @@
+*, *::before, *::after { box-sizing: border-box; }
+
+body {
+  font-family: ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, monospace;
+  background: #0f1117;
+  color: #e2e8f0;
+  margin: 0;
+  padding: 2rem;
+  line-height: 1.6;
+}
+
+h1 {
+  font-size: 1.1rem;
+  font-weight: 600;
+  margin-block: 0 1rem;
+  color: #f8fafc;
+
+  & .pct {
+    font-size: 0.95rem;
+    font-weight: 400;
+    color: #94a3b8;
+    margin-inline-start: 0.5rem;
+  }
+}
+
+details.plan {
+  border: 1px solid #1e293b;
+  padding: 1.25rem 1.5rem;
+  margin-block-end: 1.5rem;
+  background: #161b27;
+
+  &[open] { border-color: #334155; }
+}
+
+details.plan > summary {
+  font-size: 1rem;
+  font-weight: 600;
+  color: #cbd5e1;
+  cursor: pointer;
+  list-style: none;
+  display: flex;
+  align-items: baseline;
+  gap: 0.5rem;
+  user-select: none;
+
+  & .pct {
+    font-size: 0.8rem;
+    font-weight: 400;
+    color: #64748b;
+    text-transform: none;
+    letter-spacing: 0;
+  }
+
+  &::before {
+    content: '▶';
+    font-size: 0.6rem;
+    color: #475569;
+    transition: transform 0.15s ease;
+    align-self: center;
+  }
+
+  details[open] > &::before { transform: rotate(90deg); }
+}
+
+.plan-content {
+  margin-block-start: 1rem;
+}
+
+details.route {
+  border-inline-start: 2px solid #1e293b;
+  padding-inline-start: 1rem;
+  margin-block: 0.75rem;
+
+  &[open] { border-color: #334155; }
+}
+
+details.route > summary {
+  font-weight: 600;
+  color: #94a3b8;
+  font-size: 0.85rem;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  cursor: pointer;
+  list-style: none;
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding-block: 0.2rem;
+  user-select: none;
+
+  &::before {
+    content: '▶';
+    font-size: 0.6rem;
+    color: #475569;
+    transition: transform 0.15s ease;
+  }
+
+  details[open] > &::before { transform: rotate(90deg); }
+}
+
+.operation-label {
+  font-size: 0.8rem;
+  font-weight: 400;
+  color: #64748b;
+  text-transform: none;
+  letter-spacing: 0;
+}
+
+.request-status,
+.response-summary {
+  font-size: 0.8rem;
+  font-weight: 400;
+  text-transform: none;
+  letter-spacing: 0;
+}
+
+.route-content {
+  margin-block-start: 0.4rem;
+}
+
+ul.tasks {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+}
+
+ul.responses {
+  padding-inline-start: 1.5rem;
+}
+
+li {
+  font-size: 0.875rem;
+  padding: 0.2rem 0.4rem;
+  display: flex;
+  align-items: baseline;
+  gap: 0.5rem;
+}
+
+.covered { color: #4ade80; }
+
+.uncovered {
+  background: #1f1315;
+  font-weight: 500;
+}
+
+.status {
+  color: #e2e8f0;
+  font-weight: 600;
+  min-width: 3ch;
+}
+
+.content-type {
+  color: #64748b;
+  font-size: 0.8rem;
+}
+
+.problem {
+  color: #f87171;
+  font-size: 0.8rem;
+}
+
+.method {
+  color: #7dd3fc;
+  font-weight: 700;
+}
+
+.path {
+  color: #e2e8f0;
+}
+
+.warning {
+  color: #fbbf24;
+  background: #1c1a10;
+  border: 1px solid #3b3010;
+  padding: 0.75rem 1rem;
+}

data/lib/openapi_first/test/coverage/html_reporter.html.erb

@@ -0,0 +1,87 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>OpenAPI API Coverage Report</title>
+  <style><%= File.read(File.join(__dir__, 'html_reporter.css')) %></style>
+</head>
+<body>
+  <h1>API Coverage <span class="pct"><%= coverage.round(1) %>%</span></h1>
+  <% if plans.empty? -%>
+  <p class="warning"><%= NO_REQUESTS_WARNING %></p>
+  <% else -%>
+  <% plans.each do |plan| -%>
+  <details class="plan"<%= ' open' unless plan.done? %>>
+    <summary>
+      <%= h plan.title || plan.api_identifier %>
+      <span class="pct"><%= plan.api_identifier %> · <%= plan.coverage.round(1) %>%</span>
+    </summary>
+    <div class="plan-content">
+    <% plan_verbose = expand_plan?(plan) -%>
+    <% visible_routes(plan).each do |route| -%>
+    <details class="route"<%= ' open' unless route.finished? %>>
+      <summary>
+        <span class="method"><%= h route.request_method.upcase %></span>
+        <span class="path"><%= h route.path %></span>
+        <% status = route_status(route) -%>
+        <% if status == :request_problem -%>
+        <span class="request-status problem">❌ <span class="problem"><%= h explain_unfinished_request(route.requests.first) %></span></span>
+        <% elsif status == :responses_problem -%>
+        <span class="response-summary problem">⚠️ <%= uncovered_responses_count(route) %> response(s) not covered</span>
+        <% else -%>
+        <span class="request-status covered">✅</span>
+        <% end -%>
+        <% if (label = route.summary) -%>
+        <span class="operation-label"><%= h label %></span>
+        <% end -%>
+      </summary>
+      <div class="route-content">
+        <% requests = request_items(route, plan_verbose: plan_verbose) -%>
+        <% unless requests.empty? -%>
+        <ul class="tasks">
+          <% requests.each do |request| -%>
+          <% if request.finished? -%>
+          <li class="covered">
+            <span>✅</span>
+            <% if request.content_type -%><span class="content-type"><%= h request.content_type %></span><% end -%>
+          </li>
+          <% else -%>
+          <li class="uncovered">
+            <span>❌</span>
+            <% if request.content_type -%><span class="content-type"><%= h request.content_type %></span><% end -%>
+            <span class="problem"><%= h explain_unfinished_request(request) %></span>
+          </li>
+          <% end -%>
+          <% end -%>
+        </ul>
+        <% end -%>
+        <% responses = response_items(route, plan_verbose: plan_verbose) -%>
+        <% unless responses.empty? -%>
+        <ul class="tasks responses">
+          <% responses.each do |response| -%>
+          <% if response.finished? -%>
+          <li class="covered">
+            <span>✅</span>
+            <span class="status"><%= h response.status %></span>
+            <% if response.content_type -%><span class="content-type"><%= h response.content_type %></span><% end -%>
+          </li>
+          <% else -%>
+          <li class="uncovered">
+            <span>❌</span>
+            <span class="status"><%= h response.status %></span>
+            <% if response.content_type -%><span class="content-type"><%= h response.content_type %></span><% end -%>
+            <span class="problem"><%= h explain_unfinished_response(response, request_made: any_request_made?(route)) %></span>
+          </li>
+          <% end -%>
+          <% end -%>
+        </ul>
+        <% end -%>
+      </div>
+    </details>
+    <% end -%>
+    </div>
+  </details>
+  <% end -%>
+  <% end -%>
+</body>
+</html>

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative 'html_reporter/context'
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      # Writes a self-contained HTML coverage report to a file.
+      class HtmlReporter
+        def initialize(output: 'coverage/openapi_coverage.html', verbose: false, logger: Test.logger)
+          @output = output
+          @verbose = verbose
+          @logger = logger
+        end
+
+        def report(coverage_result)
+          html = TEMPLATE.result(Context.new(coverage_result, @verbose).get_binding)
+          FileUtils.mkdir_p(File.dirname(@output))
+          File.write(@output, html)
+          @logger.info "API coverage report written to #{@output}"
+        end
+
+        TEMPLATE_PATH = File.join(__dir__, 'html_reporter.html.erb')
+        TEMPLATE = ERB.new(File.read(TEMPLATE_PATH), trim_mode: '-')
+        TEMPLATE.filename = TEMPLATE_PATH
+      end
+    end
+  end
+end

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

@@ -13,7 +13,7 @@ module OpenapiFirst
         class UnknownRequestError < StandardError; end
 
         def self.for(oad, skip_response: nil, skip_route: nil)
-          plan = new(definition_key: oad.key, filepath: oad.filepath)
+          plan = new(definition_key: oad.key, filepath: oad.filepath, title: oad.title)
           routes = oad.routes
           routes = routes.reject { |route| skip_route[route.path, route.request_method] } if skip_route
           routes.each do |route|
@@ -26,14 +26,15 @@ module OpenapiFirst
           plan
         end
 
-        def initialize(definition_key:, filepath: nil)
+        def initialize(definition_key:, filepath: nil, title: nil)
           @routes = []
           @index = {}
           @api_identifier = filepath || definition_key
           @filepath = filepath
+          @title = title
         end
 
-        attr_reader :api_identifier, :filepath, :routes
+        attr_reader :api_identifier, :filepath, :routes, :title
         private attr_reader :index
 
         def track_request(validated_request)

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

@@ -7,6 +7,11 @@ module OpenapiFirst
         def finished?
           requests.all?(&:finished?) && responses.all?(&:finished?)
         end
+
+        def summary
+          operation = requests.first&.request&.operation
+          operation&.[]('summary') || operation&.[]('description')
+        end
       end
     end
   end

data/lib/openapi_first/test/coverage/{terminal_formatter.rb → terminal_reporter.rb}

@@ -3,38 +3,34 @@
 module OpenapiFirst
   module Test
     module Coverage
-      # This is the default formatter
-      class TerminalFormatter
-        def initialize(verbose: false, focused: true)
+      # Reports coverage to a logger using ANSI-coloured lines.
+      class TerminalReporter
+        def initialize(verbose: false, focused: true, logger: Test.logger)
           @verbose = verbose
           @focused = focused && !verbose
+          @logger = logger
         end
 
         def format(coverage_result)
+          logger.warn 'DEPRECATION WARNING: TerminalReporter#format is deprecated, use #report instead.'
+          report(coverage_result)
+        end
+
+        def report(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.'
+            logger.warn '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 attr_reader :out, :verbose, :focused, :logger
 
         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}%"]
+          logger.info "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?) }
@@ -54,9 +50,9 @@ module OpenapiFirst
         def format_requests(requests)
           requests.each do |request|
             if request.finished?
-              puts green "✓ #{request_label(request)}"
+              log_success "✓ #{request_label(request)}"
             else
-              puts red "❌ #{request_label(request)} – #{explain_unfinished_request(request)}"
+              log_error "❌ #{request_label(request)} – #{explain_unfinished_request(request)}"
             end
           end
         end
@@ -64,25 +60,13 @@ module OpenapiFirst
         def format_responses(responses)
           responses.each do |response|
             if response.finished?
-              puts green "  ✓  #{response_label(response)}" if verbose
+              log_success "  ✓  #{response_label(response)}" if verbose
             else
-              puts red "  ❌ #{response_label(response)} – #{explain_unfinished_response(response)}"
+              log_error "  ❌ #{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
@@ -109,6 +93,14 @@ module OpenapiFirst
 
           "All responses invalid! (#{response.last_error_message.inspect})" unless response.any_valid_response?
         end
+
+        def log_success(msg)
+          logger.info "\e[32m#{msg}\e[0m"
+        end
+
+        def log_error(msg)
+          logger.error "\e[31m#{msg}\e[0m"
+        end
       end
     end
   end

data/lib/openapi_first/test/coverage.rb

@@ -12,7 +12,11 @@ module OpenapiFirst
     # 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'
+      autoload :TerminalReporter, 'openapi_first/test/coverage/terminal_reporter'
+      autoload :HtmlReporter, 'openapi_first/test/coverage/html_reporter'
+
+      # @deprecated Use {TerminalReporter} instead.
+      TerminalFormatter = TerminalReporter
 
       Result = Data.define(:plans, :coverage)
 
@@ -45,7 +49,11 @@ module OpenapiFirst
           # 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(
+          # :nocov:
+          return unless tracker
+          # :nocov:
+
+          tracker.track_request(
             oad.key,
             CoveredRequest.new(
               key: request.request_definition.key,
@@ -61,7 +69,11 @@ module OpenapiFirst
           # 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(
+          # :nocov:
+          return unless tracker
+          # :nocov:
+
+          tracker.track_response(
             oad.key,
             CoveredResponse.new(
               key: response.response_definition.key,
@@ -76,10 +88,6 @@ module OpenapiFirst
 
         private
 
-        def current_run
-          tracker.plans_by_key
-        end
-
         # Returns all plans (Plan) that were registered for this run
         def plans
           tracker&.plans || []

data/lib/openapi_first/test/logger.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module OpenapiFirst
+  module Test
+    # Logger to output coverage reports and such
+    class Logger < ::Logger
+      def initialize(*)
+        super
+        self.formatter = proc { |_severity, _time, _progname, msg|
+          "#{msg}\n"
+        }
+      end
+    end
+  end
+end