whisperer 0.0.1 → 0.0.2

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    NDliMDRjMTM4ZDRiMDMyZDIwMTc1Y2U1NjBiZWNjNzdhYWM2ZjY3ZQ==
-  data.tar.gz: !binary |-
-    YjQzMTBmMmMzZmIyYTQ4ZGRmZmZlM2ZiZTI1MjMwNjJmNGJkY2Q1Nw==
+SHA1:
+  metadata.gz: d6f76493d9ca390d0cfc2cd573d4b41b1c8f643d
+  data.tar.gz: b755938abe8ce6e126f3649ed6de117ce2f51527
 SHA512:
-  metadata.gz: !binary |-
-    MzllODJkNDVmYzgyZTQzYzYzZjBhMWM4YmE2NmMzOWEwOGU0YmI2ZTdmMTEw
-    YzU2Y2E2MTg2ZGI2Njc3NTQ0N2I2YTU2YmFhZDc4NzdiZDk3ZTI5ZTFkN2Ix
-    ZGU5ZjJhMzc4NDkwM2U4NDljNmUyNmU5YjY3YzY2NzZjM2M2NDE=
-  data.tar.gz: !binary |-
-    YTAwZjBlMzAwY2NmOTFlMmU1NGEwYzE4ODI3NWJmNjc0ZTIxNzNiMTAzMTNh
-    MTIxYzZiYTU4NzM2YzE5ZWZlNGFlMmIzNTIxOTYzN2U2NDNjMzIzNThmZDRm
-    N2NkZmJiZWIxMDQ5ZDdkMWEwNzI0ZThmYjg4OGFiMmM2Njg5YjI=
+  metadata.gz: 2b92b0ebeb0a4864ecc2288c25ec8208e78edd3a514f1dd7630e667e981103af499a01c015b739e1e441266adb8dccd9660a4912de5c42d2dc6ac6e8756346b8
+  data.tar.gz: f35b2ac7a411bc5d0ed4236fdb6dcbb91c5299ed2afff097fa5b74084d546b25010d90cbbc6ed7c65884d625f027f866053e7e1ef14b2e18688a879ed4a41002

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# 0.0.2
+
+  * fixed the bug with using the default values in child cassette builders when parent cassette builders overrided them.
+  * internal improvements helping in developing new features.
+  * improved documentation.
+  * added default values:
+    - `get` is a default method for a request;
+    - `200` is a default status of a response;
+    - `UTF-8` is a default encoding for a body of the request and response.
+    - `json` is a default serializer.

data/Gemfile

@@ -4,4 +4,5 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'rspec', '~> 3.1'
-gem 'rake'
+gem 'rake'
+

data/README.md

@@ -6,6 +6,13 @@
 
 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.
 
+## Features
+
+ - Describes VCR cassettes with Ruby.
+ - Describes entities for a response body of VCR cassettes with [FactoryGirl](/thoughtbot/factory_girl).
+ - Posibility to inherit VCR cassettes (actually cassette builders describing VCR cassettes, but the effect is the same).
+ - Serializers to serialize a response body to a format supported by your API.
+
 ## Installation
 
 **Requirments**:
@@ -29,7 +36,7 @@ To create default directories' structure and the config file with default option
 
 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:
+If you want to create the config file only, you need to execute:
 
     $ rake whisperer:config:create
 
@@ -58,7 +65,7 @@ Whisperer.define(:arya_stark) do
 
     body do
       encoding 'UTF-8'
-      factory  'arya_stark', :json
+      factory  'arya_stark'
     end
   end
 
@@ -87,6 +94,7 @@ 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
+  serializer :json_multiple
 end
 ```
 
@@ -109,15 +117,16 @@ body do
     )
   end
 
-  raw_data factories, :json_multiple
+  raw_data factories
+  serializer :json_multiple
 end
 ```
 
