skooma 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f8caa0911924b17126cad7544d4c54e4fe3f819c6b21c3489cd47180bb69996
-  data.tar.gz: 052a2f72272a02b99cb44f62b6a1b1a319ca1c743742c66125d4da4ae9b402c1
+  metadata.gz: de042bc8ca38a43927cc9f6c1fdb829aecbbf214f771f9a092345f25d2d2f36a
+  data.tar.gz: a084b23b9eeb66af1a36d010b99bc86ae4e1b0c39e470096fc2ef788c9afb725
 SHA512:
-  metadata.gz: 4392d35e7aade0d2683f38ef782ed6b2b980aee835ea489f173202ff75627a4cff4bc3ae522bb9e06ed6b69d7b073a08520902a3a6388cd22f3e8321bbedbb08
-  data.tar.gz: 990bfcb689cd4ad8f76060c955abf9ce01fd3513a54499592136045d1f87f3000575356b1d0e7ddea78b16cc76e516d099dfeda18c35c36426a6426e933068ea
+  metadata.gz: 4286775a7c888f90b46fb35b827ce0f0f21c10ffd4737f6823326a14e00a21786f3e976877d71aee7b07a6578b09188fbe5334c8c67e4f24b78ccfe6ccc00494
+  data.tar.gz: 92e474fe454174ad5d4f1703cf8b1a9c3f9bd47bbe6eb382f60912926e28e3f9888acc612cc751c18ca8d7182f8c0922507302fbde8570ade7c0c7950c76925c

data/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.3.2] - 2024-06-24
+
+### Fixed
+
+- Fix deprecation `MiniTest::Unit.after_tests is now Minitest.after_run`. ([@barnaclebarnes])
+- Exclude test helpers from eager loading. ([@skryukov])
+- Update oas-3.1 base schema. ([@skryukov])
+
+## [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 +74,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
 
@@ -83,10 +118,13 @@ end
 
 - Initial implementation. ([@skryukov])
 
+[@barnaclebarnes]: https://github.com/barnaclebarnes
 [@skryukov]: https://github.com/skryukov
 [@ursm]: https://github.com/ursm
 
-[Unreleased]: https://github.com/skryukov/skooma/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/skryukov/skooma/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/skryukov/skooma/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/skryukov/skooma/compare/v0.3.0...v0.3.1
 [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

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/data/oas-3.1/meta/base.json

@@ -18,15 +18,6 @@
         "externalDocs": { "$ref": "#/$defs/external-docs" },
         "xml": { "$ref": "#/$defs/xml" }
     },
-    "dependentSchemas": {
-      "discriminator": {
-        "anyOf": [
-          { "required": [ "oneOf" ] },
-          { "required": [ "anyOf" ] },
-          { "required": [ "allOf" ] }
-        ]
-      }
-    },
 
     "$defs": {
         "extensible": {

data/data/oas-3.1/schema/2022-10-07.json

@@ -167,8 +167,7 @@
       "type": "object",
       "properties": {
         "url": {
-          "type": "string",
-          "format": "uri-reference"
+          "type": "string"
         },
         "description": {
           "type": "string"
@@ -525,7 +524,7 @@
               "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-cookie"
             },
             {
-              "$ref": "#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-form"
+              "$ref": "#/$defs/styles-for-form"
             }
           ],
           "$defs": {
@@ -542,9 +541,6 @@
               },
               "then": {
                 "properties": {
-                  "name": {
-                    "pattern": "[^/#?]+$"
-                  },
                   "style": {
                     "default": "simple",
                     "enum": [
@@ -630,32 +626,6 @@
                   }
                 }
               }
-            },
-            "styles-for-form": {
-              "if": {
-                "properties": {
-                  "style": {
-                    "const": "form"
-                  }
-                },
-                "required": [
-                  "style"
-                ]
-              },
-              "then": {
-                "properties": {
-                  "explode": {
-                    "default": true
-                  }
-                }
-              },
-              "else": {
-                "properties": {
-                  "explode": {
-                    "default": false
-                  }
-                }
-              }
             }
           }
         }
@@ -782,38 +752,10 @@
           "$ref": "#/$defs/specification-extensions"
         },
         {
-          "$ref": "#/$defs/encoding/$defs/explode-default"
+          "$ref": "#/$defs/styles-for-form"
         }
       ],
-      "unevaluatedProperties": false,
-      "$defs": {
-        "explode-default": {
-          "if": {
-            "properties": {
-              "style": {
-                "const": "form"
-              }
-            },
-            "required": [
-              "style"
-            ]
-          },
-          "then": {
-            "properties": {
-              "explode": {
-                "default": true
-              }
-            }
-          },
-          "else": {
-            "properties": {
-              "explode": {
-                "default": false
-              }
-            }
-          }
-        }
-      }
+      "unevaluatedProperties": false
     },
     "responses": {
       "$comment": "https://spec.openapis.org/oas/v3.1.0#responses-object",
@@ -1100,8 +1042,7 @@
         "description": {
           "type": "string"
         }
-      },
-      "unevaluatedProperties": false
+      }
     },
     "schema": {
       "$comment": "https://spec.openapis.org/oas/v3.1.0#schema-object",
@@ -1436,6 +1377,32 @@
       "additionalProperties": {
         "type": "string"
       }
+    },
+    "styles-for-form": {
+      "if": {
+        "properties": {
+          "style": {
+            "const": "form"
+          }
+        },
+        "required": [
+          "style"
+        ]
+      },
+      "then": {
+        "properties": {
+          "explode": {
+            "default": true
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "explode": {
+            "default": false
+          }
+        }
+      }
     }
   }
 }

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.after_run { 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.2"
 end

data/lib/skooma.rb

@@ -7,6 +7,11 @@ require_relative "skooma/inflector"
 
 loader = Zeitwerk::Loader.for_gem
 loader.inflector = Skooma::Inflector.new(__FILE__)
+
+# Do not eager load the test helpers
+loader.do_not_eager_load(File.join(__dir__, "skooma", "minitest.rb"))
+loader.do_not_eager_load(File.join(__dir__, "skooma", "rspec.rb"))
+
 loader.setup
 
 module Skooma

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skooma
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Svyatoslav Kryukov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-09 00:00:00.000000000 Z
+date: 2024-06-24 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.