skooma 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f8caa0911924b17126cad7544d4c54e4fe3f819c6b21c3489cd47180bb69996
-  data.tar.gz: 052a2f72272a02b99cb44f62b6a1b1a319ca1c743742c66125d4da4ae9b402c1
+  metadata.gz: 680f73ad3319719625bdf805f0c50d8ce56ec6294329dcf225a6e7f4bf29d53f
+  data.tar.gz: 7e512d7bb1d3a39d03e35a63ec687c9de23c35d3f13b777d7b1bbbdf0880e529
 SHA512:
-  metadata.gz: 4392d35e7aade0d2683f38ef782ed6b2b980aee835ea489f173202ff75627a4cff4bc3ae522bb9e06ed6b69d7b073a08520902a3a6388cd22f3e8321bbedbb08
-  data.tar.gz: 990bfcb689cd4ad8f76060c955abf9ce01fd3513a54499592136045d1f87f3000575356b1d0e7ddea78b16cc76e516d099dfeda18c35c36426a6426e933068ea
+  metadata.gz: ecc1c3a07b2fc417fbc47ba497ee53af09f3186ecf8d35c13a7e0d8e03bc0cfc0ca9bacdc6bd5a879d46f7b8d517858d605cafc02494d11bc39a794f0c385eea
+  data.tar.gz: 94f69160fb4914679a94bd28ccc48e7e5d0a9664a1cb26ed469906be66e3232dc7be13c4ce11190d04b08ebce52557c17e24b57adb14d0b15542f9fa0994fb52

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.3.1] - 2024-04-11
+
+### Added
+
+- Add coverage for tested API operations. ([@skryukov])
+ 
+    ```ruby
+    
+    # spec/rails_helper.rb
+    
+    RSpec.configure do |config|
+      # To enable coverage, pass `coverage: :report` option,
+      # and to raise an error when an operation is not covered, pass `coverage: :strict` option:
+      config.include Skooma::RSpec[Rails.root.join("docs", "openapi.yml"), coverage: :report], type: :request
+    end
+    ```
+
+    ```shell
+    $ bundle exec rspec
+    # ...
+    OpenAPI schema /openapi.yml coverage report: 110 / 194 operations (56.7%) covered.
+    Uncovered paths:
+    GET /api/uncovered 200
+    GET /api/partially_covered 403
+    # ...
+    ```
+
 ## [0.3.0] - 2024-04-09
 
 ### Changed
@@ -39,16 +66,16 @@ and this project adheres to [Semantic Versioning].
 
 - Add support for APIs mounted under a path prefix. ([@skryukov])
 
-```ruby
-# spec/rails_helper.rb
-
-RSpec.configure do |config|
-  # ...
-  path_to_openapi = Rails.root.join("docs", "openapi.yml")
-  # pass path_prefix option if your API is mounted under a prefix:
-  config.include Skooma::RSpec[path_to_openapi, path_prefix: "/internal/api"], type: :request
-end
-```
+    ```ruby
+    # spec/rails_helper.rb
+    
+    RSpec.configure do |config|
+      # ...
+      path_to_openapi = Rails.root.join("docs", "openapi.yml")
+      # pass path_prefix option if your API is mounted under a prefix:
+      config.include Skooma::RSpec[path_to_openapi, path_prefix: "/internal/api"], type: :request
+    end
+    ```
 
 ### Changed
 

data/README.md

@@ -16,7 +16,7 @@ Skooma is a Ruby library for validating API implementations against OpenAPI docu
 
 ### Learn more
 
