rspec-rails-api 0.4.0 → 0.6.0

data/lib/rspec/rails/api/dsl/example.rb

@@ -9,14 +9,15 @@ module RSpec
           ##
           # Visits the current example and tests the response
           #
-          # @param example     [Hash] Current example
-          # @param path_params [Hash] Path parameters definition
-          # @param payload     [Hash] Request body
-          # @param headers     [Hash] Custom headers
+          # @param example             [Hash] Current example
+          # @param path_params         [Hash] Path parameters definition
+          # @param payload             [Hash] Request body
+          # @param headers             [Hash] Custom headers
+          # @param ignore_content_type [Boolean] Whether to ignore the response's content-type for this response only
           #
           # @return [void]
-          def test_response_of(example, path_params: {}, payload: {}, headers: {}) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-            raise 'Missing context. Call visit with for_code context.' unless example
+          def test_response_of(example, path_params: {}, payload: {}, headers: {}, ignore_content_type: false, ignore_response: false) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists, Layout/LineLength
+            raise 'Missing context. Call "test_response_of" within a "for_code" block.' unless example
 
             status_code = prepare_status_code example.class.description
 
@@ -25,10 +26,10 @@ module RSpec
 
             send(request_params[:action],
                  request_params[:url],
-                 params:  request_params[:params].to_json,
+                 params:  request_params[:params],
                  headers: request_params[:headers])
 
-            check_response(response, status_code)
+            check_response(response, status_code, ignore_content_type: ignore_content_type) unless ignore_response
 
             return if example.class.description.match?(/-> test (\d+)(.*)/)
 
@@ -38,23 +39,24 @@ module RSpec
           private
 
           ##
-          # Searches for a defined entity in metadata
+          # Searches for a defined entity in example metadata or global entities
+          #
+          # If an entity needs expansion (e.g.: with an attribute like "type: :array, of: :something"), it will use the
+          # scope where the entity was found: global entities or example metadata.
           #
           # @param entity [Symbol] Entity reference
           #
           # @return [RSpec::Rails::Api::EntityConfig, Hash] Defined entity
           def defined(entity)
-            return { type: entity.to_s.split('_').last.to_sym } if PRIMITIVES.include? entity
+            return { type: entity } if PRIMITIVES.include? entity
 
             current_resource = rra_metadata.current_resource
             raise '@current_resource is unset' unless current_resource
 
-            entities = rra_metadata.resources[current_resource][:entities]
-
-            out = entities[entity]
-            raise "Unknown entity '#{entity}' in resource '#{current_resource}'" unless out
+            definition = RSpec::Rails::Api::Metadata.entities[entity.to_sym]
+            raise "Entity '#{entity}' was never defined (globally or in '#{current_resource}')" unless definition
 
-            out.expand_with(entities)
+            definition.expand_with(RSpec::Rails::Api::Metadata.entities)
           end
 
           ##
@@ -62,9 +64,21 @@ module RSpec
           #
           # @param response      [ActionDispatch::TestResponse] The response
           # @param expected_code [Number]                       Code to test for
-          def check_response(response, expected_code) # rubocop:disable Metrics/AbcSize
-            expect(response.status).to eq expected_code
-            expect(response.headers['Content-Type']).to eq 'application/json; charset=utf-8' if expected_code != 204
+          # @param ignore_content_type [Boolean]                Whether to ignore the response's content-type for
+          #                                                     this response only
+          def check_response(response, expected_code, ignore_content_type: false) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity
+            code_error_message = if response.status != expected_code && response.status == 422
+                                   <<~TXT
+                                     expected: #{expected_code}
+                                          got: #{response.status}
+                                     response: #{response.body}
+                                   TXT
+                                 end
+
+            expect(response.status).to eq(expected_code), code_error_message
+            if expected_code != 204 && !ignore_content_type
+              expect(response.headers['Content-Type'].downcase).to eq 'application/json; charset=utf-8'
+            end
             expectations = rra_current_example[:expectations]
             expect(response).to have_many defined(expectations[:many]) if expectations[:many]
             expect(response).to have_one defined(expectations[:one]) if expectations[:one]
