rspec-rails-api 0.1.0

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'rspec_rails_api'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/commented.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'acceptance_helper'
+
+RSpec.describe 'Categories', type: :acceptance do
+  # Needed to initialize documentation for this type of request.
+  # It should come before all the other calls (it will let the metadata
+  # class know which resource we're dealing with)
+  resource 'Categories', 'Manage categories in a group'
+
+  # Define an entity that can be returned by an URL.
+  entity :category,
+         id:         { type: :integer, description: 'The id' },
+         name:       { type: :string, description: 'The name' },
+         group_id:   { type: :number, description: 'Concerned group' },
+         created_at: { type: :datetime, description: 'Creation date' },
+         updated_at: { type: :datetime, description: 'Modification date' },
+         url:        { type: :string, description: 'URL to this category' }
+
+  entity :error,
+         error: { type: :string, name: 'The error' }
+
+  entity :form_error,
+         errors: {
+           type: :object, description: 'Form errors', attributes: {
+             name:  { type: :array, description: 'Name errors' },
+             group: { type: :array, description: 'Group errors' },
+           }
+         }
+
+  # Some vars to use in the tests
+  let(:current_user) { FactoryBot.create :user_active }
+
+  let(:group) { current_user.groups.first }
+  let(:group_id) { group.id }
+  let(:category) { FactoryBot.create :category, user: current_user, group: group }
+
+  # Declare a path accessed with a given method
+  # Their values can be declared with a  "let(:var){ value }" statement,
+  # or passed to "visit" method (see "for_code 404")
+  on_get '/api/groups/:group_id/categories', 'Categories defined in the given group' do
+    # Declare path parameters for documentation
+    path_params group_id: { type: :integer, description: 'Target group identifier' }
+
+    # Expectations for the given HTTP status
+    for_code 200, 'Success' do |example|
+      FactoryBot.create_list :category, 2, user: current_user, group: group
+
+      # This method is not built-in; check: ../README.md
+      sign_in current_user
+
+      # Actually visit the path. It will expect the given code and a
+      # content of type "application/JSON" (except for 204: no content
+      # statuses)
+      visit example
+
+      # Custom matcher: have_many will expect a body with an array of
+      # the given entity. All entries in the response will have its keys
+      # checked (not the content type).
+      # The `defined` method will get the correct entity for comparison
+      expect(response).to have_many defined :category
+
+      # Other expectations
+      expect(JSON.parse(response.body).count).to eq 2
+    end
+
+    for_code 404, 'Not found (not owned)' do |example|
+      sign_in current_user
+
+      group_id = FactoryBot.create(:user_active).groups.first.id
+
+      visit example, path_params: { group_id: group_id }
+      expect(response).to have_one defined :error
+    end
+
+    for_code 401, 'Not authorized' do |example|
+      visit example
+      expect(response).to have_one defined :error
+    end
+  end
+
+  on_get '/api/groups/:group_id/categories/:id', 'Get category' do
+    path_params group_id: { type: :integer, description: 'Target group identifier' },
+                id:       { type: :integer, description: 'Category id' }
+
+    let(:id) { category.id }
+
+    for_code 200, 'Success' do |example|
+      sign_in current_user
+
+      visit example
+      expect(response).to have_one defined :category
+    end
+
+    for_code 401, 'Not authorized' do |example|
+      visit example
+      expect(response).to have_one defined :error
+    end
+
+    for_code 404, 'Not found' do |example|
+      sign_in current_user
+
+      visit example, path_params: { id: 0 }
+      expect(response).to have_one defined :error
+    end
+  end
+
+  on_post '/api/groups/:group_id/categories', 'Creates a category' do
+    path_params group_id: { type: :integer, description: 'Target group identifier' }
+
+    request_params category: {
+      type: :object, required: true, attributes: {
+        name: { type: :string, required: true, description: 'The name' },
+      }
+    }
+
+    let(:id) { category.id }
+
+    for_code 201, 'Success' do |example|
+      sign_in current_user
+
+      visit example, payload: { category: { name: 'New category' } }
+      expect(response).to have_one defined :category
+    end
+
+    for_code 422, 'Form error' do |example|
+      sign_in current_user
+
+      visit example, payload: { category: {} }
+      expect(response).to have_one defined :form_error
+    end
+  end
+
+  on_put '/api/groups/:group_id/categories/:id', 'Updates a category' do
+    path_params group_id: { type: :integer, description: 'Target group identifier' },
+                id:       { type: :integer, description: 'Category id' }
+
+    let(:id) { category.id }
+
+    request_params category: {
+      type: :object, required: true, description: 'New category attributes', attributes: {
+        name: { type: :string, required: false, description: 'The new name' },
+      }
+    }
+
+    for_code 200, 'Success' do |example|
+      sign_in current_user
+
+      visit example, payload: { category: { name: 'New name' } }
+      expect(response).to have_one defined :category
+    end
+  end
+
+  on_delete '/api/groups/:group_id/categories/:id', 'Deletes a category' do
+    path_params group_id: { type: :integer, description: 'Target group identifier' },
+                id:       { type: :integer, description: 'Category id' }
+
+    let(:id) { category.id }
+
+    for_code 204, 'Success' do |example|
+      sign_in current_user
+
+      visit example
+      # Not checking content for 204 responses
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Rails
+    module Api
+      module DSL
+        # These methods will be available in examples (i.e.: 'for_code')
+        module Example
+          def visit(example, path_params: {}, payload: {}) # rubocop:disable Metrics/AbcSize
+            raise 'Missing context. Call visit with for_code context.' unless example
+
+            status_code    = prepare_status_code example.class.description
+            request_params = prepare_request_params example.class.parent.description, path_params, payload
+
+            send(request_params[:action],
+                 request_params[:url],
+                 params:  request_params[:params].to_json,
+                 headers: request_params[:headers])
+
+            check_response(response, status_code)
+
+            set_request_example example.class.metadata[:rrad], request_params, status_code, response.body
+          end
+
+          def defined(entity)
+            current_resource = self.class.metadata[:rrad].current_resource
+            raise '@current_resource is unset' unless current_resource
+
+            entities = self.class.metadata[:rrad].resources[current_resource][:entities]
+
+            out = entities[entity]
+            raise "Unkown entity '#{entity}' in resource '#{current_resource}'" unless out
+
+            out.expand_with(entities)
+          end
+
+          private
+
+          def check_response(response, expected_code)
+            expect(response.status).to eq expected_code
+            expect(response.headers['Content-Type']).to eq 'application/json; charset=utf-8' if expected_code != 204
+          end
+
+          def set_request_example(rrad_metadata, request_params, status_code = nil, response = nil)
+            rrad_metadata.add_request_example(url:         request_params[:example_url],
+                                              action:      request_params[:action],
+                                              status_code: status_code,
+                                              response:    response,
+                                              path_params: request_params[:path_params],
+                                              params:      request_params[:params])
+          end
+
+          def prepare_request_params(description, request_params = {}, payload = {})
+            example_params = description.split ' '
+
+            {
+              action:      example_params[0].downcase,
+              url:         prepare_request_url(example_params[1], request_params),
+              example_url: example_params[1],
+              params:      payload,
+              headers:     prepare_request_headers,
+            }
+          end
+
+          # Replace path params by values
+          def prepare_request_url(url, request_params)
+            url.gsub(/(?::(\w*))/) do |e|
+              symbol = e.sub(':', '').to_sym
+              if request_params.key?(symbol)
+                request_params[symbol]
+              elsif respond_to?(symbol)
+                send(symbol)
+              else
+                puts "! Define #{symbol} (let(:#{symbol}){ value }) or pass it to 'visit'"
+              end
+            end
+          end
+
+          def prepare_request_headers
+            {
+              'Accept'       => 'application/json',
+              'Content-Type' => 'application/json',
+            }
+          end
+
+          def prepare_status_code(description)
+            code_match = /-> (\d+) - .*/.match description
+
+            raise 'Please provide a numerical code for the "for_code" block' unless code_match
+
+            code_match[1].to_i
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'rspec/rails/api/metadata'
+
+module RSpec
+  module Rails
+    module Api
+      module DSL
+        # 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.
+          def resource(name, description = '')
+            metadata[:rrad] ||= Metadata.new
+            metadata[:rrad].add_resource name, description
+          end
+
+          # Used to describe an entity
+          def entity(type, fields)
+            metadata[:rrad].add_entity type, fields
+          end
+
+          # Used to describe query parameters
+          def path_params(fields)
+            metadata[:rrad].add_path_params fields
+          end
+
+          def request_params(fields)
+            metadata[:rrad].add_request_params fields
+          end
+
+          def on_get(url, description = nil, &block)
+            on_action(:get, url, description, &block)
+          end
+
+          def on_post(url, description = nil, &block)
+            on_action(:post, url, description, &block)
+          end
+
+          def on_put(url, description = nil, &block)
+            on_action(:put, url, description, &block)
+          end
+
+          def on_patch(url, description = nil, &block)
+            on_action(:patch, url, description, &block)
+          end
+
+          def on_delete(url, description = nil, &block)
+            on_action(:delete, url, 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, doc_only: false, &block)
+            metadata[:rrad].add_status_code(status_code, description)
+
+            describe "-> #{status_code} - #{description}" do
+              if (!ENV['DOC_ONLY'] || ENV['DOC_ONLY'] == 'false' || !doc_only) && block
+                example 'Test and create documentation', caller: block.send(:caller) do
+                  instance_eval(&block) if block_given?
+                end
+              else
+                document_only status_code
+              end
+            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.parent.description
+
+              set_request_example parent_example.metadata[:rrad], request_params, status_code
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+RSpec::Core::ExampleGroup.extend(RSpec::Rails::Api::DSL::ExampleGroup)

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'rspec/rails/api/field_config'
+
+module RSpec
+  module Rails
+    module Api
+      # Represents an entity configuration.
+      # Basically, entities configuration only have a collection of fields
+      # and a method to serialize them for comparison with actual content
+      class EntityConfig
+        attr_accessor :fields
+
+        def initialize(fields)
+          @fields = {}
+          fields.each_key do |name|
+            @fields[name] = FieldConfig.new fields[name]
+          end
+        end
+
+        def to_h
+          out = {}
+          @fields.each_key do |key|
+            out[key] = @fields[key].to_h
+          end
+          out
+        end
+
+        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]
+
+            hash[field][:attributes] = entities[attributes].expand_with(entities)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'rspec/rails/api/entity_config'
+require 'rspec/rails/api/utils'
+
+module RSpec
+  module Rails
+    module Api
+      # Represents an entity field configuration.
+      # A field have some options and a method to serialize itself.
+      class FieldConfig
+        attr_accessor :required, :type, :attributes, :description
+
+        def initialize(type:, required: true, description:, attributes: nil, of: nil)
+          @required    = required
+          @description = description
+          raise "Field type not allowed: '#{type}'" unless Utils.check_attribute_type(type)
+
+          define_attributes attributes if type == :object
+          define_attributes of if type == :array
+
+          @type = type
+        end
+
+        def to_h
+          out               = { required: @required, type: @type }
+          out[:description] = @description unless @description.nil?
+
+          if %i[object array].include?(@type) && @attributes
+            out[:attributes] = if @attributes.is_a? EntityConfig
+                                 @attributes.to_h
+                               elsif attributes.is_a? Symbol
+                                 @attributes
+                               end
+          end
+
+          out
+        end
+
+        private
+
+        def define_attributes(attributes)
+          @attributes = if attributes.is_a? Hash
+                          @attributes = EntityConfig.new attributes
+                        elsif attributes.is_a? Symbol
+                          attributes
+                        end
+        end
+      end
+    end
+  end
+end