openapi_first 3.4.3 → 4.0.0

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

@@ -1,41 +1,162 @@
-*, *::before, *::after { box-sizing: border-box; }
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+:root {
+  --font-size-base: 1rem;
+  --font-size-xs: calc(var(--font-size-base) * 0.75);
+  --font-size-sm: calc(var(--font-size-base) * 0.875);
+  --font-size-h1: calc(var(--font-size-base) * 1.6);
+
+  --bg-primary: #0f1117;
+  --bg-secondary: #161b27;
+
+  --border-default: #1e293b;
+  --border-active: #334155;
+  --border-warning: #3b3010;
+
+  --tree-indent: 1.25rem;
+  --tree-row-center: 0.9rem;
+
+  --text-heading: #f8fafc;
+  --text-primary: #e2e8f0;
+  --text-muted: #94a3b8;
+
+  --color-success: #4ade80;
+  --color-error: #f87171;
+  --color-info: #7dd3fc;
+  --color-warning: #fbbf24;
+  --color-skipped: #fb923c;
+}
 
 body {
-  font-family: ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, monospace;
-  background: #0f1117;
-  color: #e2e8f0;
+  font-family:
+    ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, monospace;
+  background: var(--bg-primary);
+  color: var(--text-primary);
   margin: 0;
-  padding: 2rem;
+  padding: 1rem 2rem;
   line-height: 1.6;
 }
 
+.page-header {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 1rem;
+  margin-block-end: 0.875rem;
+}
+
+.generated-at {
+  font-size: var(--font-size-xs);
+  color: var(--text-muted);
+  white-space: nowrap;
+}
+
+.page-title {
+  display: flex;
+  align-items: center;
+  align-self: stretch;
+  margin: 0;
+}
+
 h1 {
-  font-size: 1.1rem;
-  font-weight: 600;
-  margin-block: 0 1rem;
-  color: #f8fafc;
+  font-size: var(--font-size-h1);
+  color: var(--text-heading);
 
   & .pct {
-    font-size: 0.95rem;
-    font-weight: 400;
-    color: #94a3b8;
+    font-size: var(--font-size-sm);
+    color: var(--text-muted);
     margin-inline-start: 0.5rem;
   }
 }
 