-- [Let there be docs! A documentation-first approach to Rails API development](https://evilmartians.com/events/let-there-be-docs-a-documentation-first-approach-to-rails-api-development) – Talk and slides from Friendly.rb 2023
+- [Let there be docs! A documentation-first approach to Rails API development](https://evilmartians.com/chronicles/let-there-be-docs-a-documentation-first-approach-to-rails-api-development)
 
 <a href="https://evilmartians.com/?utm_source=skooma&utm_campaign=project_page">
 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
@@ -51,6 +51,10 @@ RSpec.configure do |config|
 
   # OR pass path_prefix option if your API is mounted under a prefix:
   config.include Skooma::RSpec[path_to_openapi, path_prefix: "/internal/api"], type: :request
+
+  # To enable coverage, pass `coverage: :report` option,
+  # and to raise an error when an operation is not covered, pass `coverage: :strict` option:
+  config.include Skooma::RSpec[path_to_openapi, coverage: :report], type: :request
 end
 ```
 
@@ -115,8 +119,15 @@ end
 
 ```ruby
 # test/test_helper.rb
+path_to_openapi = Rails.root.join("docs", "openapi.yml")
+ActionDispatch::IntegrationTest.include Skooma::Minitest[path_to_openapi]
+
+# OR pass path_prefix option if your API is mounted under a prefix:
+ActionDispatch::IntegrationTest.include Skooma::Minitest[path_to_openapi, path_prefix: "/internal/api"], type: :request
 
-ActionDispatch::IntegrationTest.include Skooma::Minitest[Rails.root.join("docs", "openapi.yml")]
+# To enable coverage, pass `coverage: :report` option,
+# and to raise an error when an operation is not covered, pass `coverage: :strict` option:
+ActionDispatch::IntegrationTest.include Skooma::Minitest[path_to_openapi, coverage: :report], type: :request
 ```
 
 #### Validate OpenAPI document

data/lib/skooma/coverage.rb

@@ -0,0 +1,90 @@
+module Skooma
+  class NoopCoverage
+    def track_request(*)
+    end
+
+    def report
+    end
+  end
+
+  class Coverage
+    class SimpleReport
+      def initialize(coverage)
+        @coverage = coverage
+      end
+
+      attr_reader :coverage
+
+      def report
+        puts <<~MSG
+          OpenAPI schema #{URI.parse(coverage.schema.uri.to_s).path} coverage report: #{coverage.covered_paths.count} / #{coverage.defined_paths.count} operations (#{coverage.covered_percent.round(2)}%) covered.
+          #{coverage.uncovered_paths.empty? ? "All paths are covered!" : "Uncovered paths:"}
+          #{coverage.uncovered_paths.map { |method, path, status| "#{method.upcase} #{path} #{status}" }.join("\n")}
+        MSG
+      end
+    end
+
+    def self.new(schema, mode: nil, format: nil)
+      case mode
+      when nil, false
+        NoopCoverage.new
+      when :report, :strict
+        super
+      else
+        raise ArgumentError, "Invalid coverage: #{mode}, expected :report, :strict, or false"
+      end
+    end
+
+    attr_reader :mode, :format, :defined_paths, :covered_paths, :schema
+
+    def initialize(schema, mode:, format:)
+      @schema = schema
+      @mode = mode
+      @format = format || SimpleReport
+      @defined_paths = find_defined_paths(schema)
+      @covered_paths = Set.new
+    end
+
+    def track_request(result)
+      operation = [nil, nil, nil]
+      result.collect_annotations(result.instance, keys: %w[paths responses]) do |node|
+        case node.key
+        when "paths"
+          operation[0] = node.annotation["method"]
+          operation[1] = node.annotation["current_path"]
+        when "responses"
+          operation[2] = node.annotation
+        end
+      end
+      covered_paths << operation
+    end
+
+    def uncovered_paths
+      defined_paths - covered_paths
+    end
+
+    def covered_percent
+      covered_paths.count * 100.0 / defined_paths.count
+    end
+
+    def report
+      format.new(self).report
+      exit 1 if mode == :strict && uncovered_paths.any?
+    end
+
+    private
+
+    def find_defined_paths(schema)
+      Set.new.tap do |paths|
+        schema["paths"].each do |path, path_item|
+          resolved_path_item = (path_item.key?("$ref") ? path_item.resolve_ref(path_item["$ref"]) : path_item)
+          resolved_path_item.slice("get", "post", "put", "patch", "delete", "options", "head", "trace").each do |method, operation|
+            operation["responses"]&.each do |code, _|
+              paths << [method, path, code]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skooma/matchers/conform_request_schema.rb

@@ -5,13 +5,17 @@ require "pp"
 module Skooma
   module Matchers
     class ConformRequestSchema
-      def initialize(schema, mapped_response)
-        @schema = schema
+      def initialize(skooma, mapped_response)
+        @skooma = skooma
+        @schema = skooma.schema
         @mapped_response = mapped_response
       end
 
       def matches?(*)
         @result = @schema.evaluate(@mapped_response)
+
+        @skooma.coverage.track_request(@result) if @mapped_response["response"]
+
         @result.valid?
       end
 

data/lib/skooma/matchers/conform_response_schema.rb

@@ -3,8 +3,8 @@
 module Skooma
   module Matchers
     class ConformResponseSchema < ConformRequestSchema
-      def initialize(schema, mapped_response, expected)
-        super(schema, mapped_response)
+      def initialize(skooma, mapped_response, expected)
+        super(skooma, mapped_response)
         @expected = expected
       end
 

data/lib/skooma/matchers/wrapper.rb

@@ -38,30 +38,39 @@ module Skooma
 
           raise "Response object not found"
         end
+
+        def skooma_openapi_schema
+          skooma.schema
+        end
       end
 
-      def initialize(helper_methods_module, openapi_path, base_uri: "https://skoomarb.dev/", path_prefix: "")
+      def initialize(helper_methods_module, openapi_path, base_uri: "https://skoomarb.dev/", path_prefix: "", **params)
         super()
 
         registry = create_test_registry
         pathname = Pathname.new(openapi_path)
-        source_uri = "#{base_uri}#{path_prefix.delete_suffix("/")}"
+        source_uri = "#{base_uri}#{path_prefix.delete_suffix("/").delete_prefix("/")}"
         source_uri += "/" unless source_uri.end_with?("/")
         registry.add_source(
           source_uri,
           JSONSkooma::Sources::Local.new(pathname.dirname.to_s)
         )
-        schema = registry.schema(URI.parse("#{source_uri}#{pathname.basename}"), schema_class: Skooma::Objects::OpenAPI)
-        schema.path_prefix = path_prefix
+        @schema = registry.schema(URI.parse("#{source_uri}#{pathname.basename}"), schema_class: Skooma::Objects::OpenAPI)
+        @schema.path_prefix = path_prefix
+
+        @coverage = Coverage.new(@schema, mode: params[:coverage], format: params[:coverage_format])
 
         include DefaultHelperMethods
         include helper_methods_module
 
-        define_method :skooma_openapi_schema do
-          schema
+        skooma_self = self
+        define_method :skooma do
+          skooma_self
         end
       end
 
+      attr_accessor :schema, :coverage
+
       private
 
       def create_test_registry

data/lib/skooma/minitest.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "minitest/unit"
+
 module Skooma
   # Minitest helpers for OpenAPI schema validation
   # @example
@@ -10,19 +12,19 @@ module Skooma
   class Minitest < Matchers::Wrapper
     module HelperMethods
       def assert_conform_schema(expected_status)
-        matcher = Matchers::ConformSchema.new(skooma_openapi_schema, mapped_response, expected_status)
+        matcher = Matchers::ConformSchema.new(skooma, mapped_response, expected_status)
 
         assert matcher.matches?, -> { matcher.failure_message }
       end
 
       def assert_conform_request_schema
-        matcher = Matchers::ConformRequestSchema.new(skooma_openapi_schema, mapped_response(with_response: false))
+        matcher = Matchers::ConformRequestSchema.new(skooma, mapped_response(with_response: false))
 
         assert matcher.matches?, -> { matcher.failure_message }
       end
 
       def assert_conform_response_schema(expected_status)
-        matcher = Matchers::ConformResponseSchema.new(skooma_openapi_schema, mapped_response(with_request: false), expected_status)
+        matcher = Matchers::ConformResponseSchema.new(skooma, mapped_response(with_request: false), expected_status)
 
         assert matcher.matches?, -> { matcher.failure_message }
       end
@@ -36,6 +38,8 @@ module Skooma
 
     def initialize(openapi_path, **params)
       super(HelperMethods, openapi_path, **params)
+
+      MiniTest::Unit.after_tests { coverage.report }
     end
   end
 end

data/lib/skooma/objects/openapi/keywords/paths.rb

@@ -28,6 +28,8 @@ module Skooma
 
             return result.failure("Path #{instance["path"]} not found in schema") unless path
 
+            result.annotate({"current_path" => path})
+
             result.call(instance, path) do |subresult|
               subresult.annotate({"path_attributes" => attributes})
               path_schema.evaluate(instance, subresult)

data/lib/skooma/objects/path_item/keywords/base_operation.rb

@@ -13,12 +13,16 @@ module Skooma
             end
 
             json.evaluate(instance, result)
-            return result.success if result.passed?
 
             path_item_result = result.parent
             path_item_result = path_item_result.parent until path_item_result.key.start_with?("/")
 
-            path = path_item_result.annotation["path"]
+            paths_result = path_item_result.parent
+            paths_result.annotate(paths_result.annotation.merge("method" => key))
+
+            return result.success if result.passed?
+
+            path = paths_result.annotation["current_path"]
 
             result.failure("Path #{path}/#{key} is invalid")
           end

data/lib/skooma/objects/path_item/keywords/delete.rb

@@ -5,7 +5,7 @@ module Skooma
     class PathItem
       module Keywords
         class Delete < BaseOperation
-          self.key = "options"
+          self.key = "delete"
           self.depends_on = %w[parameters]
           self.value_schema = :schema
           self.schema_value_class = Objects::Operation

data/lib/skooma/rspec.rb

@@ -10,15 +10,15 @@ module Skooma
   class RSpec < Matchers::Wrapper
     module HelperMethods
       def conform_schema(expected_status)
-        Matchers::ConformSchema.new(skooma_openapi_schema, mapped_response, expected_status)
+        Matchers::ConformSchema.new(skooma, mapped_response, expected_status)
       end
 
       def conform_response_schema(expected_status)
-        Matchers::ConformResponseSchema.new(skooma_openapi_schema, mapped_response(with_request: false), expected_status)
+        Matchers::ConformResponseSchema.new(skooma, mapped_response(with_request: false), expected_status)
       end
 
       def conform_request_schema
-        Matchers::ConformRequestSchema.new(skooma_openapi_schema, mapped_response(with_response: false))
+        Matchers::ConformRequestSchema.new(skooma, mapped_response(with_response: false))
       end
 
       def be_valid_document
@@ -28,6 +28,13 @@ module Skooma
 
     def initialize(openapi_path, **params)
       super(HelperMethods, openapi_path, **params)
+
+      skooma_self = self
+      ::RSpec.configure do |c|
+        c.after(:suite) do
+          at_exit { skooma_self.coverage.report }
+        end
+      end
     end
   end
 end

data/lib/skooma/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Skooma
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skooma
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Svyatoslav Kryukov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-09 00:00:00.000000000 Z
+date: 2024-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -54,6 +54,7 @@ files:
 - data/oas-3.1/schema/2022-10-07.json
 - lib/skooma.rb
 - lib/skooma/body_parsers.rb
+- lib/skooma/coverage.rb
 - lib/skooma/dialects/oas_3_1.rb
 - lib/skooma/env_mapper.rb
 - lib/skooma/inflector.rb
@@ -163,7 +164,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.5.7
 signing_key:
 specification_version: 4
 summary: Validate API implementations against OpenAPI documents.