mock5 1.0.3 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 76be219294f80c132aa6185e6968ada828583e65
-  data.tar.gz: 57a45abc38b9aeda5e26ca5dba4b7bd574ce527f
+  metadata.gz: 5e3ff7dc93593a4f21dd450ed0874f436d1493c9
+  data.tar.gz: 1599500a3e285e92e7931b4e24ce5790d0f6bc25
 SHA512:
-  metadata.gz: 9f03b77ad3a4b76c135eaf5a0b138099350861a8340d59b465d84e869bb07f9fd0925955b1aa98a4a76fdba5ee9937641237972980b5fd7f2d121b8257514b43
-  data.tar.gz: 4b2548315b2f6f24e71a15f8c39f0c3052fe4ade33c26d8d92a80a5088c46f33b78b3e28ff99c320b168d5d554fc16e29a4a2a5cf6fcfe0194f17fbcfdf4577d
+  metadata.gz: 6e93dd71cc6c4b953de995bd642764b17298a0e24c16ea2ede62d7c56dc0f70c71ad3397d9c456c43384f74f5c0f4b5dff1c1268d7a67a85026360a3f55b0005
+  data.tar.gz: 961aa86904f8e5f6fd54007202f4f107f4301174e01a864c9d72d94e180d0c931042b068b9cd21012148daafc98972cef47bfc126a0306120ab480f97eb9b884

data/README.md

@@ -1,33 +1,88 @@
 # Mock5