+h2 {
+  margin: 0;
+  font-size: var(--font-size-sm);
+  color: var(--text-heading);
+}
+
+.api-identifier {
+  font-size: var(--font-size-xs);
+  color: var(--text-muted);
+  font-weight: normal;
+}
+
+.filters {
+  display: flex;
+  justify-content: flex-end;
+  gap: 1.25rem;
+  margin-block-end: 0.5rem;
+  font-size: var(--font-size-sm);
+}
+
+.filters .filter {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  cursor: pointer;
+  color: var(--text-muted);
+  user-select: none;
+
+  & input {
+    cursor: pointer;
+  }
+}
+
+/* CSS-only route filtering driven by the toolbar checkboxes. */
+body:has(#filter-covered:not(:checked)) details.route.is-covered {
+  display: none;
+}
+body:has(#filter-uncovered:not(:checked)) details.route.is-uncovered {
+  display: none;
+}
+body:has(#filter-skipped-requests:not(:checked)) details.route.is-skipped {
+  display: none;
+}
+
+/* Hide a plan once none of its routes remain visible. */
+body:has(#filter-covered:not(:checked))
+  details.plan:not(:has(details.route.is-uncovered)):not(
+    :has(details.route.is-skipped)
+  ),
+body:has(#filter-uncovered:not(:checked))
+  details.plan:not(:has(details.route.is-covered)):not(
+    :has(details.route.is-skipped)
+  ),
+body:has(#filter-skipped-requests:not(:checked))
+  details.plan:not(:has(details.route.is-covered)):not(
+    :has(details.route.is-uncovered)
+  ),
+body:has(#filter-covered:not(:checked)):has(#filter-uncovered:not(:checked))
+  details.plan:not(:has(details.route.is-skipped)),
+body:has(#filter-covered:not(:checked)):has(
+    #filter-skipped-requests:not(:checked)
+  )
+  details.plan:not(:has(details.route.is-uncovered)),
+body:has(#filter-uncovered:not(:checked)):has(
+    #filter-skipped-requests:not(:checked)
+  )
+  details.plan:not(:has(details.route.is-covered)),
+body:has(#filter-covered:not(:checked)):has(
+    #filter-uncovered:not(:checked)
+  ):has(#filter-skipped-requests:not(:checked))
+  details.plan {
+  display: none;
+}
+
 details.plan {
-  border: 1px solid #1e293b;
+  border: 1px solid var(--border-default);
   padding: 1.25rem 1.5rem;
   margin-block-end: 1.5rem;
-  background: #161b27;
-
-  &[open] { border-color: #334155; }
+  background: var(--bg-secondary);
 }
 
 details.plan > summary {
-  font-size: 1rem;
-  font-weight: 600;
-  color: #cbd5e1;
+  font-size: var(--font-size-base);
+  color: var(--text-heading);
   cursor: pointer;
   list-style: none;
   display: flex;
@@ -44,41 +165,50 @@ details.plan > summary {
   user-select: none;
 
   & .pct {
-    font-size: 0.8rem;
-    font-weight: 400;
-    color: #64748b;
+    font-size: var(--font-size-xs);
+    color: var(--text-muted);
     text-transform: none;
     letter-spacing: 0;
   }
 
   &::before {
-    content: '▶';
-    font-size: 0.6rem;
-    color: #475569;
+    content: "▶";
+    font-size: var(--font-size-xs);
+    color: var(--text-muted);
     transition: transform 0.15s ease;
     align-self: center;
   }
 
-  details[open] > &::before { transform: rotate(90deg); }
+  details[open] > &::before {
+    transform: rotate(90deg);
+  }
 }
 
 .plan-content {
-  margin-block-start: 1rem;
+  margin-block-start: 0.75rem;
+  margin-inline-start: 0.25rem;
+  padding-inline-start: var(--tree-indent);
+  border-inline-start: 2px solid var(--border-default);
 }
 
 details.route {
-  border-inline-start: 2px solid #1e293b;
-  padding-inline-start: 1rem;
-  margin-block: 0.75rem;
+  margin-block: 0;
+  position: relative;
 
-  &[open] { border-color: #334155; }
+  /* horizontal connector reaching left to the plan spine */
+  &::before {
+    content: "";
+    position: absolute;
+    left: calc(-1 * var(--tree-indent));
+    top: var(--tree-row-center);
+    width: calc(var(--tree-indent) - 0.25rem);
+    border-top: 2px solid var(--border-default);
+  }
 }
 
 details.route > summary {
-  font-weight: 600;
-  color: #94a3b8;
-  font-size: 0.85rem;
-  text-transform: uppercase;
+  color: var(--text-muted);
+  font-size: var(--font-size-sm);
   letter-spacing: 0.04em;
   cursor: pointer;
   list-style: none;
@@ -89,27 +219,27 @@ details.route > summary {
   user-select: none;
 
   &::before {
-    content: '▶';
-    font-size: 0.6rem;
-    color: #475569;
+    content: "▶";
+    font-size: var(--font-size-xs);
+    color: var(--text-muted);
     transition: transform 0.15s ease;
   }
 
-  details[open] > &::before { transform: rotate(90deg); }
+  details[open] > &::before {
+    transform: rotate(90deg);
+  }
 }
 
 .operation-label {
-  font-size: 0.8rem;
-  font-weight: 400;
-  color: #64748b;
+  font-size: var(--font-size-xs);
+  color: var(--text-muted);
   text-transform: none;
   letter-spacing: 0;
 }
 
 .request-status,
 .response-summary {
-  font-size: 0.8rem;
-  font-weight: 400;
+  font-size: var(--font-size-xs);
   text-transform: none;
   letter-spacing: 0;
 }
@@ -121,59 +251,76 @@ details.route > summary {
 ul.tasks {
   list-style: none;
   margin: 0;
-  padding: 0;
+  padding-inline-start: var(--tree-indent);
+  padding-block: 0;
   display: flex;
   flex-direction: column;
-  gap: 0.2rem;
-}
-
-ul.responses {
-  padding-inline-start: 1.5rem;
+  border-inline-start: 2px solid var(--border-default);
 }
 
 li {
-  font-size: 0.875rem;
+  font-size: var(--font-size-sm);
   padding: 0.2rem 0.4rem;
   display: flex;
   align-items: baseline;
   gap: 0.5rem;
+  position: relative;
+
+  /* horizontal connector reaching left to the task spine */
+  &::before {
+    content: "";
+    position: absolute;
+    left: calc(-1 * var(--tree-indent));
+    top: var(--tree-row-center);
+    width: calc(var(--tree-indent) - 0.25rem);
+    border-top: 2px solid var(--border-default);
+  }
+}
+
+.covered {
+  color: var(--color-success);
 }
 
-.covered { color: #4ade80; }
+.skipped {
+  color: var(--color-skipped);
+}
+
+.skipped-note,
+.skipped-summary {
+  color: var(--color-skipped);
+  font-size: var(--font-size-xs);
+}
 
-.uncovered {
-  background: #1f1315;
-  font-weight: 500;
+.skipped-summary {
+  margin-inline-start: 0.75rem;
+  white-space: nowrap;
 }
 
 .status {
-  color: #e2e8f0;
-  font-weight: 600;
+  color: var(--text-primary);
   min-width: 3ch;
 }
 
 .content-type {
-  color: #64748b;
-  font-size: 0.8rem;
+  color: var(--text-muted);
+  font-size: var(--font-size-xs);
 }
 
 .problem {
-  color: #f87171;
-  font-size: 0.8rem;
+  color: var(--color-error);
+  font-size: var(--font-size-xs);
 }
 
 .method {
-  color: #7dd3fc;
-  font-weight: 700;
+  color: var(--color-info);
 }
 
 .path {
-  color: #e2e8f0;
+  color: var(--text-primary);
 }
 
 .warning {
-  color: #fbbf24;
-  background: #1c1a10;
-  border: 1px solid #3b3010;
+  color: var(--color-warning);
+  border: 1px solid var(--border-warning);
   padding: 0.75rem 1rem;
 }

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

@@ -6,41 +6,64 @@
   <style><%= File.read(File.join(__dir__, 'html_reporter.css')) %></style>
 </head>
 <body>
-  <h1>API Coverage <span class="pct"><%= coverage.round(1) %>%</span></h1>
+  <header class="page-header">
+    <h1 class="page-title">API Coverage: <%= coverage.round(1) %>%</h1>
+    <div>
+        <span class="generated-at">Generated at: <%= h generated_at %></span>
+        <% if any_skipped? -%>
+        <span class="skipped-summary"><%= skipped_requests_count %> request(s) and <%= skipped_responses_count %> response(s) skipped</span>
+        <% end -%>
+        <div class="filters">
+            <label class="filter"><input type="checkbox" id="filter-covered" checked> Covered operations</label>
+            <label class="filter"><input type="checkbox" id="filter-uncovered" checked> Uncovered operations</label>
+            <label class="filter"><input type="checkbox" id="filter-skipped-requests" checked> Skipped requests</label>
+        </div>
+    </div>
+  </header>
   <% 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>
+      <h2><%= h plan.title || plan.api_identifier %> <span class="api-identifier"><%= h plan.api_identifier %></span></h2>
+      <span class="pct"><%= 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? %>>
+    <% requests = request_items(route) -%>
+    <% responses = response_items(route) -%>
+    <details class="route <%= route_class(route) %>"<%= ' open' if any_request_made?(route) && !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>
+        <% if status == :skipped -%>
+        <span class="request-status skipped">Skipped</span>
+        <% elsif status == :request_problem -%>
+        <span class="request-status problem">❌ <span class="problem"><%= h explain_unfinished_request(route.tracked_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 route.skipped_responses.any? && status != :skipped -%>
+        <span class="response-summary skipped"><%= route.skipped_responses.count %> response(s) skipped</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? -%>
+          <% if request.skipped? -%>
+          <li class="skipped">
+            <% if request.content_type -%><span class="content-type"><%= h request.content_type %></span><% end -%>
+            <span class="skipped-note">Skipped, not covered by any test</span>
+          </li>
+          <% elsif request.finished? -%>
           <li class="covered">
             <span>✅</span>
             <% if request.content_type -%><span class="content-type"><%= h request.content_type %></span><% end -%>
@@ -55,11 +78,16 @@
           <% 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? -%>
+          <% if response.skipped? -%>
+          <li class="skipped">
+            <span class="status"><%= h response.status %></span>
+            <% if response.content_type -%><span class="content-type"><%= h response.content_type %></span><% end -%>
+            <span class="skipped-note">Skipped</span>
+          </li>
+          <% elsif response.finished? -%>
           <li class="covered">
             <span>✅</span>
             <span class="status"><%= h response.status %></span>

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

@@ -8,6 +8,8 @@ module OpenapiFirst
     module Coverage
       # Writes a self-contained HTML coverage report to a file.
       class HtmlReporter
+        include SkippedSummary
+
         def initialize(output: 'coverage/openapi_coverage.html', verbose: false, logger: Test.logger)
           @output = output
           @verbose = verbose
@@ -18,9 +20,17 @@ module OpenapiFirst
           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}"
+          coverage_result.plans.each do |plan|
+            next if plan.coverage >= 100
+
+            logger.info "API validation coverage for #{plan.api_identifier}: #{plan.coverage.round(4)}%"
+          end
+          log_skipped_summary(coverage_result)
+          logger.info "API coverage report written to #{@output}"
         end
 
+        private attr_reader :logger
+
         TEMPLATE_PATH = File.join(__dir__, 'html_reporter.html.erb')
         TEMPLATE = ERB.new(File.read(TEMPLATE_PATH), trim_mode: '-')
         TEMPLATE.filename = TEMPLATE_PATH

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

@@ -14,14 +14,13 @@ module OpenapiFirst
 
         def self.for(oad, skip_response: nil, skip_route: nil)
           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|
-            responses = skip_response ? route.responses.reject(&skip_response) : route.responses
+          oad.routes.each do |route|
             plan.add_route request_method: route.request_method,
                            path: route.path,
                            requests: route.requests,
-                           responses:
+                           responses: route.responses,
+                           skipped: skip_route ? skip_route[route.path, route.request_method] : false,
+                           skip_response:
           end
           plan
         end
@@ -63,15 +62,36 @@ module OpenapiFirst
           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
+        def skipped_requests
+          routes.flat_map(&:skipped_requests)
+        end
+
+        def skipped_responses
+          routes.flat_map(&:skipped_responses)
+        end
+
+        def skipped_requests_count
+          skipped_requests.count
+        end
+
+        def skipped_responses_count
+          skipped_responses.count
+        end
+
+        def add_route(request_method:, path:, requests:, responses:, skipped: false, skip_response: nil)
+          request_tasks = requests.to_a.map { |request| add_task RequestTask.new(request, skipped:) }
           response_tasks = responses.to_a.map do |response|
-            index[response.key] = ResponseTask.new(response)
+            add_task ResponseTask.new(response, skipped: skipped || (skip_response ? skip_response[response] : false))
           end
           @routes << RouteTask.new(path:, request_method:, requests: request_tasks, responses: response_tasks)
         end
+
+        private
+
+        def add_task(task)
+          index[task.key] = task unless task.skipped?
+          task
+        end
       end
     end
   end

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

@@ -9,10 +9,11 @@ module OpenapiFirst
       class RequestTask
         extend Forwardable
 
-        def_delegators :@request, :path, :request_method, :content_type
+        def_delegators :@request, :key, :path, :request_method, :content_type
 
-        def initialize(request_definition)
+        def initialize(request_definition, skipped: false)
           @request = request_definition
+          @skipped = skipped
           @requested = false
           @last_error_message = nil
         end
@@ -25,6 +26,10 @@ module OpenapiFirst
           @last_error_message = validated_request.error.exception_message unless validated_request.valid?
         end
 
+        def skipped?
+          @skipped == true
+        end
+
         def requested?
           @requested == true
         end

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

@@ -11,8 +11,9 @@ module OpenapiFirst
 
         def_delegators :@response, :status, :content_type, :key
 
-        def initialize(response_definition)
+        def initialize(response_definition, skipped: false)
           @response = response_definition
+          @skipped = skipped
           @responded = false
           @last_error_message = nil
         end
@@ -25,6 +26,10 @@ module OpenapiFirst
           @last_error_message = validated_response.error.exception_message unless validated_response.valid?
         end
 
+        def skipped?
+          @skipped == true
+        end
+
         def responded?
           @responded == true
         end

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

@@ -4,8 +4,30 @@ module OpenapiFirst
   module Test
     module Coverage
       RouteTask = Data.define(:path, :request_method, :requests, :responses) do
+        def skipped?
+          requests.all?(&:skipped?)
+        end
+
+        def tracked_requests
+          requests.reject(&:skipped?)
+        end
+
+        def tracked_responses
+          responses.reject(&:skipped?)
+        end
+
+        def skipped_requests
+          requests.select(&:skipped?)
+        end
+
+        def skipped_responses
+          responses.select(&:skipped?)
+        end
+
         def finished?
-          requests.all?(&:finished?) && responses.all?(&:finished?)
+          return false if skipped?
+
+          tracked_requests.all?(&:finished?) && tracked_responses.all?(&:finished?)
         end
 
         def summary

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OpenapiFirst
+  module Test
+    module Coverage
+      # Shared reporting of skipped requests and responses for coverage reporters.
+      module SkippedSummary
+        def log_skipped_summary(coverage_result)
+          requests = coverage_result.skipped_requests_count
+          responses = coverage_result.skipped_responses_count
+          return if requests.zero? && responses.zero?
+
+          logger.info "API coverage skipped #{requests} request(s) and #{responses} response(s)."
+          return if requests.zero?
+
+          logger.warn "#{requests} request(s) were skipped entirely. " \
+                      'These requests are excluded from API coverage and are not contract-tested at all.'
+        end
+      end
+    end
+  end
+end