rspec-rails-api 0.3.4 → 0.5.0

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

@@ -9,99 +9,185 @@ module RSpec
         # All these methods will be available in example groups
         # (anything but 'it', 'example', 'for_code')
         module ExampleGroup
-          # First method to be called in a spec file
-          # as it will initialize the metadatas.
+          ##
+          # First method to be called in a spec file # as it will initialize the
+          # metadata.
+          #
+          # @param name        [String] Resource name
+          # @param description [String] Resource description
           def resource(name, description = '')
-            metadata[:rrad] ||= Metadata.new
-            metadata[:rrad].add_resource name, description
+            metadata[:rra] ||= Metadata.new
+            metadata[:rra].add_resource name, description
           end
 
-          # Used to describe an entity
+          ##
+          # Describes an entity
+          #
+          # @param type   [Symbol] Name of the entity for reference
+          # @param fields [Hash]   Fields declarations
+          #
+          # @return [void]
           def entity(type, fields)
-            metadata[:rrad].add_entity type, fields
+            metadata[:rra].add_entity type, fields
           end
 
-          # Used to describe a request or path param which will be available as reference
+          ##
+          # Describes request or path parameters
+          #
+          # @param type   [Symbol] Name of the parameters set for reference
+          # @param fields [Hash]   Fields declarations
+          #
+          # @return [void]
           def parameters(type, fields)
-            metadata[:rrad].add_parameter type, fields
+            metadata[:rra].add_parameter type, fields
           end
 
-          # Used to describe query parameters
+          ##
+          # Declares parameters used in URLS (_path_)
+          # Use `fields` or `defined` but not both.
+          #
+          # @param [Hash, nil]   fields  An attributes declaration
+          # @param [Symbol, nil] defined An entity reference
+          #
+          # @return [void]
           def path_params(fields: nil, defined: nil)
-            if defined && !metadata[:rrad].parameters[defined]
+            if defined && !metadata[:rra].parameters[defined]
               raise "Parameter #{defined} was not defined with the 'parameters' method"
             end
 
-            fields ||= metadata[:rrad].parameters[defined]
+            fields ||= metadata[:rra].parameters[defined]
 
-            metadata[:rrad].add_path_params fields
+            metadata[:rra].add_path_params fields
           end
 
+          ##
+          # Declares parameters for a request body
+          # Use `attributes` or `defined` but not both.
+          #
+          # @param [Hash, nil]   attributes An attributes declaration
+          # @param [Symbol, nil] defined    An entity reference.
+          #
+          # @return [void]
           def request_params(attributes: nil, defined: nil)
-            if defined && !metadata[:rrad].parameters[defined]
+            if defined && !metadata[:rra].parameters[defined]
               raise "Parameter #{defined} was not defined with the 'parameters' method"
             end
 
-            attributes ||= metadata[:rrad].parameters[defined]
+            attributes ||= metadata[:rra].parameters[defined]
 
-            metadata[:rrad].add_request_params attributes
+            metadata[:rra].add_request_params attributes
           end
 
-          def on_get(url, description = nil, &block)
-            on_action(:get, url, description, &block)
+          ##
+          # Defines a GET action
+          #
+          # @param [String] url         URL to test
+          # @param [String] summary     What the action does
+          # @param [String] description Longer description
+          #
+          # @return [void]
+          def on_get(url, summary = nil, description = nil, &block)
+            on_action(:get, url, summary, description, &block)
           end
 
-          def on_post(url, description = nil, &block)
-            on_action(:post, url, description, &block)
+          ##
+          # Defines a POST action
+          #
+          # @param [String] url         URL to test
+          # @param [String] summary     What the action does
+          # @param [String] description Longer description
+          #
+          # @return [void]
+          def on_post(url, summary = nil, description = nil, &block)
+            on_action(:post, url, summary, description, &block)
           end
 
-          def on_put(url, description = nil, &block)
-            on_action(:put, url, description, &block)
+          ##
+          # Defines a PUT action
+          #
+          # @param [String] url         URL to test
+          # @param [String] summary     What the action does
+          # @param [String] description Longer description
+          #
+          # @return [void]
+          def on_put(url, summary = nil, description = nil, &block)
+            on_action(:put, url, summary, description, &block)
           end
 
-          def on_patch(url, description = nil, &block)
-            on_action(:patch, url, description, &block)
+          ##
+          # Defines a PATCH action
+          #
+          # @param [String] url         URL to test
+          # @param [String] summary     What the action does
+          # @param [String] description Longer description
+          #
+          # @return [void]
+          def on_patch(url, summary = nil, description = nil, &block)
+            on_action(:patch, url, summary, description, &block)
           end
 
-          def on_delete(url, description = nil, &block)
-            on_action(:delete, url, description, &block)
+          ##
+          # Defines a DELETE action
+          #
+          # @param [String] url         URL to test
+          # @param [String] summary     What the action does
+          # @param [String] description Longer description
+          #
+          # @return [void]
+          def on_delete(url, summary = nil, description = nil, &block)
+            on_action(:delete, url, summary, description, &block)
           end
 
-          # Currently fill metadatas with the action
-          def on_action(action, url, description, &block)
-            metadata[:rrad].add_action(action, url, description)
-
-            describe("#{action.upcase} #{url}", &block)
-          end
-
-          def for_code(status_code, description = nil, doc_only: false, test_only: false, &block)
+          ##
+          # Adds an HTTP code declaration to metadata, with expected result
+          # If no expectation is provided, the response will be expected to be empty
+          #
+          # @param status_code [Number]  Status code to test for
+          # @param description [String]  Description of the route/status pair
+          # @param expect_many [Symbol]  Check the response for a list of given entity
+          # @param expect_one  [Symbol]  Check the response for a given entity
+          # @param test_only   [Boolean] When true, test the response without filling the documentation
+          #
+          # @return [void]
+          #
+          def for_code(status_code, description = nil, expect_many: nil, expect_one: false, test_only: false, &block)
             description ||= Rack::Utils::HTTP_STATUS_CODES[status_code]
 
-            metadata[:rrad].add_status_code(status_code, description) unless test_only
+            metadata[:rra].add_status_code(status_code, description) unless test_only
+            metadata[:rra].add_expectations(expect_one, expect_many)
+            metadata[:rra_current_example] = metadata[:rra].current_example
 
             describe "->#{test_only ? ' test' : ''} #{status_code} - #{description}" do
-              execute_for_code_block(status_code, doc_only, block)
+              execute_for_code_block(block)
             end
           end
 
           private
 
-          def document_only(status_code)
-            example 'Create documentation' do |example|
-              parent_example = example.example_group
-              request_params = prepare_request_params parent_example.module_parent.description
+          ##
+          # Currently fill metadata with the action
+          #
+          # @param [Symbol]      action      HTTP verb
+          # @param [String]      url         URL to test
+          # @param [String, nil] summary     What the action does
+          # @param [String, nil] description Longer description
+          #
+          # @return [void]
+          def on_action(action, url, summary, description, &block)
+            metadata[:rra].add_action(action, url, summary, description)
 
-              set_request_example parent_example.metadata[:rrad], request_params, status_code
-            end
+            describe("#{action.upcase} #{url}", &block)
           end
 
-          def execute_for_code_block(status_code, doc_only, callback_block)
-            if (!ENV['DOC_ONLY'] || ENV['DOC_ONLY'] == 'false' || !doc_only) && callback_block
-              example 'Test and create documentation', caller: callback_block.send(:caller) do
-                instance_eval(&callback_block) if callback_block
-              end
-            else
-              document_only status_code
+          ##
+          # Visit the URL and test response
+          #
+          # @param callback_block [block]   Block to execute for testing the response
+          #
+          # @return [void]
+          def execute_for_code_block(callback_block)
+            example 'Test response and create documentation', caller: callback_block.send(:caller) do
+              instance_eval(&callback_block) if callback_block
             end
           end
         end

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

@@ -18,6 +18,8 @@ module RSpec
           end
         end
 
+        ##
+        # @return [Hash] Entity configuration
         def to_h
           out = {}
           @fields.each_key do |key|
@@ -26,18 +28,40 @@ module RSpec
           out
         end
 
+        ##
+        # Replaces the arrays 'of' and objects 'attributes' with the corresponding
+        # entities, recursively
+        #
+        # @param entities [Hash] List of entities
+        #
+        # @return [Hash]
         def expand_with(entities)
           hash = to_h
           hash.each_pair do |field, config|
             next unless %i[array object].include? config[:type]
 
-            attributes = config[:attributes]
-            next unless attributes.is_a? Symbol
-            raise "Entity #{attributes} not found for entity completion." unless entities[attributes]
+            attribute = config[:attributes]
+            next unless attribute.is_a? Symbol
 
-            hash[field][:attributes] = entities[attributes].expand_with(entities)
+            hash[field][:attributes] = expand_attribute attribute, entities
           end
         end
+
+        private
+
+        ##
+        # Expands an attribute for "for" and "attributes" keys
+        #
+        # @param attribute [Symbol] Attribute name
+        # @param entities  [Hash]   List of entities
+        def expand_attribute(attribute, entities)
+          # Primitives support
+          return { type: attribute } if PRIMITIVES.include? attribute
+
+          raise "Entity #{attribute} not found for entity completion." unless entities[attribute]
+
+          entities[attribute].expand_with(entities)
+        end
       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
@@ -14,7 +14,7 @@ module RSpec
         def initialize(type:, description:, required: true, attributes: nil, of: nil)
           @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)
 
           define_attributes attributes if type == :object
           define_attributes of if type == :array
@@ -22,6 +22,8 @@ module RSpec
           @type = type
         end
 
+        ##
+        # @return [Hash] Field configuration
         def to_h
           out               = { required: @required, type: @type }
           out[:description] = @description unless @description.nil?
@@ -39,6 +41,12 @@ module RSpec
 
         private
 
+        ##
+        # Sets @attributes of the field when it's an Array or Hash
+        #
+        # @param attributes [Hash, Symbol] The attributes definition or reference
+        #
+        # @return [void]
         def define_attributes(attributes)
           @attributes = case attributes
                         when Hash

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

@@ -1,40 +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'
 
-# FIXME: Split the matcher in something else; it's too messy.
+##
+# RSpec matcher to check something against an array of `expected`
 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?
 
-    # Check every entry
-    ok = true
-    @actual.each do |item|
-      ok = false unless RSpec::Rails::Api::Utils.validate_object_structure item, expected
-    end
+    @errors = RSpec::Rails::Api::Validator.validate_array actual, expected
 
-    ok
+    @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
 
-# FIXME: Split the matcher in something else; it's too messy.
+##
+# RSpec matcher to check something against the `expected` definition
 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