mock_server 0.2.4 → 0.3.0

data/README.md

@@ -1,84 +1,131 @@
 # MockServer
 
-You're building a neat javascript application that consume JSON...
+__MockServer let you record interactions with Rack-apps and provide playback with advanced request matching for your tests.__
 
-So you have spec for your models and controller for your API, you do?
+[![Build Status](https://secure.travis-ci.org/unixcharles/mock_server.png?branch=master)](http://travis-ci.org/unixcharles/mock_server)
 
-And you're going to test it with something like capybara?
+MockServer is an answer from a real world problem at [Teambox](http://teambox.com) and we use it extensively for our entire acceptance test suites.
 
-... The thing is that its going to be slow, and you're testing testing all you're application logic again!
+When building javascript application that communicate with the backend over an API, you will find yourself the entire stack again and again, waiting after the database while you only want ensure that your javascript applicatin is correctly communicating with the server.
 
-MockServer allow you to record your interaction with the server and give you a way to match
-the record request with the real request. 
+Our solution was to considere our own backend as it was an external API and completely mock the interaction with the API.
 
-Its like a rack [VCR](https://github.com/myronmarston/vcr) for your own API!
+### Speed. Its fast.
 
-# Recording mode
+Run test against a completely fake server, don't hit you application stack.
 
-Create mount the rack application, in rails
+### Test isolation.
 
-    require 'mock_server/record'
-    config.middleware.use MockServer::Record, 
-      { :path => 'fixtures/records', :filename => 'uploads'
-        :routes => [ '/api/*/**', '/api/*/**' ] }
+Avoid duplicated testing. Test your API in its own test suite and let the frontend perform request against fixtures to avoid testing the entire stack (again).
 
-And you're ready to record. Run the test, build so seed by clicking around. whatever.
+MockServer is a very light solution divided in three parts.
 
-# Playback mode
+* a recording Rack middleware
+* a playback Rack middleware
+* an helper module to use inside your tests
 
-    require 'mock_server/playback'
-    config.middleware.use MockServer::Playback, 
-      { :path => 'fixtures/records' }
+# Getting started
 
-Recording your own playback? Noes, don't use the two Rack middleware at the same time.
+## Installation
 
-# Rspec
+```bash
+gem install mock_server
+```
 
-    require 'mock_server/spec/helpers'
-    RSpec.configure do |config|
-      config.include MockServer::Spec::Helpers
-    end
+## Recording mode
 
-In your spec
+Mounting the rack middleware, in rails
 
-    before :each do
+```ruby
+require 'mock_server/record'
+config.middleware.use MockServer::Record, 
+  { :path => 'fixtures/records', :filename => 'api'
+    :routes => [ '/api/*/**', '/api_v2/**' ] }
+```
 
-      # Set the filename where you store the records
-      mock_server_use_record 'uploads'
+At this point, the `MockServer::Record` middleware will record all the intraction that match the given routes into the `fixtures/records/api.yml` file.
 
-      # From now on, those path belong to MockServer.
-      #
-      # if we can't match to a record, the server return a 404 and populate the errors stack.
-      mock_server_enable_routes '**/uploads/*', '**/uploads', '**/folders'
+You can record from your test or just boot the app and click around, be creative.
 
-    end
+## Playback mode
 
-    after :each do
-      mock_server_reset!
-    end
+Once you are done recording, disable the `MockServer::Record`, and you are ready to use the `MockServer::Playback` middleware.
 
-    scenario "Some json api fun" do
-      mock_server_get('/api/2/projects')
-      mock_server_post('/api/2/projects') do |request, recorded_request|
+```ruby
+require 'mock_server/playback'
+config.middleware.use MockServer::Playback, 
+  { :path => 'fixtures/records' }
+```
 
-        # I use the should helpers because it return the method
-        # but it won't raise a failure in the test, since it happen
-        # inside a proc ouside the scenario. But It will populate the
-        # error stack if can't match anything.
+You are now ready to test.
 
-        recorded_request.body.name.should == recorded_request.body.name and
-        recorded_request.body.name.should == 'MockServer'
+## Rspec
 
-        # Its a normal detect block, so it has to return true to match
-        # the record response.
-      }
+MockServer is just two record/playback Rack middleware, but it also come with an helper module to maniplate its settings.
 
-      ... fun stuff ...
+You just need to include the module in your test.
 
-      mock_server_success_stack.should include('/api/2/projects')
-      mock_server_errors_stack.should be_empty
-    end
+For exemple, in Rspec, you could do like this:
 
-# Pull request?
+```ruby
+require 'mock_server/spec/helpers'
+RSpec.configure do |config|
+  config.include MockServer::Spec::Helpers
+end
+```
 
-Yes.
+Inside your test, basic usage exemple:
+
+```ruby
+before :each do
+
+  # Set the filename where you store the records
+  # in this exemple, it will load `fixtures/records/bootsrap.yml`
+  # and `fixtures/records/uploads.yml`
+  mock_server_use_record 'bootsrap', 'uploads'
+
+  # From now on, those path belong to MockServer.
+  # if we can't match to a record, the server return a 404 and populate the errors stack.
+  mock_server_enable_routes '**/uploads/*', '**/uploads', '**/folders'
+
+end
+
+after :each do
+  mock_server_reset!
+end
+
+scenario "Some JSON api fun" do
+  mock_server_get('/api/2/projects')
+  # If no block is given, it will return the first recorded response that
+  # match the verb and path.
+
+  # You can be more specific by using a block
+  mock_server_post('/api/2/projects') do |request, recorded_request|
+
+    recorded_request.body.name == recorded_request.body.name and
+    recorded_request.body.name == 'MockServer'
+
+    # Internally, the Playback middlware will perform a Array#detect against
+    # all the recorded request loaded from the fixture files and will
+    # return the response when it return true
+  }
+
+  # ...fun stuff... fight with selenium selectors or whatever you would normally do!
+end
+```
+
+Have a look at the [helpers](http://rubydoc.info/github/unixcharles/mock_server/master/MockServer/Spec/Helpers).
+
+## Pull request?
+
+Yes.
+
+## Documentation
+
+[rubydoc](http://rubydoc.info/github/unixcharles/mock_server/master)
+
+## Credits
+
+MockServer borrow idea of the awesome [VCR](https://github.com/myronmarston/vcr) from [Myron Marston](https://github.com/myronmarston) that does similar work with HTTP interactions to external services. Give it a look!
+
+MockServer is developped and improved for our internal use at [Teambox](http://teambox.com/). Kudos to my work mates for their insightful feedback and pull requests.

data/lib/mock_server/spec/helpers.rb

@@ -1,5 +1,5 @@
 unless defined? MockServer::Store
-  require_relative 'Store/global'
+  require 'mock_server/store/global'
 end
 
 module MockServer
@@ -7,100 +7,226 @@ module MockServer
     module Helpers
       include MockServer::Store
 
-      # Inspect
+
+      # Public: Inspect mock server options
+      #
+      # Returns a String.
       def mock_server_inspect
         mock_server_options.inspect
       end
 
-      # Configuration
+      # Public: Overwrite or initialize the list of fixtures
+      #
+      # *arguments - Filename...
+      #
+      # Examples
+      #
+      #    mock_server_use_record(:users, :comments)
+      #
       def mock_server_use_record(*arguments)
         mock_server_options_set(:record_filenames, arguments)
       end
 
+      # Public: Add fixtures to the list of fixtures
+      #
+      # *arguments - Filename...
+      #
+      # Examples
+      #
+      #    mock_server_add_record(:users, :comments)
+      #
       def mock_server_add_record(*arguments)
         config = (mock_server_options_fetch(:record_filenames, []) + arguments)
         mock_server_options_set(:record_filenames, config)
       end
 
+      # Public: Set the path of fixtures files
+      #
+      # path - Sting of the fixtures path
+      #
+      # Examples
+      #
+      #    mock_server_set_fixture_path('fixtures/records/')
+      #
       def mock_server_set_fixture_path(path)
         mock_server_options_set(:path, path)
       end
 
-      # Active path config
-      def mock_server_enable_routes(*arguments)
-        routes = mock_server_options_fetch(:routes, []) + arguments
+      # Public: Enabled MockServer on a given routes.
+      # Accept unix-directory like */** catch all.
+      #
+      # *arguments - Sting of the fixtures path
+      #
+      # Examples
+      #
+      #    mock_server_enable_routes('/api/2/**', '/api/verify')
+      #
+      def mock_server_enable_routes(*paths)
+        routes = mock_server_options_fetch(:routes, []) + paths
         mock_server_options_set(:routes, routes)
       end
 
-      def mock_server_disable_path(path)
-        routes = mock_server_options_fetch(:routes, []) - [path]
-        mock_server_options_set(:routes, routes.flatten!)
+      # Public: Disable MockServer on a given routes.
+      #
+      # *paths - Sting of the fixtures path
+      #
+      # Examples
+      #
+      #    mock_server_disable_path('/api/2/**', '/api/verify')
+      #
+      def mock_server_disable_path(*paths)
+        routes = mock_server_options_fetch(:routes, []) - paths
+        mock_server_options_set(:routes, routes.flatten)
       end
 
+      # Public: Disable all routes being server by MockServer
+      #
+      #
+      # Examples
+      #
+      #    mock_server_disable_all_routes!
+      #
       def mock_server_disable_all_routes!
         mock_server_options_set(:routes, [])
       end
 
-      # Matchers helpers
+      # Public: Register a matcher on a GET request for a given route.
+      #
+      # path    - Relative HTTP path to match
+      # &block  - Optional block for complex matching on the request
+      #
+      # Examples
+      #
+      #    mock_server_get('/api/2/account')
+      #
+      #    mock_server_get('/api/2/account') { |request, recorded_request| request.body == recorded_request.body }
+      #
       def mock_server_get(path, &block)
         mock_server_request :get, path, block
       end
 
+      # Public: Register a matcher on a POST request for a given route.
+      #
+      # path    - Relative HTTP path to match
+      # &block  - Optional block for complex matching on the request
+      #
+      # Examples
+      #
+      #    mock_server_post('/api/2/account')
+      #
+      #    mock_server_post('/api/2/account') { |request, recorded_request| request.body == recorded_request.body }
+      #
       def mock_server_post(path, &block)
         mock_server_request :post, path, block
       end
 
+      # Public: Register a matcher on a PUT request for a given route.
+      #
+      # path    - Relative HTTP path to match
+      # &block  - Optional block for complex matching on the request
+      #
+      # Examples
+      #
+      #    mock_server_put('/api/2/account')
+      #
+      #    mock_server_put('/api/2/account') { |request, recorded_request| request.body == recorded_request.body }
+      #
       def mock_server_put(path, &block)
         mock_server_request :put, path, block
       end
 
+      # Public: Register a matcher on a DELETE request for a given route.
+      #
+      # path    - Relative HTTP path to match
+      # &block  - Optional block for complex matching on the request
+      #
+      # Examples
+      #
+      #    mock_server_delete('/api/2/account')
+      #
+      #    mock_server_delete('/api/2/account') { |request, recorded_request| request.body == recorded_request.body }
+      #
       def mock_server_delete(path, &block)
         mock_server_request :delete, path, block
       end
 
+      # Public: Clear all the matchers
+      #
       def mock_server_clear_matchers!
         mock_server_options_set(:matchers, [])
       end
 
-      # Errors / Success stack
+      # Public: Retrive the MockServer request stack.
+      #
+      # Return array of request path.
       def mock_server_requests_stack
         mock_server_options_fetch(:requests_stack, [])
       end
 
+      # Public: Clear the MockServer request stack.
       def mock_server_requests_stack_clear!
          mock_server_options_set(:requests_stack, [])
       end
 
+      # Public: Retrive the MockServer request stack.
+      #
+      # Return array of request path.
       def mock_server_errors_stack
         mock_server_options_fetch(:errors_stack, [])
       end
 
+      # Public: Retrive the MockServer errors request stack.
+      # i.e.: path being register for being serve by MockServer, but
+      # no suitable matcher was found to serve the request will be
+      # added to the error stack
+      #
+      # Return array of errors.
       def mock_server_errors_stack_clear!
         mock_server_options_set(:errors_stack, [])
       end
 
+      # Public: Retrive the MockServer successful request stack.
+      #
+      # Return array of successful response stack.
       def mock_server_success_stack
         mock_server_options_fetch(:success_stack, [])
       end
 
+      # Public: Clear the MockServer successful request stack.
       def mock_server_success_stack_clear!
         mock_server_options_set(:success_stack, [])
       end
 
+      # Public: Clear the MockServer response stack.
+      #
+      # alias:
+      #
+      #   mock_server_requests_stack_clear!
+      #   mock_server_success_stack_clear!
+      #   mock_server_errors_stack_clear!
+      #
       def mock_server_response_stack_clear!
         mock_server_requests_stack_clear!
         mock_server_success_stack_clear!
         mock_server_errors_stack_clear!
       end
 
-      # Clear all the settings
-
+      # Public: Clear the MockServer state.
+      #
+      # alias:
+      #
+      #   mock_server_response_stack_clear!
+      #   mock_server_clear_matchers!
+      #   mock_server_disable_all_routes!
+      #
       def mock_server_reset!
         mock_server_response_stack_clear!
         mock_server_clear_matchers!
         mock_server_disable_all_routes!
       end
 
+      # Public: Utility helper to reraise errors catch inside the matchers block
+      #
       def mock_server_reraise_matcher_exceptions
         mock_server_options_fetch(:matcher_exceptions, []).each do |exception|
           raise exception
@@ -109,17 +235,32 @@ module MockServer
 
       protected
 
-      # Matchers helpers
+      # Internal: Register a matcher on a given route for playback
+      #
+      # method  - HTTP verb to register
+      # path    - Relative HTTP path to match
+      # matcher - Optional proc for complex matching on the request
+      #
+      # Examples
+      #
+      #    mock_server_request(:get, '/api/2/account')
+      #
+      #    mock_server_request(:get, '/api/2/account', lambda {|request, recorded_request| request.body == recorded_request.body } )
+      #
       def mock_server_request(method, path, matcher)
         add_mock_server_matcher({ :method => method, :path => path, :matcher => matcher })
       end
 
+      # Internal: Insert a matcher hash into the matchers array of the MockServer storage class.
+      #
       def add_mock_server_matcher(matcher)
         options = self.mock_server_options_read
-        options[:matchers] << matcher
+        options[:matchers].unshift(matcher)
         mock_server_options_write(options)
       end
 
+      # Internal: Fetch key from the storage class
+      #
       def mock_server_options_fetch(key, value)
         if self.mock_server_options_read[key]
           mock_server_options_get(key)
@@ -128,12 +269,16 @@ module MockServer
         end
       end
 
+      # Internal: Setter for the storage class
+      #
       def mock_server_options_set(key, value)
         hash = self.mock_server_options_read
         hash[key] = value
         self.mock_server_options_write(hash)
       end
 
+      # Internal: Getter for the storage class
+      #
       def mock_server_options_get(key)
         hash = self.mock_server_options_read
         hash[key]

metadata

@@ -1,60 +1,55 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: mock_server
-version: !ruby/object:Gem::Version 
-  hash: 31
+version: !ruby/object:Gem::Version
+  version: 0.3.0
   prerelease: 
-  segments: 
-  - 0
-  - 2
-  - 4
-  version: 0.2.4
 platform: ruby
-authors: 
+authors:
 - Charles Barbier
 - Saimon Moore
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-02-03 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-07-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rack
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: hashie
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id002
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email: unixcharles@gmail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - README.md
 - LICENSE
 - lib/mock_server.rb
@@ -66,36 +61,26 @@ files:
 - lib/mock_server/spec/helpers.rb
 homepage: http://www.github.com/unixcharles/mock_server
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Mock you're entire application
 test_files: []
-