@@ -100,9 +114,12 @@ module RSpec
           # @return [Hash] Options for the request
           def prepare_request_params(description, request_params = {}, payload = {}, request_headers = {})
             example_params = description.split
+            verb = example_params[0].downcase
+
+            payload = payload.to_json if verb != 'get'
 
             {
-              action:      example_params[0].downcase,
+              action:      verb,
               url:         prepare_request_url(example_params[1], request_params),
               example_url: example_params[1],
               params:      payload,

data/lib/rspec/rails/api/dsl/example_group.rb

@@ -28,7 +28,7 @@ module RSpec
           #
           # @return [void]
           def entity(type, fields)
-            metadata[:rra].add_entity type, fields
+            RSpec::Rails::Api::Metadata.add_entity type, fields
           end
 
           ##
@@ -78,6 +78,16 @@ module RSpec
             metadata[:rra].add_request_params attributes
           end
 
+          ##
+          # Declares security schemes valid for this path. It won't be enforced during testing but will complete the
+          # documentation. When the reference does not exist, an exception will be thrown _during_ render, not before.
+          #
+          # @param scheme_references [Array<Symbol>] References to a security scheme defined with the renderer's
+          #                                          `add_security_scheme`.
+          def requires_security(*scheme_references)
+            metadata[:rra].add_security_references(*scheme_references)
+          end
+
           ##
           # Defines a GET action
           #
@@ -186,7 +196,7 @@ module RSpec
           #
           # @return [void]
           def execute_for_code_block(callback_block)
-            example 'Test and create documentation', caller: callback_block.send(:caller) do
+            example 'Test response and create documentation', caller: callback_block.send(:caller) do
               instance_eval(&callback_block) if callback_block
             end
           end

data/lib/rspec/rails/api/entity_config.rb

@@ -13,8 +13,8 @@ module RSpec
 
         def initialize(fields)
           @fields = {}
-          fields.each_key do |name|
-            @fields[name] = FieldConfig.new fields[name]
+          fields.each_pair do |name, definition|
+            @fields[name] = FieldConfig.new(**definition)
           end
         end
 
@@ -55,15 +55,12 @@ module RSpec
         # @param attribute [Symbol] Attribute name
         # @param entities  [Hash]   List of entities
         def expand_attribute(attribute, entities)
-          if PRIMITIVES.include? attribute
-            # Primitives support
-            { type: attribute.to_s.split('_').last.to_sym }
-          else
-            # Defined attribute
-            raise "Entity #{attribute} not found for entity completion." unless entities[attribute]
+          # Primitives support
+          return { type: attribute } if PRIMITIVES.include? attribute
 
-            entities[attribute].expand_with(entities)
-          end
+          raise "Entity #{attribute} not found for entity completion." unless entities[attribute]
+
+          entities[attribute].expand_with(entities)
         end
       end
     end

data/lib/rspec/rails/api/field_config.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'rspec/rails/api/entity_config'
-require 'rspec/rails/api/utils'
+require 'rspec/rails/api/validator'
 
 module RSpec
   module Rails
@@ -11,10 +11,13 @@ module RSpec
       class FieldConfig
         attr_accessor :required, :type, :attributes, :description
 
-        def initialize(type:, description:, required: true, attributes: nil, of: nil)
+        def initialize(type:, description:, required: true, attributes: nil, of: nil) # rubocop:disable Metrics/CyclomaticComplexity
           @required    = required
           @description = description
-          raise "Field type not allowed: '#{type}'" unless Utils.check_attribute_type(type)
+
+          raise "Field type not allowed: '#{type}'" unless Validator.valid_type?(type)
+          raise "Don't use 'of' on non-arrays" if of && type != :array
+          raise "Don't use 'attributes' on non-objects" if attributes && type != :object
 
           define_attributes attributes if type == :object
           define_attributes of if type == :array

data/lib/rspec/rails/api/matchers.rb

@@ -1,53 +1,48 @@
 # frozen_string_literal: true
 
 require 'active_support/hash_with_indifferent_access'
+require 'yaml'
 
+require 'rspec/rails/api/validator'
 require 'rspec/rails/api/utils'
 
 ##
 # RSpec matcher to check something against an array of `expected`
-#
-# FIXME: Split the matcher in something else; it's too messy.
 RSpec::Matchers.define :have_many do |expected|
   match do |actual|
-    @actual = actual
-    @actual = JSON.parse(actual.body) if actual.respond_to? :body
+    actual = RSpec::Rails::Api::Utils.hash_from_response actual
 
-    raise "Response is not an array: #{@actual.class}" unless @actual.is_a? Array
-    raise 'Response has no item to compare with' unless @actual.count.positive?
+    raise "Response is not an array: #{actual.class}" unless actual.is_a? Array
+    raise 'Response has no item to compare with' unless actual.count.positive?
 
-    # Primitive type
-    if expected[:type].is_a?(Symbol)
-      @actual.each do |item|
-        return false unless RSpec::Rails::Api::Utils.check_value_type(expected[:type], item)
-      end
+    @errors = RSpec::Rails::Api::Validator.validate_array actual, expected
 
-      return true
-    end
-
-    # Check every entry
-    @actual.each do |item|
-      return false unless RSpec::Rails::Api::Utils.validate_object_structure item, expected
-    end
-
-    true
+    @errors.blank?
   end
 
-  diffable
+  failure_message do |actual|
+    object = RSpec::Rails::Api::Utils.hash_from_response(actual).to_json.chomp
+    RSpec::Rails::Api::Validator.format_failure_message @errors, object
+  end
 end
 
 ##
 # RSpec matcher to check something against the `expected` definition
-# FIXME: Split the matcher in something else; it's too messy.
 RSpec::Matchers.define :have_one do |expected|
   match do |actual|
-    @actual = actual
-    @actual = JSON.parse(actual.body) if actual.respond_to? :body
+    actual = RSpec::Rails::Api::Utils.hash_from_response actual
 
-    raise "Response is not a hash: #{@actual.class}" unless @actual.is_a? Hash
+    @errors = if expected.keys.count == 1 && expected.key?(:type)
+                RSpec::Rails::Api::Validator.validate_type actual, expected[:type]
+              else
+                RSpec::Rails::Api::Validator.validate_object actual, expected
+              end
 
-    RSpec::Rails::Api::Utils.validate_object_structure @actual, expected
+    @errors.blank?
   end
 
-  diffable
+  failure_message do |actual|
+    object = RSpec::Rails::Api::Utils.hash_from_response(actual).to_json.chomp
+    RSpec::Rails::Api::Validator.format_failure_message @errors, object
+  end
 end

data/lib/rspec/rails/api/metadata.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
 require 'rspec/rails/api/utils'
+require 'rspec/rails/api/validator'
 require 'rspec/rails/api/open_api_renderer'
 require 'rspec/rails/api/entity_config'
 
 module RSpec
   module Rails
     module Api
-      # Handles contexts and examples metadatas.
+      # Handles contexts and examples metadata.
       class Metadata # rubocop:disable Metrics/ClassLength
-        attr_reader :entities, :resources, :parameters, :current_resource, :current_url, :current_method, :current_code
+        attr_reader :resources, :parameters, :current_resource, :current_url, :current_method, :current_code
 
         def initialize
           @resources  = {}
-          @entities   = {}
           @parameters = {}
           # Only used when building metadata during RSpec boot
           @current_resource = nil
@@ -22,6 +22,33 @@ module RSpec
           @current_code     = nil
         end
 
+        class << self
+          ##
+          # Define an entity globally.
+          #
+          # Global entities will be available within the specs, but if they are re-declared locally, the local variant
+          # will be used.
+          #
+          # @param name   [Symbol] Entity name
+          # @param fields [Hash]   Fields definitions
+          #
+          # @return [void]
+          def add_entity(name, fields)
+            @entities ||= {}
+            raise "#{name} is already declared" if @entities.key? name
+
+            @entities[name] = EntityConfig.new fields
+          end
+
+          def entities
+            @entities || {}
+          end
+
+          def reset
+            @entities = {}
+          end
+        end
+
         ##
         # Adds a resource to metadata
         #
@@ -30,24 +57,10 @@ module RSpec
         #
         # @return [void]
         def add_resource(name, description)
-          @resources[name.to_sym] = { description: description, paths: {} }
+          @resources[name.to_sym] ||= { description: description, paths: {} }
           @current_resource       = name.to_sym
         end
 
-        ##
-        # Adds an entity definition
-        #
-        # @param name   [Symbol] Entity name
-        # @param fields [Hash]   Fields definitions
-        #
-        #
-        # @return [void]
-        def add_entity(name, fields)
-          Utils.deep_set(@resources,
-                         "#{@current_resource}.entities.#{name}",
-                         EntityConfig.new(fields))
-        end
-
         ##
         # Adds a parameter definition
         #
@@ -60,6 +73,7 @@ module RSpec
 
           fields.each_value do |field|
             field[:required] = true unless field[:required] == false
+            field[:schema] = { type: field[:of] } if field[:type] == :array && PRIMITIVES.include?(field[:of])
           end
           @parameters[name] = fields
         end
@@ -76,11 +90,11 @@ module RSpec
           chunks = @current_url.split('?')
 
           fields.each do |name, field|
-            valid_attribute = Utils.check_attribute_type(field[:type], except: %i[array object])
+            valid_attribute = Validator.valid_type?(field[:type], except: %i[array object])
             raise "Field type not allowed: #{field[:type]}" unless valid_attribute
 
             scope = path_param_scope(chunks, name)
-            Utils.deep_set(@resources, "#{@current_resource}.paths.#{@current_url}.path_params.#{name}",
+            Utils.deep_set(@resources, [@current_resource, 'paths', @current_url, 'path_params', name],
                            description: field[:description] || nil,
                            type:        field[:type] || nil,
                            required:    field[:required] || true,
@@ -109,10 +123,24 @@ module RSpec
 
           params = organize_params fields
           Utils.deep_set(@resources,
-                         "#{@current_resource}.paths.#{@current_url}.actions.#{@current_method}.params",
+                         [@current_resource, 'paths', @current_url, 'actions', @current_method, 'params'],
                          params)
         end
 
+        # Associate a defined security scheme to this request
+        #
+        # @param references [Array<Symbol>] Security scheme reference
+        def add_security_references(*references)
+          check_current_context :resource, :url, :method
+
+          refs = @resources.dig @current_resource, 'paths', @current_url, 'actions', @current_method, 'security'
+          refs ||= []
+          refs += references
+          Utils.deep_set(@resources,
+                         [@current_resource, 'paths', @current_url, 'actions', @current_method, 'security'],
+                         refs)
+        end
+
         ##
         # Adds an action and sets `@current_url` and `@current_method`
         #
@@ -125,7 +153,7 @@ module RSpec
         def add_action(method, url, summary, description = '')
           check_current_context :resource
 
-          Utils.deep_set(@resources, "#{@current_resource}.paths.#{url}.actions.#{method}",
+          Utils.deep_set(@resources, [@current_resource, 'paths', url, 'actions', method],
                          description: description || '',
                          summary:     summary,
                          statuses:    {},
@@ -148,7 +176,7 @@ module RSpec
           check_current_context :resource, :url, :method
 
           Utils.deep_set(@resources,
-                         "#{@current_resource}.paths.#{@current_url}.actions.#{@current_method}.statuses.#{status_code}",
+                         [@current_resource, 'paths', @current_url, 'actions', @current_method, 'statuses', status_code],
                          description: description,
                          example:     { response: nil })
           @current_code = status_code
@@ -160,10 +188,13 @@ module RSpec
         #
         # @return [Hash] Current example metadata
         def current_example
-          # rubocop:disable Layout/LineLength
-          Utils.deep_get @resources,
-                         "#{@current_resource}.paths.#{@current_url}.actions.#{@current_method}.statuses.#{@current_code}"
-          # rubocop:enable Layout/LineLength
+          @resources.dig @current_resource,
+                         :paths,
+                         @current_url.to_sym,
+                         :actions,
+                         @current_method.to_sym,
+                         :statuses,
+                         @current_code.to_s.to_sym
         end
 
         ##
@@ -179,7 +210,7 @@ module RSpec
 
           # rubocop:disable Layout/LineLength
           Utils.deep_set(@resources,
-                         "#{@current_resource}.paths.#{@current_url}.actions.#{@current_method}.statuses.#{@current_code}.expectations",
+                         [@current_resource, 'paths', @current_url, 'actions', @current_method, 'statuses', @current_code, 'expectations'],
                          {
                            one:  one,
                            many: many,
@@ -195,20 +226,20 @@ module RSpec
         # @param action      [String, nil]  HTTP verb
         # @param status_code [Integer, nil] Status code
         # @param response    [String, nil]  Response body
-        # @param path_params [Hash, nil]    Used path parameterss
+        # @param path_params [Hash, nil]    Used path parameters
         # @param params      [Hash, nil]    Used body parameters
         #
         # rubocop:disable Metrics/ParameterLists
         def add_request_example(url: nil, action: nil, status_code: nil, response: nil, path_params: nil, params: nil)
           resource = nil
           @resources.each do |key, res|
-            resource = key if Utils.deep_get(res, "paths.#{url}.actions.#{action}.statuses.#{status_code}")
+            resource = key if res.dig :paths, url.to_sym, :actions, action.to_sym, :statuses, status_code.to_s.to_sym
           end
 
           raise "Resource not found for #{action.upcase} #{url}" unless resource
 
           Utils.deep_set(@resources,
-                         "#{resource}.paths.#{url}.actions.#{action}.statuses.#{status_code}.example",
+                         [resource, 'paths', url, 'actions', action, 'statuses', status_code, 'example'],
                          path_params: path_params,
                          params:      params,
                          response:    response)
@@ -261,12 +292,16 @@ module RSpec
         ##
         # Checks and complete a field definition
         #
-        # @param fields [Hash] Fields definitions
+        # @param fields [Hash,Symbol] Fields definitions
         #
-        # @return [Hash] Completed field definition
-        def organize_params(fields) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        # @return [Hash,Symbol] Completed field definition
+        def organize_params(fields) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          return fields if fields.is_a?(Symbol) && PRIMITIVES.include?(fields)
+          raise "Unsupported type \"#{fields}\"" unless fields.is_a? Hash
+
           out      = { properties: {} }
           required = []
+
           allowed_types = %i[array object]
           fields.each do |name, field|
             allowed_type = allowed_types.include?(field[:type]) || PARAM_TYPES.key?(field[:type])
@@ -286,7 +321,7 @@ module RSpec
         # @param field [Hash] Parameter definition
         #
         # @return [Hash] Completed parameter
-        def fill_request_param(field)
+        def fill_request_param(field) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
           if field[:type] == :object && field[:attributes]
             organize_params field[:attributes]
           else
@@ -294,6 +329,7 @@ module RSpec
               type:        PARAM_TYPES[field[:type]][:type],
               description: field[:description] || nil,
             }
+            properties[:format] = PARAM_TYPES[field[:type]][:format] if PARAM_TYPES[field[:type]][:format]
 
             properties[:items] = organize_params field[:of] if field[:type] == :array && field[:of]
             properties