vigia 0.0.9 → 0.1.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 929d9503715c7b1c7d98b04831cac098545caf26
-  data.tar.gz: e8cbd9941d8839d48bb8d8fc278e96f4f6fed369
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NzQzNmJmYjk4OTkzYjZmZDc0ZGQ3N2I4MTZiYjUyYmZhOTNkODExZQ==
+  data.tar.gz: !binary |-
+    ZDI3MTQ4ZWYxNDY5MjIzMjA2MGM3OWVkN2EwNzA0NDU0NDhjODY5MQ==
 SHA512:
-  metadata.gz: 3c06c22b0c3bfce8583293f22bf6e195799e13cb811b33d80532383e599b91614221a333d4fa07377cb2810961daee2ecbcf3d47505ca3a2ee5b4b5b25bdec5c
-  data.tar.gz: b4dca429249f5218810f138b3bc38fade070f4923c8e876f5aae129e1bf9664bbfa7759d142c3e3c18c8f08466d17ba0858e74a798d178b1357b4c42f1980f41
+  metadata.gz: !binary |-
+    ZGI4ZWY0MjAxZGM5YzRmYjdhYTE0MTc0NTg0NmRjZTI1ZTE3NDBjMWQ0YmE2
+    YmZmY2FhMWJhZTkzMDQ5NDU5N2U5MmE0ODAwNjhhYzk5MWRjODVmNjI0NmM0
+    NmY3ZDliMjRlNDMyOGJiZGJiMmU0NDhlNzRkNDJkMWFjMmQwYmY=
+  data.tar.gz: !binary |-
+    MzdkMDE5NjMzYmI5MGJmODY3MWQ1YWQwMDRjZDhhOWIwNzAxMWUxODVmMzQ5
+    M2ExMmVkMDI3Y2MwYzg2MWRiYWI3YTAyZDY2ZTFjMjliZTgyYmEyNmNlMmIy
+    MTlhM2I2NTc4NzM5OTY2Yzc0ZGY5ZDUyNjk1YTQ4NjVmZGY2NTU=

data/README.md

@@ -7,11 +7,11 @@ Vigia
 
 # What is it?
 