-[![Gem Version](https://img.shields.io/gem/v/mock5.svg)][gem]
-[![Build Status](https://img.shields.io/travis/rwz/mock5.svg)][travis]
-[![Code Climate](https://img.shields.io/codeclimate/github/rwz/mock5.svg)][codeclimate]
-[gem]: https://rubygems.org/gems/mock5
-[travis]: http://travis-ci.org/rwz/mock5
-[codeclimate]: https://codeclimate.com/github/rwz/mock5
+[![Gem Version](https://img.shields.io/gem/v/mock5.svg)](https://rubygems.org/gems/mock5)
+[![Build Status](https://img.shields.io/travis/rwz/mock5.svg)](http://travis-ci.org/rwz/mock5)
+[![Code Climate](https://img.shields.io/codeclimate/github/rwz/mock5.svg)](https://codeclimate.com/github/rwz/mock5)
+[![Inline docs](http://inch-pages.github.io/github/rwz/mock5.svg)](http://inch-pages.github.io/github/rwz/mock5)
 
-Mock5 allows to mock external APIs with simple Sinatra Rake apps.
+Mock5 allows to mock external APIs with simple Sinatra Rack apps.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+This gem could be useful for testing, and maybe development purposes.
+Add it to the relevant groups in your Gemfile.
 
-    gem "mock5"
+```ruby
+gem "mock5", groups: [:test, :development]
+```
 
-And then execute:
+and run `bundle`.
 
-    $ bundle
+## Usage
 
-Or install it yourself as:
+### mock
+Use this method to describe API you're trying to mock.
 
-    $ gem install mock5
+```ruby
+weather_api = Mock5.mock("http://weather-api.com") do
+  get "/weather.json" do
+    MultiJson.dump(
+      location: "Philadelphia, PA",
+      temperature: "60F",
+      description: "Sunny"
+    )
+  end
+end
+```
 
-## Usage
+### mount
+Use this method to enable API mocks you've defined previously.
 
 ```ruby
+Mock5.mount weather_api, some_other_api
+Net::HTTP.get("weather-api.com", "/weather.json") # => "{\"location\":...
+```
+
+### unmount
+Unmounts passed APIs if thery were previously mounted
+
+```ruby
+Mock5.unmount some_other_api # [, and_another_api... ]
+```
+
+### mounted_apis
+This method returns a Set of all currently mounted APIs
+
+```ruby
+Mock5.mounted_apis # => { weather_api }
+Mock5.mount another_api
+Mock5.mounted_apis # => { weather_api, another_api }
+```
+
+### with_mounted
+Executes the block with all given APIs mounted, and then unmounts them.
+
+```ruby
+Mock5.mounted_apis # => { other_api }
+Mock5.with_mounted weather_api, other_api do
+  Mock5.mounted_apis # => { other_api, weather_api }
+  run_weather_api_test_suite!
+end
+Mock5.mounted_apis # => { other_api }
+```
+
+## Example
+
+Say you're writing a nice wrapper around remote user management REST API.
+You want your library to handle any unexpected situation aproppriately and
+show a relevant error message, or schedule a retry some time later.
+
+Obviously, you can't rely on a production API to test all these codepaths. You
+probably want a way to emulate all these situations locally. Enter Mock5:
+
+```ruby
+# user registers successfully
 SuccessfulRegistration = Mock5.mock("http://example.com") do
   post "/users" do
-    # emulate successful registration
     MultiJson.dump(
       first_name: "Zapp",
       last_name: "Brannigan",
@@ -36,6 +91,7 @@ SuccessfulRegistration = Mock5.mock("http://example.com") do
   end
 end
 
+# registration returns validation error
 UnsuccessfulRegistration = Mock5.mock("http://example.com") do
   post "/users" do
     halt 406, MultiJson.dump(
@@ -45,28 +101,58 @@ UnsuccessfulRegistration = Mock5.mock("http://example.com") do
   end
 end
 
-describe MyApi do
+# remote api is down for some reason
+RegistrationUnavailable = Mock5.mock("http://example.com") do
+  post "/users" do
+    halt 503, "Service Unavailable"
+  end
+end
+
+# remote api times takes long time to respond
+RegistrationTimeout = Mock5.mock("http://example.com") do
+  post "/users" do
+    sleep 15
+  end
+end
+
+describe MyApiWrapper do
   describe "successfull" do
     around do |example|
-      Mock5.with_mounted SuccessfulRegistration do
-        example.call
-      end
+      Mock5.with_mounted(SuccessfulRegistration, &example)
     end
 
     it "allows user registration" do
-      expect{ MyApi.register_user }.not_to raise_error
+      expect{ MyApiWrapper.register_user }.not_to raise_error
     end
   end
 
   describe "validation errors" do
     around do |example|
-      Mock5.with_mounted UnsuccessfulRegistration do
-        example.call
-      end
+      Mock5.with_mounted(UnsuccessfulRegistration, &example)
+    end
+
+    it "raises a valiation error" do
+      expect{ MyApiWrapper.register_user }.to raise_error(MyApiWrapper::ValidationError)
+    end
+  end
+
+  describe "service is unavailable" do
+    around do |example|
+      Mock5.with_mounted(RegistrationUnavailable, &example)
+    end
+
+    it "raises a ServiceUnavailable error" do
+      expect{ MyApiWrapper.register_user }.to raise_error(MyApiWrapper::ServiceUnavailable)
+    end
+  end
+
+  describe "timeout" do
+    around do |example|
+      Mock5.with_mounted(RegistrationTimeout, &example)
     end
 
-    it "returns errors" do
-      expect{ MyApi.register_user }.to raise_error(MyApi::ValidationError)
+    it "raises timeout error" do
+      expect{ MyApiWrapper.register_user }.to raise_error(Timeout::Error)
     end
   end
 end

data/lib/mock5.rb

@@ -2,35 +2,108 @@ require "mock5/version"
 require "mock5/api"
 require "set"
 
+# The main module of the gem, exposing all API management methods.
+# Can be included into class.
 module Mock5
   extend self
 
+  # Returns a set of currently mounted APIs
+  #
+  # @return [Set] a list of currently mounted APIs
   def mounted_apis
     @_mounted_apis ||= Set.new
   end
 
-  def mock(*args, &block)
-    Api.new(*args, &block)
+  # Generates a new API
+  #
+  # @example
+  #   my_mock_api = Mock5.mock("http://example.com") do
+  #     get "posts" do
+  #       [
+  #         {id: 1, body: "a posy body"},
+  #         {id: 2, body: "another post body"}
+  #       ].to_json
+  #     end
+  #
+  #     post "posts" do
+  #       halt 201, "The post was created successfully"
+  #     end
+  #   end
+  #
+  # @param endpoint [String] a url of the API service endpoint to mock.
+  #   Should only include hostname and schema.
+  #
+  # @yield a block to define behavior using Sinatra API
+  #
+  # @return [Mock5::Api] a mountable API object
+  def mock(endpoint=nil, &block)
+    Api.new(endpoint, &block)
   end
 
+  # Mounts given list of APIs. Returns a list of APIs that were actually
+  # mounted. The APIs that were already mounted when the method is called
+  # are not included in the return value.
+  #
+  # @param apis [Enum #to_set] a list of APIs to mount
+  #
+  # @return [Set] a list of APIs actually mounted
   def mount(*apis)
-    (apis.to_set - mounted_apis).each do |api|
+    apis.to_set.subtract(mounted_apis).each do |api|
       mounted_apis.add api
       registry.register_request_stub api.request_stub
     end
   end
 
+  # Unmount given APIs. Returns only the list of APIs that were actually
+  # unmounted. If the API wasn't mounted when the method is called, it won't be
+  # included in the return value.
+  #
+  # @param apis [Enum #to_set] a list of APIs to unmount
+  #
+  # @return [Set] a list of APIs actually unmounted
   def unmount(*apis)
-    (mounted_apis & apis).each do |api|
+    mounted_apis.intersection(apis).each do |api|
       mounted_apis.delete api
       registry.remove_request_stub api.request_stub
     end
   end
 
+  # Returns true if all given APIs are mounted. false otherwise.
+  #
+  # @param apis [Enum #to_set] a list of APIs to check
+  #
+  # @return [Boolean] true if all given APIs are mounted, false otherwise
   def mounted?(*apis)
     apis.to_set.subset?(mounted_apis)
   end
 
+  # Mounts a list of given APIs, executes block and then unmounts them back.
+  # Useful for wrapping around RSpec tests. It only unmounts APIs that were
+  # not mounted before. Any API that was mounted before the method was
+  # called remains mounted.
+  #
+  # @example
+  #   my_api = Mock5.mock("http://example.com") do
+  #     get "index.html" do
+  #       "<h1>Hello world!</h1>"
+  #     end
+  #   end
+  #
+  #   another_api = Mock5.mock("http://foobar.com") do
+  #     get "hello/:what" do
+  #       "<h1>Hello #{params["what"]}</h1>"
+  #     end
+  #   end
+  #
+  #   Mock5.with_mounted my_api, another_api do
+  #     Net::HTTP.get("example.com", "/index.html") # => "<h1>Hello world!</h1>"
+  #     Net::HTTP.get("foobar.com", "/hello/bar") # => "<h1>Hello, bar</h1>"
+  #   end
+  #
+  # @param apis [Enum #to_set] a list of APIs to mount before executing the
+  #   block
+  #
+  # @yield the block to execute with given APIs being mounted
   def with_mounted(*apis)
     mounted = mount(*apis)
     yield
@@ -38,6 +111,9 @@ module Mock5
     unmount *mounted
   end
 
+  # Unmounts all currently mounted APIs and returns them
+  #
+  # @return [Set] a list of unmounted APIs
   def unmount_all!
     unmount *mounted_apis
   end

data/lib/mock5/api.rb

@@ -3,14 +3,46 @@ require "sinatra"
 require "webmock"
 
 module Mock5
+  # A class representing an API mock
   class Api
-    attr_reader :endpoint, :app
 
+    # @return [Sinatra::Base] a Sinatra app mocking the API
+    attr_reader :app
+
+    # @return [Regexp] a regexp to match the API request urls
+    attr_reader :endpoint
+
+    # Returns an instance of +Mock5::Api+
+    #
+    # @example
+    #   my_mock_api = Mock5::Api.new("http://example.com") do
+    #     get "posts" do
+    #       [
+    #         {id: 1, body: "a posy body"},
+    #         {id: 2, body: "another post body"}
+    #       ].to_json
+    #     end
+    #
+    #     post "posts" do
+    #       halt 201, "The post was created successfully"
+    #     end
+    #   end
+    #
+    # @param endpoint [String, Regexp] a url of the API service to
+    #   endpoint to mock. Can only contain schema and hostname, path
+    #   should be empty.
+    #
+    # @yield a block passed to Sinatra to initialize an app
+    #
+    # @return [Mock5::Api]
     def initialize(endpoint=nil, &block)
       @app = Sinatra.new(&block)
       @endpoint = normalize_endpoint(endpoint)
     end
 
+    # Returns webmock request stub built with Sinatra app and enpoint url
+    #
+    # @return [WebMock::RequestStub]
     def request_stub
       @request_stub ||= WebMock::RequestStub.new(:any, endpoint).tap{ |s| s.to_rack(app) }
     end

data/lib/mock5/version.rb

@@ -1,3 +1,3 @@
 module Mock5
-  VERSION = "1.0.3".freeze
+  VERSION = "1.0.5".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mock5
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.5
 platform: ruby
 authors:
 - Pavel Pravosud
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-13 00:00:00.000000000 Z
+date: 2014-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: webmock
@@ -84,3 +84,4 @@ summary: Mock APIs using Sinatra
 test_files:
 - spec/mock5_api_spec.rb
 - spec/mock5_spec.rb
+has_rdoc: