rspec-rails-api 0.3.4 → 0.4.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 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,16 +28,41 @@ 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)
+          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]
+
+            entities[attribute].expand_with(entities)
           end
         end
       end

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

@@ -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

@@ -4,6 +4,9 @@ require 'active_support/hash_with_indifferent_access'
 
 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|
@@ -13,18 +16,28 @@ RSpec::Matchers.define :have_many do |expected|
     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
+
+      return true
+    end
+
     # Check every entry
-    ok = true
     @actual.each do |item|
-      ok = false unless RSpec::Rails::Api::Utils.validate_object_structure item, expected
+      return false unless RSpec::Rails::Api::Utils.validate_object_structure item, expected
     end
 
-    ok
+    true
   end
 
   diffable
 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|

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

@@ -9,7 +9,7 @@ module RSpec
     module Api
       # Handles contexts and examples metadatas.
       class Metadata # rubocop:disable Metrics/ClassLength
-        attr_reader :entities, :resources, :current_resource, :parameters
+        attr_reader :entities, :resources, :parameters, :current_resource, :current_url, :current_method, :current_code
 
         def initialize
           @resources  = {}
@@ -22,26 +22,54 @@ module RSpec
           @current_code     = nil
         end
 
+        ##
+        # Adds a resource to metadata
+        #
+        # @param name        [String] Resource name
+        # @param description [String] Resource description
+        #
+        # @return [void]
         def add_resource(name, description)
           @resources[name.to_sym] = { description: description, paths: {} }
           @current_resource       = name.to_sym
         end
 
-        def add_entity(type, fields)
+        ##
+        # 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.#{type}",
+                         "#{@current_resource}.entities.#{name}",
                          EntityConfig.new(fields))
         end
 
-        def add_parameter(type, fields)
-          raise "Parameter #{type} is already defined" if @parameters[type]
+        ##
+        # Adds a parameter definition
+        #
+        # @param name   [Symbol] Parameter definition name
+        # @param fields [Hash]   Fields definitions
+        #
+        # @return [void]
+        def add_parameter(name, fields)
+          raise "Parameter #{name} is already defined" if @parameters[name]
 
           fields.each_value do |field|
             field[:required] = true unless field[:required] == false
           end
-          @parameters[type] = fields
+          @parameters[name] = fields
         end
 
+        ##
+        # Adds path parameters definition
+        #
+        # @param fields [Hash] Parameters definitions
+        #
+        # @return [void]
         def add_path_params(fields) # rubocop:disable Metrics/MethodLength
           check_current_context :resource, :url
 
@@ -60,6 +88,9 @@ module RSpec
           end
         end
 
+        ##
+        # Add request parameters (_body_)
+        #
         # Fields should be something like:
         #   id:   {type: :number, description: 'Something'},
         #   name: {type: string, description: 'Something'}
@@ -69,6 +100,10 @@ module RSpec
         #     property: {type: :string, description: 'Something'},
         #     ...
         #   }}
+        #
+        # @param fields [Hash] Parameters definitions
+        #
+        # @return [void]
         def add_request_params(fields)
           check_current_context :resource, :url, :method
 
@@ -78,11 +113,21 @@ module RSpec
                          params)
         end
 
-        def add_action(method, url, description)
+        ##
+        # Adds an action and sets `@current_url` and `@current_method`
+        #
+        # @param method      [:get, :post, :put, :patch, delete] Method name
+        # @param url         [String]                            Associated URL
+        # @param summary     [String]                            What the route does for given method
+        # @param description [String]                            Longer description of this action
+        #
+        # @return [void]
+        def add_action(method, url, summary, description = '')
           check_current_context :resource
 
           Utils.deep_set(@resources, "#{@current_resource}.paths.#{url}.actions.#{method}",
-                         description: description,
+                         description: description || '',
+                         summary:     summary,
                          statuses:    {},
                          params:      {})
 
@@ -90,6 +135,14 @@ module RSpec
           @current_method = method
         end
 
+        ##
+        # Adds a status code to metadata and sets `@current_code`
+        #
+        # @param status_code [Integer] The status code
+        # @param description [String]  Code description
+        #
+        # @return [void]
+        #
         # rubocop:disable Layout/LineLength
         def add_status_code(status_code, description)
           check_current_context :resource, :url, :method
@@ -102,6 +155,49 @@ module RSpec
         end
         # rubocop:enable Layout/LineLength
 
+        ##
+        # Gets the current example
+        #
+        # @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
+        end
+
+        ##
+        # Adds expectations for current example
+        #
+        # @param one [Hash, nil] Entity definition
+        # @param many [Hash, nil] Entity definition
+        #
+        # @return [void]
+        def add_expectations(one, many)
+          check_current_context :resource, :url, :method, :code
+          none = !many && !one
+
+          # rubocop:disable Layout/LineLength
+          Utils.deep_set(@resources,
+                         "#{@current_resource}.paths.#{@current_url}.actions.#{@current_method}.statuses.#{@current_code}.expectations",
+                         {
+                           one:  one,
+                           many: many,
+                           none: none,
+                         })
+          # rubocop:enable Layout/LineLength
+        end
+
+        ##
+        # Adds a request example
+        #
+        # @param url         [String, nil]  Visited URL
+        # @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 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
@@ -119,6 +215,8 @@ module RSpec
         end
         # rubocop:enable Metrics/ParameterLists
 
+        ##
+        # @return [Hash] Hash representation of the metadata
         def to_h
           {
             resources: @resources,
@@ -128,6 +226,13 @@ module RSpec
 
         private
 
+        ##
+        # Checks for the definition of given scopes.
+        # This is useful to verify if all metadata is set for the current example
+        #
+        # @param scope [Symbol[]] List of scope to check for
+        #
+        # @return [Boolean]
         def check_current_context(*scope) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           scope ||= []
           raise 'No resource declared' if scope.include?(:resource) && !@current_resource
@@ -136,6 +241,13 @@ module RSpec
           raise 'No status code declared' if scope.include?(:code) && !@current_code
         end
 
+        ##
+        # Checks if a given parameter is used in the URL (_path_) or querystring (query)
+        #
+        # @param url_chunks [String[]] Chunks of an url splitted on the query separator (`?`)
+        # @param name       [Symbol]   Name of the parameter
+        #
+        # @return [:path, :query]
         def path_param_scope(url_chunks, name)
           if /:#{name}/.match?(url_chunks[0])
             :path
@@ -146,6 +258,12 @@ module RSpec
           end
         end
 
+        ##
+        # Checks and complete a field definition
+        #
+        # @param fields [Hash] Fields definitions
+        #
+        # @return [Hash] Completed field definition
         def organize_params(fields) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
           out      = { properties: {} }
           required = []
@@ -154,7 +272,7 @@ module RSpec
             allowed_type = allowed_types.include?(field[:type]) || PARAM_TYPES.key?(field[:type])
             raise "Field type not allowed: #{field[:type]}" unless allowed_type
 
-            required.push name.to_s if field[:required]
+            required.push name.to_s if field[:required] != false
 
             out[:properties][name] = fill_request_param field
           end
@@ -162,9 +280,15 @@ module RSpec
           out
         end
 
+        ##
+        # Checks and completes a request parameter definition
+        #
+        # @param field [Hash] Parameter definition
+        #
+        # @return [Hash] Completed parameter
         def fill_request_param(field)
-          if field[:type] == :object && field[:properties]
-            organize_params field[:properties]
+          if field[:type] == :object && field[:attributes]
+            organize_params field[:attributes]
           else
             properties = {
               type:        PARAM_TYPES[field[:type]][:type],