-It is very useful, when you need generate dynamically instances of a factory.
+It is very useful, when you need to 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:
+If you need to generate almost the same VCR cassette, but with a bit different data, you can do it via inheritance:
 
 ```ruby
 Whisperer.define(:robb_stark, parent: :arya_stark) do
@@ -186,6 +195,8 @@ Placeholder is a simple class inheriting `OpenStruct` class:
 
 It decouples factories from your application.
 
+**Note:** If you use own models instead of `OpenStruct` objects for defining factories, you have to implement `attributes` method returning a hash with attributes for your models. Otherwise, the serializers provided by this gem will use all instance variables of your models for serializing them.
+
 ### 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:
@@ -246,13 +257,65 @@ Now, it can be used as any other serializer:
   end
 ```
 
+### Sub directories to save cassettes
+
+By default all generated cassettes are saved in one directory. It is not convenient when you have a lot of cassettes there. Therefore, there is an option to define own subpath in a cassette builder, that subpath will be used for saving a cassette:
+
+```ruby
+Whisperer.define(:robb_stark) do
+  response do
+    body do
+      factory 'robb_stark'
+    end
+  end
+
+  sub_path 'starks'
+end
+```
+
+If you don't change the path to your cassette, the cassette from the example will be saved in `spec/cassettes/vcr_cassettes/starks` directory. It helps you to structure your cassettes.
+
+### Default values of cassette builders
+
+There are attributes which you can omit and the gem will provide default values for them. All values listed in the following example are default and you can omit them:
+
+```ruby
+  Whisperer.define(:arya_stark) do
+    request do
+      method :get
+      
+      body do
+        encoding 'UTF-8'
+        string   '' 
+      end
+    end
+  
+    response do
+      status do
+        code    200
+        message 'OK'
+      end
+
+      body do
+        encoding   'UTF-8'
+        serializer :json
+      end
+    end
+  end
+```
+
+Also, there are attributes which are automatically calculated if you don't specify values for them:
+
+ - **recorded_at** - it gets a date of generating a cassette;
+ - **content_length** header of a response` - the gem calculates this value based on a response body.
+
 ### 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
+ - **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:
 
@@ -270,7 +333,7 @@ To generate cassettes based on cassette builders, you need to launch command:
 
 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
+To generate one particular cassette, you can use this command
 
     $ rake whisperer:cassettes:generate[cassette_builder]
 
@@ -284,6 +347,14 @@ Manual creation of cassette builders is painful. There is a command which can he
 
 It creates a sample for you in the directory with cassette builders, you need to edit it only.
 
+## Code examples
+
+There is a repository with [examples](https://github.com/dnesteryuk/whisperer_example) of the Whisperer gem usage. It will help you to start using it.
+
+## Resources
+
+[Introduction into Whisperer](http://nesteryuk.info/2014/11/16/whisperer-introduction.html)
+
 ## Contributing
 
 1. Fork it

data/TODO.md

@@ -1,47 +1,42 @@
-## Release 0.0.1
+## Release 0.0.3
 
-1. Add info to doc:
-  - subpath for generating cassettes
-  - factories for requests
+1. Find the way to disable altering the existing cassettes by VCR while launching tests.
+2. Add a helper method to generate a collection of factories to avoid such code:
 
-## Release 0.0.2
+  ```ruby
+      factory = FactoryGirl.build(:event)
 
-1. Think about the better way for inheriting serializes, now it looks like:
+      factories = [factory]
 
-  ```ruby
-    class Whisperer::Serializers::Base
-      # ...
-    end
+      6.times do |t|
+        i = (t + 2).to_s
 
-    class Whisperer::Serializers::Json < Whisperer::Serializers::Base
-      # ...
-    end
+        factories << FactoryGirl.build(
+          :event,
+          id: factory.id + i
+
+        )
+      end
+  ```
+which is duplicated in a few builders.
+3. Default record which will be used only for inheriting, something:
 
-    class Whisperer::Serializers::JsonMultiple < Whisperer::Serializers::Json
-      # ...
+  ```ruby
+    Whisperer.define(:default_for_my_api) do
     end
   ```
 
-  If an user wants to inherit `Whisperer::Serializers::JsonMultiple` it will look even more crazy.
+  it won't be used for generating a cassette, only for inheriting.
+4. Add DSL which will allow us to define any helper method for the body DSL. It should allow our users to extend functionality of the gem.
+5. Add DSL to define the way how we can read attributes from models which are used in factories if it is not `OpenStruct` model.
+6. `Whisperer::Serializers::Json#fetch_attrs` method should be extracted to own class since it may be useful for a custom serializers.
+7. Move the documentation to the wiki.
 
