skooma 0.2.3 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6263d8960b9a3b49287103608c6770c967b6fadfcf58d826df2a492c4dedbd35
-  data.tar.gz: 5dd2c141d4baa7f0b95c1b3f3fbfd1afdafaae0097a1139956ba1c7e45f876a1
+  metadata.gz: 680f73ad3319719625bdf805f0c50d8ce56ec6294329dcf225a6e7f4bf29d53f
+  data.tar.gz: 7e512d7bb1d3a39d03e35a63ec687c9de23c35d3f13b777d7b1bbbdf0880e529
 SHA512:
-  metadata.gz: e5ddc4010685045a5b2a9908597096af07fb5ac21cce3e1c456568111fed4fc2fb708603be0a47dbd6e61bec0d64e0d85e27841ab36583f0fb61b73759d3f05b
-  data.tar.gz: 1210a2ed7f56206369242baa147795acd3a6bc77aa6b719cb3ccc26ab33367a775921d0d94fd8741b651274afdc9183c20af194e4a289190d5968de239a9ae56
+  metadata.gz: ecc1c3a07b2fc417fbc47ba497ee53af09f3186ecf8d35c13a7e0d8e03bc0cfc0ca9bacdc6bd5a879d46f7b8d517858d605cafc02494d11bc39a794f0c385eea
+  data.tar.gz: 94f69160fb4914679a94bd28ccc48e7e5d0a9664a1cb26ed469906be66e3232dc7be13c4ce11190d04b08ebce52557c17e24b57adb14d0b15542f9fa0994fb52

data/CHANGELOG.md

@@ -7,6 +7,49 @@ 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
+
+- BREAKING CHANGE: Pass `headers` parameter to registered `BodyParsers`. ([@skryukov])
+
+    ```ruby
+    # Before:
+    Skooma::BodyParsers.register("application/xml", ->(body) { Hash.from_xml(body) })
+    # After:
+    Skooma::BodyParsers.register("application/xml", ->(body, headers:) { Hash.from_xml(body) })
+    ```
+### Fixed
+
+- Fix wrong path when combined with Rails exceptions_app. ([@ursm])
+
 ## [0.2.3] - 2024-01-18
 
 ### Added
@@ -23,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
 
@@ -68,8 +111,10 @@ end
 - Initial implementation. ([@skryukov])
 
 [@skryukov]: https://github.com/skryukov
+[@ursm]: https://github.com/ursm
 
-[Unreleased]: https://github.com/skryukov/skooma/compare/v0.2.3...HEAD
+[Unreleased]: https://github.com/skryukov/skooma/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/skryukov/skooma/compare/v0.2.3...v0.3.0
 [0.2.3]: https://github.com/skryukov/skooma/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/skryukov/skooma/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/skryukov/skooma/compare/v0.2.0...v0.2.1

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/body_parsers.rb

@@ -3,7 +3,7 @@
 module Skooma
   module BodyParsers
     class << self
-      DEFAULT_PARSER = ->(body) { body }
+      DEFAULT_PARSER = ->(body, **_options) { body }
 
       def [](media_type)
         parsers[media_type.to_s.strip.downcase] || DEFAULT_PARSER
@@ -20,7 +20,7 @@ module Skooma
     self.parsers = {}
 
     module JSONParser
-      def self.call(body)
+      def self.call(body, **_options)
         JSON.parse(body)
       rescue JSON::ParserError
         body

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/env_mapper.rb

@@ -9,7 +9,7 @@ module Skooma
       def call(env, response = nil, with_response: true, with_request: true)
         result = {
           "method" => env["REQUEST_METHOD"].downcase,
-          "path" => env["PATH_INFO"]
+          "path" => env["action_dispatch.original_path"] || env["PATH_INFO"]
         }
         result["request"] = map_request(env) if with_request
         result["response"] = map_response(response) if response && with_response
@@ -23,10 +23,19 @@ module Skooma
         {
           "query" => env["rack.request.query_string"] || env["QUERY_STRING"],
           "headers" => env.select { |k, _| k.start_with?("HTTP_") || PLAIN_HEADERS.include?(k) }.transform_keys { |k| k.sub(REGEXP_HTTP, "").split("_").map(&:capitalize).join("-") },
-          "body" => env["RAW_POST_DATA"]
+          "body" => env["RAW_POST_DATA"] || read_rack_input(env["rack.input"])
         }
       end
 
+      def read_rack_input(input)
+        return nil unless input.respond_to?(:rewind)
+
+        input.rewind
+        raw_input = input.read
+        input.rewind
+        raw_input
+      end
+
       def map_response(response)
         status, headers, body = response.to_a
         full_body = +""

data/lib/skooma/instance.rb

@@ -63,16 +63,16 @@ module Skooma
         data = {}
         data["status"] = JSONSkooma::JSONNode.new(value.fetch("status"), key: "status", parent: self)
         data["headers"] = Headers.new(value.fetch("headers", {}), key: "headers", parent: self)
-        body_value = parse_body(value["body"], data["headers"]&.[]("Content-Type"))
+        body_value = parse_body(value["body"], data["headers"])
         data["body"] = Attribute.new(body_value, key: "body", parent: self)
         ["object", data]
       end
 
-      def parse_body(body, content_type)
+      def parse_body(body, headers)
         return nil unless body
 
-        parser = BodyParsers[content_type&.split(";")&.first]
-        parser ? parser.call(body) : body
+        parser = BodyParsers[headers["Content-Type"]&.value&.split(";")&.first]
+        parser ? parser.call(body, headers: headers) : body
       end
     end
 
@@ -83,16 +83,16 @@ module Skooma
         data = {}
         data["query"] = Attribute.new(value.fetch("query", ""), key: "query", parent: self)
         data["headers"] = Headers.new(value.fetch("headers", {}), key: "headers", parent: self)
-        body_value = parse_body(value["body"], data["headers"]&.[]("Content-Type"))
+        body_value = parse_body(value["body"], data["headers"])
         data["body"] = Attribute.new(body_value, key: "body", parent: self)
         ["object", data]
       end
 
-      def parse_body(body, content_type)
+      def parse_body(body, headers)
         return nil unless body
 
-        parser = BodyParsers[content_type&.split(";")&.first]
-        parser ? parser.call(body) : body
+        parser = BodyParsers[headers["Content-Type"]&.value&.split(";")&.first]
+        parser ? parser.call(body, headers: headers) : body
       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.2.3"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skooma
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.1
 platform: ruby
 authors:
 - Svyatoslav Kryukov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-18 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.