whisperer 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NDliMDRjMTM4ZDRiMDMyZDIwMTc1Y2U1NjBiZWNjNzdhYWM2ZjY3ZQ==
+  data.tar.gz: !binary |-
+    YjQzMTBmMmMzZmIyYTQ4ZGRmZmZlM2ZiZTI1MjMwNjJmNGJkY2Q1Nw==
+SHA512:
+  metadata.gz: !binary |-
+    MzllODJkNDVmYzgyZTQzYzYzZjBhMWM4YmE2NmMzOWEwOGU0YmI2ZTdmMTEw
+    YzU2Y2E2MTg2ZGI2Njc3NTQ0N2I2YTU2YmFhZDc4NzdiZDk3ZTI5ZTFkN2Ix
+    ZGU5ZjJhMzc4NDkwM2U4NDljNmUyNmU5YjY3YzY2NzZjM2M2NDE=
+  data.tar.gz: !binary |-
+    YTAwZjBlMzAwY2NmOTFlMmU1NGEwYzE4ODI3NWJmNjc0ZTIxNzNiMTAzMTNh
+    MTIxYzZiYTU4NzM2YzE5ZWZlNGFlMmIzNTIxOTYzN2U2NDNjMzIzNThmZDRm
+    N2NkZmJiZWIxMDQ5ZDdkMWEwNzI0ZThmYjg4OGFiMmM2Njg5YjI=

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+--profile

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+rvm:
+  - 2.1.4
+  - 2.1.3
+  - 2.1.2
+  - 2.1.1
+  - 2.1.0
+  - 2.0.0
+matrix:
+before_install:
+  - "export DISPLAY=:99.0"
+  - "sh -e /etc/init.d/xvfb start"
+script: bundle exec rspec spec

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in whisperer.gemspec
+gemspec
+
+gem 'rspec', '~> 3.1'
+gem 'rake'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Dmitriy Nesteryuk
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,293 @@
+# Whisperer
+
+[![Code Climate](https://codeclimate.com/github/dnesteryuk/whisperer/badges/gpa.svg)](https://codeclimate.com/github/dnesteryuk/whisperer)
+[![Build Status](https://secure.travis-ci.org/dnesteryuk/whisperer.png?branch=master)](https://travis-ci.org/dnesteryuk/whisperer)
+[![Dependency Status](https://gemnasium.com/dnesteryuk/whisperer.png)](https://gemnasium.com/dnesteryuk/whisperer)
+
+Do you hate fixtures? I do as well. The purpose of this library is to make your life easier when your application works with external API and you use VCR to stub that API.
+
+## Installation
+
+**Requirments**:
+ - Ruby 2.0.x or 2.1.x
+
+Add this line to your application's Gemfile:
+
+    gem 'whisperer'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install whisperer
+
+To create default directories' structure and the config file with default options, you need to execute:
+
+    $ rake whisperer:install
+
+It will create `cassette_builders` directory in your `spec` folder and `.whisperer.yml` file in your root directory of the project.
+
+If you want to create only the config file, you need to execute:
+
+    $ rake whisperer:config:create
+
+## Usage
+
+### Describing VCR cassettes
+
+VCR cassettes are described in `cassette builders`. It is Ruby DSL which repeats structure of VCR cassette:
+
+```ruby
+Whisperer.define(:arya_stark) do
+  request do
+    uri    'http://example.com/users/1'
+    method :get
+  end
+
+  response do
+    status do
+      code    200
+      message 'OK'
+    end
+
+    headers do
+      content_type 'application/json;charset=utf-8'
+    end
+
+    body do
+      encoding 'UTF-8'
+      factory  'arya_stark', :json
+    end
+  end
+
+  recorded_at 'Mon, 13 Jan 2014 21:01:47 GMT'
+end
+```
+
+But, it is Ruby, hence, we can benefit from that. Whisperer uses [FactoryGirl](/thoughtbot/factory_girl) to describe a response body. If you are not familar with FactoryGirl, please, make sure, you know how to use it bofore going on. There are a few ways how factories can be used.
+
+You can use one single factory:
+
+```ruby
+body do
+  factory 'arya_stark' # we provide only name of the factory
+end
+```
+
+`arya_stark` factory is taken to generate the response body:
+
+```
+string: '{"first_name":"Arya","last_name":"Stark","group":"member"}'
+```
+
+You can use multiple factories to generate collection for your response:
+
+```ruby
+body do
+  factories ['robb_stark', 'ned_stark'] # again we provide only names of factories
+end
+```
+
+`robb_stark` and `ned_stark` are taken to generate the response body:
+
+```
+string: '[{"first_name":"Robb","last_name":"Stark","group":"member"},{"first_name":"Ned","last_name":"Stark","group":"member"}]'
+```
+
+You can pass factory objects instead of their names:
+
+```ruby
+body do
+  factories = (1..20).to_a.map do |i|
+    factories << FactoryGirl.build(
+      :article,
+      id:      'testid' + i,
+      title:   'test name' + i,
+      body:    'desc' + i
+    )
+  end
+
+  raw_data factories, :json_multiple
+end
+```
+
+It is very useful, when you need generate dynamically instances of a factory.
+
+#### Inheritance in cassette builders
+
+If you need to generate almost the same VCR cassette, but with a bit differ data, you can do it via inheritance:
+
+```ruby
+Whisperer.define(:robb_stark, parent: :arya_stark) do
+  response do
+    body do
+      factory :robb_stark
+    end
+  end
+end
+```
+
+In this case all data is taken from `aray_stark` cassette builder, only the response body is different.
+
+You can redefine any option of VCR cassette:
+
+```ruby
+Whisperer.define(:robb_stark, parent: :arya_stark) do
+  request do
+    uri 'http://example.com/users/10'
+  end
+end
+```
+
+#### Request/Response Headers
+
+While describing headers for a request or response you can use any kind of headers, they are dynamically created:
+
+```ruby
+  headers do
+    content_length    100
+    content_type     'application/json'
+    x_requested_with 'XMLHttpRequest'
+  end
+```
+
+In a cassette it will look like:
+
+```
+  Content-Length:
+    - '100'
+  Content-Type:
+    - application/json
+  X-Requested-With
+    - XMLHttpRequest
+```
+
+#### Placeholder for FactoryGirl
+
+Since VCR is used to stub interractions with external services, there is a big chance that you don't have Ruby model to be used for defining factories. In most cases, you don't need them to generate VCR cassettes. Whisperer offers the placeholder class:
+
+```ruby
+  FactoryGirl.define do
+    factory :arya_stark, class: Placeholder do
+      first_name 'Arya'
+      last_name  'Stark'
+      group      'member'
+    end
+  end
+```
+
+Placeholder is a simple class inheriting `OpenStruct` class:
+
+```ruby
+  Placeholder = Class.new(OpenStruct)
+```
+
+It decouples factories from your application.
+
+### Serializers for a response body
+
+When an external API is subbed with VCR, API response has some format like Json, XML or any other formats. Whisperer supports possibility to convert factories into a format your external API uses. Such mechanism is provided by **serializers** which are used along with building a response body. Whisperer has only 2 serializers:
+
+ - json
+ - multiple json
+
+`Json` serializer is used for serializing one single factory:
+
+```ruby
+  response do
+    body do
+      factory    :robb_stark
+      serializer :json
+    end
+  end
+```
+
+The purpose of `json `serializer is to convert a given factory into Json format.
+
+`Multiple Json` serializer is used for serializing a collection of factories:
+
+```ruby
+body do
+  factories  ['robb_stark', 'ned_stark']
+  serializer :json_multiple
+end
+```
+
+It is very similar to `Json` serializer, but in this case it goes through the array, builds factories, serializes a received array of objects.
+
+If you need to define your own serializer, it is very easy to do. At first you need to define your own serializer class inhering `Whisperer::Serializes::Base` class:
+
+```ruby
+  class MySerializer < Whisperer::Serializers::Base
+    def serialize
+      do_something_with(@obj)
+    end
+  end
+```
+
+*Note:* `@obj` is an `OpenStruct` instance in this example.
+
+Then you need to register the new serializer:
+
+```ruby
+  Whisperer.register_serializer(:my_serializer, Serializers::MySerializer)
+```
+
+Now, it can be used as any other serializer:
+
+```ruby
+  response do
+    body do
+      factory    :robb_stark
+      serializer :my_serializer
+    end
+  end
+```
+
+### Configuration
+
+You can configure Whisperer through `.whisperer.yml` which should be created in a root directory of your project. It gives you following options:
+
+ - generate_to - the path to save generated cassettes
+ - builders_matcher - the pattern to find builders
+ - factories_matcher - the pattern to find factories
+
+Example of such file:
+
+```
+generate_to:       'spec/cassettes/vcr_cassettes/'
+builders_matcher:  './spec/cassette_builders/**/*.rb'
+factories_matcher: './spec/factories/*.rb'
+```
+
+### Generating cassettes
+
+To generate cassettes based on cassette builders, you need to launch command:
+
+    $ rake whisperer:cassettes:generate_all
+
+This command will generate new cassettes and re-generate all existing cassettes for VCR.
+
+To generate only on particular cassette, you can use this command
+
+    $ rake whisperer:cassettes:generate[cassette_builder]
+
+`cassette_builder` is a name of the cassette builder.
+
+### Generating a sample for the cassette builder
+
+Manual creation of cassette builders is painful. There is a command which can help you with that:
+
+    $ rake whisperer:cassettes:builders:sample
+
+It creates a sample for you in the directory with cassette builders, you need to edit it only.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/TODO.md

@@ -0,0 +1,47 @@
+## Release 0.0.1
+
+1. Add info to doc:
+  - subpath for generating cassettes
+  - factories for requests
+
+## Release 0.0.2
+
+1. Think about the better way for inheriting serializes, now it looks like:
+
+  ```ruby
+    class Whisperer::Serializers::Base
+      # ...
+    end
+
+    class Whisperer::Serializers::Json < Whisperer::Serializers::Base
+      # ...
+    end
+
+    class Whisperer::Serializers::JsonMultiple < Whisperer::Serializers::Json
+      # ...
+    end
+  ```
+
+  If an user wants to inherit `Whisperer::Serializers::JsonMultiple` it will look even more crazy.
+
+2. In most cases if we have a serializer for one single factory, we need a serializer for multiple factories. We need to write code which will create a multiple serializer automatically.
+3. The Whisperer::Config.load method is too complex.
+4. Create rake task for generating factories based on Vcr responses.
+5. Try to find better way for defining dynamic attributes for headers, it doesn't work when you write:
+
+  ```ruby
+    Whisperer::Record.new(
+      response: {
+        headers: {
+          content_length: 10
+        }
+      }
+    )
+  ```
+
+6. Refactore Whisperer::Record#merge_attrs! method, it should be moved to some another class
+7. Refactore Whisperer.define method, it is another responsibility which should not leave in this module.
+8. Think about the issue with touching Whisperer::cassette_records, it is not ok
+9. `Whisperer::generate` and `Whisperer::generate_all` receive cassette records twice. Also, it is needless to check existence of a cassette record if it is passed from `generate_all` to `generate`.
+10. Serializers must be stored similar to preprocessors (in the own module/class).
+11. Check whether we can use a real model instead of OpenStruct while describing factories.

data/lib/whisperer.rb

@@ -0,0 +1,102 @@
+require 'whisperer/version'
+
+require 'virtus'
+require 'vcr'
+
+require 'whisperer/config'
+
+require 'whisperer/placeholder'
+require 'whisperer/dsl'
+require 'whisperer/helpers'
+
+require 'whisperer/generator'
+
+require 'whisperer/convertors/hash'
+require 'whisperer/convertors/interaction'
+
+require 'whisperer/serializers/json'
+require 'whisperer/serializers/json_multiple'
+
+require 'whisperer/preprocessors'
+require 'whisperer/preprocessors/content_length'
+require 'whisperer/preprocessors/response_body'
+
+module Whisperer
+  @cassette_records = ThreadSafe::Hash.new
+  @serializers      = ThreadSafe::Hash.new
+
+  class << self
+    attr_reader :cassette_records
+    attr_reader :serializers
+
+    def define(name, options = {}, &block)
+      dsl = Dsl.build
+      dsl.instance_eval &block
+      record = dsl.container
+
+      if options[:parent]
+        original_record = cassette_records[options[:parent]]
+
+        if original_record.nil?
+          raise ArgumentError.new("Parent record \"#{options[:parent]}\" is not declared.")
+        else
+          record.merge!(original_record)
+        end
+      end
+
+      cassette_records[name.to_sym] = record
+    end
+
+    # Returns true if at least one factory is defined, otherwise returns false.
+    def defined_any?
+      cassette_records.size > 0
+    end
+
+    def generate(name)
+      name = name.to_sym
+
+      unless cassette_records[name]
+        raise NocassetteRecordError.new("There is not cassette builder with \"#{name}\" name.")
+      end
+
+      container = cassette_records[name]
+
+      Generator.generate(container, name)
+    end
+
+    def generate_all
+      if defined_any?
+        cassette_records.each do |name, container|
+          generate(name)
+        end
+      else
+        raise NocassetteRecordError.new('cassette builders are not found.')
+      end
+    end
+
+    def serializer(name)
+      unless serializers[name]
+        raise ArgumentError.new("There is not serializer registered with \"#{name}\" name")
+      end
+
+      serializers[name]
+    end
+
+    def register_serializer(name, class_name)
+      serializers[name] = class_name
+    end
+
+    def register_preprocessor(name, class_name)
+      Preprocessors.register(name, class_name)
+    end
+  end
+
+  class NocassetteRecordError < ArgumentError; end
+end
+
+
+Whisperer.register_serializer(:json, Whisperer::Serializers::Json)
+Whisperer.register_serializer(:json_multiple, Whisperer::Serializers::JsonMultiple)
+
+Whisperer::register_preprocessor(:response_body, Whisperer::Preprocessors::ResponseBody)
+Whisperer::register_preprocessor(:content_length, Whisperer::Preprocessors::ContentLength)