-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:
+## Release 0.1.0
 
-  ```ruby
-    Whisperer::Record.new(
-      response: {
-        headers: {
-          content_length: 10
-        }
-      }
-    )
-  ```
+1. Create rake task for generating factories based on Vcr responses.
+
+## Think about possibile features
 
-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.
+1. Do we need to expose preprocessors or may be extend their usage (unregister, apply only for a certain cassettes)?
+2. We can use factories for building request body, shold we consider this option as a real feature?

data/lib/whisperer.rb

@@ -9,81 +9,50 @@ require 'whisperer/placeholder'
 require 'whisperer/dsl'
 require 'whisperer/helpers'
 
+require 'whisperer/storage'
 require 'whisperer/generator'
+require 'whisperer/merger'
 
 require 'whisperer/convertors/hash'
 require 'whisperer/convertors/interaction'
 
+require 'whisperer/serializers'
 require 'whisperer/serializers/json'
 require 'whisperer/serializers/json_multiple'
 
 require 'whisperer/preprocessors'
+require 'whisperer/preprocessors/default_values'
 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
+    def define(*args, &block)
+      Storage.define(*args, &block)
     end
 
     def generate(name)
       name = name.to_sym
 
-      unless cassette_records[name]
-        raise NocassetteRecordError.new("There is not cassette builder with \"#{name}\" name.")
+      unless container = Storage.cassette_record(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)
+      if Storage.defined_any?
+        Storage.cassette_records.each do |name, container|
+          Generator.generate(container, name)
         end
       else
-        raise NocassetteRecordError.new('cassette builders are not found.')
+        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
+      Serializers.register(name, class_name)
     end
 
     def register_preprocessor(name, class_name)
@@ -91,12 +60,13 @@ module Whisperer
     end
   end
 
-  class NocassetteRecordError < ArgumentError; end
+  class NoCassetteRecordError < ArgumentError; end
 end
 
 
-Whisperer.register_serializer(:json, Whisperer::Serializers::Json)
+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)
+Whisperer.register_preprocessor(:default_values, Whisperer::Preprocessors::DefaultValues)
+Whisperer.register_preprocessor(:response_body,  Whisperer::Preprocessors::ResponseBody)
+Whisperer.register_preprocessor(:content_length, Whisperer::Preprocessors::ContentLength)

data/lib/whisperer/merger.rb

@@ -0,0 +1,36 @@
+module Whisperer
+  class Merger
+    extend Helpers
+
+    add_builder 'merge'
+
+    def initialize(child, parent)
+      @child, @parent = child, parent
+    end
+
+    def merge
+      merge_attrs(@parent, @child)
+    end
+
+    protected
+      def merge_attrs(source, holder)
+        source.attributes.each do |attr, val|
+          if val.respond_to?(:attributes)
+            merge_attrs(val, holder[attr])
+          else
+            # We need to make sure that such attribute is declared
+            # for a record, otherwise, it cannot be written.
+            if holder.class.attribute_set[attr].nil?
+              holder.attribute(attr, source.class.attribute_set[attr])
+            end
+
+            attr_info = holder.class.attribute_set[attr]
+
+            if holder[attr].nil? || holder[attr].respond_to?(:is_default)
+              holder[attr] = val
+            end
+          end
+        end
+      end
+  end
+end

data/lib/whisperer/preprocessors/default_values.rb

@@ -0,0 +1,22 @@
+require_relative 'base'
+
+module Whisperer
+  module Preprocessors
+    class DefaultValues < Base
+      def process
+        fill_default_vals(@record)
+      end
+
+      private
+        def fill_default_vals(holder)
+          holder.attributes.each do |attr, val|
+            if val.respond_to?(:attributes)
+              fill_default_vals(val)
+            else
+              holder[attr] = val.to_default if val.respond_to?(:is_default)
+            end
+          end
+        end
+    end # class DefaultValues
+  end # module Preprocessors
+end # module Whisperer