-Vigia is a gem to perform integration test within RSpec framework using a compatible
-[Api Blueprint](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md) definition file. It uses [RedSnow](https://github.com/apiaryio/redsnow) to parse the Api Blueprint file and [RestClient](https://github.com/rest-client/rest-client) as http client to perform the requests.
+<img src="http://singularities.org/vigia.png" width="96" height="96" class="right" alt="Vigia logo" />
 
-Vigia runs by default only two comparision between the blueprint file and the server response. The Http response code and the inclusion of the blueprint headers inside the headers response. But it can be easily extended through rspec shared examples
+Vigia is a gem to perform integration tests using RSpec and a compatible adapter (See [Adapters](#adapters)). The adapter creates the structure of the test (groups and context) and sets up all the variables (See [Context variables](#context-variables)) used to perform the http request.
 
+These results and expectations objects can be used to run examples that will compare the expected value with the server response value. Vigia allows to use a variety of different ways to execute these comparisons (See [Vigia Examples](#vigia-examples) and [Custom Shared Examples](#custom-shared-examples))
 
 # Installation
 
@@ -27,70 +27,229 @@ end
 
 Run bundle install
 
-```
+```bash
 $ bundle install
 ```
 
-Vigia can now be used inside your application.
+Now, Vigia can be used inside your application.
 
 # Getting started
 
-Vigia provides an easy way to configure the parameters of the test
+This example shows an easy way to start a rails server and perform you apibs test.
+
+```ruby
+# Your lib/tasks/vigia.rake
+namespace :spec do
+  desc 'Run Vigia tests'
+  task :vigia => :environment do
+
+    # start rails server by the easiest way
+    system("bundle exec rails s -e #{ Rails.env } -d")
+    # give some time to the server
+    sleep 10
+
+    Vigia.configure do |config|
+      config.source_file = "#{ Rails.root }/apibs/my_api.apib"
+      config.host        = 'http://localhost:3000'
+    end
+
+    Vigia.rspec!
+  end
+end
+```
+
+## Configuration
+
+Vigia tries to be flexible enough in case that you need to run custom operations during the tests.
 
 ```ruby
 
 Vigia.configure do |config|
 
-  # Define the Apib Blueprint Path. For example, within a Rails app
-  config.apib_path = "#{ Rails.root }/apibs/my_api.apib"
+  # Define your source file. For example, within a Rails app
+  config.source_file = "#{ Rails.root }/apibs/my_api.apib"
 
   # Define the host address where the request will be performed.
   config.host = 'http://localhost:3000'
 
-  # Include examples files within the Rspec.
-  config.custom_examples_paths = [ "#{ Rails.root }/spec/apibs" ]
+  # Include a collection of custom headers in all the requests.
+  config.headers = { authorization: 'Bearer <your hash here>' }
 
-  # Add custom examples for the apib.
-  config.add_custom_examples_on(:all, 'my custom examples')
+  # Reset rspec_config and set up documentation formatter
+  config.rspec_config do |rspec_config|
+    rspec_config.reset
+    rspec_config.formatter = RSpec::Core::Formatters::DocumentationFormatter
+  end
 
-  # Includes a collection of custom headers in all the requests.
-  config.headers = { authorization: 'Bearer <your hash here>' }
+  # Attach a before_context hook to set up the database using Databasecleaner
+  config.before_context do
+    DatabaseCleaner.start
+  end
 
+  # Set a timer on the primary group and raise an exception if the
+  # described group takes more than 5 seconds to run
+  config.before_group do
+    let!(:group_started_at) { Time.now } if described_class.options[:primary]
+  end
+
+  config.after_group do
+    if described_class.options[:primary]
+      it 'has taken less than 5 seconds to run this example' do
+        expect(Time.now.to_i - group_started_at.to_i).to be < 5
+      end
+    end
+  end
 end
 
+Vigia.rspec!
+
 ```
+For more information about config, see the `Vigia::Config` class.
+
+## Adapters
 
-## Putting all together: using a rake task to perform the tests
+By default, Vigia uses `Vigia::Adapters::Blueprint` adapter. This adapter takes an Api Blueprint compatible file and parses it using [RedSnow](https://github.com/apiaryio/redsnow). Then, it builds up the test structure accordingly.
 
-This example shows an easy way to start a rails server an perform you apibs test.
+If needed, Vigia can be configured to use a custom adapter. To do so, you just need to specify the adapter class inside the vigia configuration block:
 
 ```ruby
-# Your lib/tasks/vigia.rake
+Vigia.configure do |config|
+  config.adapter = MyBlogAdapter
+end
+```
 
-namespace :spec do
+Then, insde your adapter class, you can use the `setup_adater` method to define the groups and contexts that the adapter will provide:
 
-  desc 'Run Vigia tests'
-  task :vigia => :environment do
+```ruby
 
-    # start rails server by the easiest way
-    system("bundle exec rails s -e #{ Rails.env } -d")
-    # give some time to the server
-    sleep 10
+# Post
+class MyBlogAdapter < Vigia::Adapter
+  setup_adapter do
+    group :resource,
+      primary: true,
+      contexts: [ :default ]
+      describes: [ :post, :pages ]
+
+    context :default,
+      http_client_options: {
+        url: -> { "/#{ resource }" },
+        method: :get
+        },
+      expectations: {
+        code: 200,
+        headers: {},
+        body: -> { adapter.body_for(resource) }
+      }
+  end
 
-    Vigia.configure do |config|
-      config.apib_path = "#{ Rails.root }/apibs/my_api.apib"
-      config.host = 'http://localhost:3000'
+  def body_for(resource)
+    case resource
+    when :post
+      # Your post index expected body
+    when :pages
+      # Your pages index expected body
+    else
+      'Unknown resource. WTH!'
     end
+  end
+end
+```
 
-    Vigia.rspec!
+When vigia starts, it fetchs the first group defined as primary. For each group, Vigia will loop on each element of the describes option (`:post, :page` in this example), and will set a rspec memoized object named as the group (`let(:resource) { :post }`). Then, it will run the children (if any) and the contexts in this group, setting up the `http_client_options` and `expectations` memoized objects per context.
+
+See `Vigia::Adapters::Blueprint` class for more information about configuring and setting up an adapter.
+
+## Context Variables
+
+Vigia tries to be consistent with the way the RSpec are normally written. It creates the describe groups and context based on the adapter configuration and set up all the variables for the examples by using RSpec memoized objects.
 
+```ruby
+
+# With an adapter `ExampleAdapter` with this config
+#
+# group :resource,
+#   describes: [ :posts, :pages ],
+#   children:  [ :action ]
+#
+# group :action
+#   describes: [ :get, :post ],
+#   context:   [ :default ]
+#
+# context :default,
+#   http_client_options: {
+#     method:  -> { action.to_s.upcase }
+#     url:     -> { adapter.url_for(resource) }" }
+#     headers: :headers
+#   expectations:
+#     code: :code
+#     headers: {}
+#     body: -> { Body.for(resource} }
+#
+# Vigia will generate this RSpec code
+
+describe Vigia::RSpec do
+  let(:adapter) { ExampleAdapter.instance }
+  let(:client)  { Vigia.config.http_client_class.new(http_options) }
+  let(:result)  { client.run }
+
+  # the loop starts...
+  describe 'posts' do
+    let(:resource) { :posts }
+
+    describe 'action' do
+      let(:action) { :get }
+
+      context 'default' do
+        let(:http_client_options) { Vigia::HttpClient::Options.new(context_options) }
+        let(:expectations)        { Vigia::HttpClient::ExpectedRequest.new(expectations) }
+
+        # EXAMPLES RUN HERE!
+      end
+      # NEXT ACTION
+    end
+    # NEXT RESOURCE
   end
 end
 ```
 
-## Custom examples
+Also, It is important to mention that it is in this context where the adapter configuration will be executed. In the previous example, we configured the http_client option as follows:
+
+```ruby
+#   http_client_options: {
+#     method:  -> { action.to_s.upcase }
+#     url:     -> { adapter.url_for(resource) }" }
+#     headers: :headers
+```
+
+The option `method` is a lambda object. This object will be executed inside the RSpec memoized objects context. It is the same as doing:
+
+```ruby
+  # it has access to all context/group memoized objects
+  let(:method) { action.to_s.upcase }
+```
+
+You can also use the adapter like in option `url`, since it has been defined as a memoized object by Vigia::RSpec.
+
+Lastly, you can specify a symbol as the option value. In this case, the adapter will be the reciever of this method.
+
+## Vigia Examples
 
-Vigia allows to include custom rspec examples in the test using some options in the config
+The first way to include examples on vigia is using `register`. Option `disabled_if` can be used to prevent the example for being executed on different situations. `contexts` limits the example to the listed contexts.
+
+```ruby
+
+# On your config file, spec_helper, etc.
+Vigia::Sail::Example.register(
+  :my_custom_body_validator,
+  expectation: -> { expect { MyValidator(result.body) }.not.to raise_error } },
+  contexts:    [ :my_context ],  # default: :default
+  disable_if:  -> { ! result.headers[:content_type].include?('my_validator_mime') }
+  )
+```
+
+## Custom shared examples
+
+Vigia allows to include custom shared rspec examples in the test using some options in the config
 
 ```ruby
 
@@ -100,13 +259,8 @@ Vigia.configure do |config|
 
   # Define the custom examples you want to include in your test
 
-  # To the example in all your request use `:all` symbol
+  # To the example in all your requests use `:all` symbol
   config.add_custom_examples_on(:all, 'my custom examples')
-
-  # You can specify the name of an action or a resource. Only the requests which belong to that
-  # resource or action will run these shared examples
-  config.add_custom_examples_on('Create an Image', 'create image examples')
-
 end
 ```
 
@@ -117,29 +271,8 @@ Then, create your Rspec shared example and name the examples accordingly
 
 shared_examples 'my custom examples' do |vigia_example, response|
   it 'is a valid json response' do
-    expect { JSON.parse(result[:body]) }.not_to raise_error
+    expect { JSON.parse(result.body) }.not_to raise_error
   end
 end
 
-shared_examples 'create image examples' do |vigia_example, response|
-  before do
-    @json_result = JSON.parse(result[:body])
-    @json_expectation = JSON.parse(expectations[:body])
-  end
-
-  it 'has the expected link to the image' do |vigia_example, response|
-    expect(@json_result['image']['link']).to eql(@json_expectation['image']['link'])
-  end
-end
 ```
-
-# ToDo
-
- - [ ] Vigia::Example defines each Api Blueprint transactional example, but each example can have several responses (200, 404, etc.). Think a better way to handle this instead of passing the response variable across methods.
-
- - [ ] Spike: Do we need to set RSpec specific options? (Vigia::Rspec)
-
- - [ ] Parse http client exceptions properly. (done?)
-
- - [ ] Support custom http client through config. (low priority)
-

data/Rakefile

@@ -1,7 +1,18 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'cucumber/rake/task'
+
+Cucumber::Rake::Task.new(:cucumber) do |t|
+  t.cucumber_opts = '--tags ~@wip'
+end
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
-task :test    => :spec
+desc 'Clear tmp folders'
+task :clobber do
+  FileUtils.rm_rf(File.join(__dir__, 'coverage'))
+end
+
+# Not sure why simplecov is preventing cucumber for being run after spec
+# when running rake default
+task :default => [ :spec, :cucumber ]

data/lib/vigia/adapter.rb

@@ -0,0 +1,63 @@
+module Vigia
+  class Adapter
+
+    attr_accessor :source_file, :structure
+
+    class << self
+      def setup_adapter(&block)
+        raise 'You have to call config_adapter with a block' unless block_given?
+        @template = block
+      end
+
+      def template
+        @template
+      end
+
+      def instance
+        new.tap do |object|
+          object.source_file = Vigia.config.source_file
+          object.structure   = Structure.generate(object, @template)
+          object
+        end
+      end
+    end
+
+    class Structure
+      class << self
+        def generate(adapter, structure)
+          instance = new(adapter, structure)
+          instance.preload
+          instance
+        end
+      end
+
+      attr_reader :adapter, :groups, :contexts, :template
+
+      def initialize(adapter, template)
+        @adapter   = adapter
+        @template  = template
+        @groups    = {}
+        @contexts  = {}
+      end
+
+      def preload
+        instance_exec(&template)
+
+        Vigia::Sail::Group.collection   = groups
+        Vigia::Sail::Context.collection = contexts
+      end
+
+      def after_initialize(&block)
+        adapter.instance_exec(&block)
+      end
+
+      def group(name, options = {})
+        @groups.merge!(name => options)
+      end
+
+      def context(name, options = {})
+        @contexts.merge!(name => options)
+      end
+    end
+  end
+end

data/lib/vigia/adapters/blueprint.rb

@@ -0,0 +1,105 @@
+module Vigia
+  module Adapters
+    class Blueprint < Vigia::Adapter
+
+      attr_reader :apib
+
+      setup_adapter do
+
+        after_initialize do
+          @apib_parsed = RedSnow::parse(File.read(source_file))
+          @apib        = @apib_parsed.ast
+        end
+
+        group :resource_group,
+          primary:     true,
+          children:    [ :resource ],
+          describes:   -> { adapter.apib.resource_groups },
+          description: -> { "Resource Group: #{ resource_group.name }" }
+
+        group :resource,
+          children:    [ :action ],
+          describes:   -> { resource_group.resources },
+          description: -> { "Resource: #{ resource.name }" }
+
+        group :action,
+          children:    [ :transactional_example ],
+          describes:   -> { resource.actions },
+          description: -> { action.method }
+
+        group :transactional_example,
+          children: [ :response ],
+          describes: -> { action.examples },
+          description: -> { "Example ##{ parent_object.examples.index(transactional_example) }" }
+
+        group :response,
+          contexts:     [ :default ],
+          describes:   -> { transactional_example.responses },
+          description: -> { "Running Response #{ response.name }" }
+
+        context :default,
+          http_client_options: {
+            headers:      -> { adapter.headers_for(resource, action, transactional_example, response) },
+            method:       -> { action.method },
+            uri_template: -> { resource.uri_template },
+            parameters:   -> { adapter.parameters_for(resource, action) },
+            payload:      -> { adapter.payload_for(transactional_example, response) if adapter.with_payload?(action) }
+          },
+          expectations: {
+            code:    -> { response.name.to_i },
+            headers: -> { adapter.headers_for(resource, action, transactional_example, response, include_payload = false) },
+            body:    -> { response.body }
+          }
+      end
+
+      def headers_for(resource, action, transactional_example, response, include_payload = true)
+        headers  = headers_for_response(resource, response)
+        headers += headers_for_payload(transactional_example, response) if with_payload?(action) && include_payload
+        compile_headers(headers)
+      end
+
+      def parameters_for(resource, action)
+        (resource.parameters.collection + action.parameters.collection).each_with_object([]) do |parameter, collection|
+          collection << { name: parameter.name, value: parameter.example_value, required: (parameter.use == :required) }
+        end
+      end
+
+      def with_payload?(action)
+        %w(POST PUT PATCH).include? action.method
+      end
+
+      def payload_for(transactional_example, response)
+        payload = get_payload(transactional_example, response)
+        payload.body
+      end
+
+      private
+
+      def compile_headers(headers)
+        headers.inject({}) do |hash, header|
+          normalize_header_name = header[:name].gsub('-', '_').downcase.to_sym
+          hash.merge!(normalize_header_name => header[:value])
+        end
+      end
+
+      def headers_for_response(resource, response)
+        collection = []
+        collection << [*resource.model.headers.collection]
+        collection << [*response.headers.collection]
+        collection.flatten
+      end
+
+      def headers_for_payload(transactional_example, response)
+        payload = get_payload(transactional_example, response)
+        [ *payload.headers.collection ].flatten
+      end
+
+      def get_payload(transactional_example, response)
+        index = transactional_example.responses.index(response)
+        transactional_example.requests.fetch(index)
+      rescue => e
+        raise "Unable to load payload for response #{ response.name }"
+      end
+    end
+  end
+end

data/lib/vigia/config.rb

@@ -1,18 +1,28 @@
 module Vigia
   class Config
-    attr_accessor :apib_path, :host, :custom_examples_paths, :custom_examples, :headers, :http_client_class
+    attr_accessor :source_file, :host, :custom_examples_paths, :custom_examples, :headers, :http_client_class
+    attr_accessor :adapter, :hooks, :rspec_config_block, :stderr, :stdout
 
     def initialize
       @host                  = nil
-      @apib_path             = nil
+      @source_file           = nil
+      @rspec_config_block    = nil
       @headers               = {}
       @custom_examples_paths = []
       @custom_examples       = []
+      @hooks                 = []
+      @stderr                = $stderr
+      @stdout                = $stdout
+      @adapter               = Vigia::Adapters::Blueprint
       @http_client_class     = Vigia::HttpClient::RestClient
     end
 
+    def apply
+      validate!
+    end
+
     def validate!
-      raise("You need to provide an apib_path") unless @apib_path
+      raise("You need to provide an source") unless source_file
       raise("You have to provide a host value in config or in the Apib") unless host
     end
 
@@ -20,27 +30,28 @@ module Vigia
       @custom_examples << { filter: filter, name: name }
     end
 
-    def host
-      @host || blueprint.metadata['host']
+    def rspec_config(&block)
+      @rspec_config_block = block
     end
 
-    def custom_examples_for(specpaib_example)
-      custom_examples.each_with_object([]) do |custom_example, collection|
-        collection << custom_example[:name] if eligible_example?(specpaib_example, custom_example[:filter])
-        collection
-      end
+    def before_group(&block)
+      store_hook(Vigia::Sail::GroupInstance, :before, block)
     end
 
-    def blueprint
-      @blueprint ||= Vigia::Blueprint.new(File.read(apib_path))
+    def after_group(&block)
+      store_hook(Vigia::Sail::GroupInstance, :after, block)
     end
 
-    private
+    def before_context(&block)
+      store_hook(Vigia::Sail::Context, :before, block)
+    end
 
-    def eligible_example?(specpaib_example, filter)
-      return true if filter == :all
+    def after_context(&block)
+      store_hook(Vigia::Sail::Context, :after, block)
+    end
 
-      [ specpaib_example.resource.name, specpaib_example.action.name ].include?(filter)
+    def store_hook(rspec_class, filter, block)
+      @hooks << { rspec_class: rspec_class, filter: filter,  block: block }
     end
   end
 end

data/lib/vigia/http_client/options.rb

@@ -0,0 +1,30 @@
+module Vigia
+  module HttpClient
+    class Options < OpenStruct
+      class << self
+        def build(context, in_let_context)
+          instance = new
+          instance.context = context
+          instance.options.each do |name, value|
+            instance[name] = context.contextual_object(object: value, context: in_let_context)
+          end
+          instance.use_uri_template       if instance.uri_template
+          instance.include_config_headers if Vigia.config.headers.any?
+          instance
+        end
+      end
+
+      def options
+        context.options[:http_client_options] || {}
+      end
+
+      def use_uri_template
+        self.url = Vigia::Url.new(uri_template).expand(parameters)
+      end
+
+      def include_config_headers
+        self.headers.merge!(Vigia.config.headers)
+      end
+    end
+  end
+end

data/lib/vigia/http_client/requests.rb

@@ -0,0 +1,10 @@
+module Vigia
+  module HttpClient
+    class RequestData < OpenStruct
+    end
+    class ExpectedRequest < RequestData
+    end
+    class ClientRequest < RequestData
+    end
+  end
+end