protobuf-rspec 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.yardoc
+doc

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in protobuf-rspec.gemspec
+gemspec

data/README.md

@@ -0,0 +1,115 @@
+protobuf-rspec gem
+==================
+
+RSpec Helpers designed to give you mock abstraction of client or service layer. Require as protobuf/rspec/helpers and include into your running RSpec configuration.
+
+**Note:** Tested to work with the [protobuf gem](https://rubygems.org/gems/protobuf) (>= 1.0).
+
+Mocking Client Requests (Outside-In test of the service methods)
+----------------------------------------------------------------
+
+Use this method to call a local service in your application to test responses and behavior based on the given request. This should be used to outside-in test a local RPC Service without testing the underlying socket implementation or needing actual client code to invoke the method(s) under test.
+
+Given the service implementation below:
+
+```ruby
+module Proto
+  class UserService < Protobuf::Rpc::Service
+    def create
+      user = User.create_from_proto(request)
+      self.response = ProtoRepresenter.new(user).to_proto
+    end
+  end
+end
+```
+
+This could be one way to test the implementation while ignoring the RPC backend:
+
+
+```ruby
+describe Proto::UserService do
+  describe '#create' do
+    it 'creates a new user' do
+      create_request = Proto::UserCreate.new(...)
+      client = call_local_service(Proto::UserService, :create, create_request)
+      client.response.should eq(some_response_object)
+    end
+  end
+end
+```
+
+Mocking Service Responses
+-------------------------
+
+Create a mock service that responds in the way you are expecting to aid in testing client -> service calls. In order to test your success callback you should provide a :response object. Similarly, to test your failure callback you should provide an :error object. If you would like to test the object that is given as a request you should provide a :request object.
+
+### Testing the client on_success callback
+```ruby
+  # Method under test
+  def create_user(request)
+    status = 'unknown'
+    Proto::UserService.client.create(request) do |c|
+      c.on_success do |response|
+        status = response.status
+      end
+    end
+    status
+  end
+  ...
+  
+  # spec
+  it 'verifies the on_success method behaves correctly' do
+    mock_remote_service(Proto::UserService, :client, response: mock('response_mock', status: 'success'))
+    create_user(request).should eq('success')
+  end
+```
+
+### Testing the client on_failure callback
+```ruby
+# Method under test
+def create_user(request)
+  status = nil
+  Proto::UserService.client.create(request) do |c|
+    c.on_failure do |error|
+      status = 'error'
+      ErrorReporter.report(error.message)
+    end
+  end
+  status
+end
+...
+
+# spec
+it 'verifies the on_success method behaves correctly' do
+  mock_remote_service(Proto::UserService, :client, error: mock('error_mock', message: 'this is an error message'))
+  ErrorReporter.should_receive(:report).with('this is an error message')
+  create_user(request).should eq('error')
+end
+```
+
+### Testing the given client request object
+```ruby
+# Method under test
+def create_user
+  request = ... # some operation to build a request on state
+  Proto::UserService.client.create(request) do |c|
+    ...
+  end
+end
+...
+
+# spec
+it 'verifies the request is built correctly' do
+  expected_request = ... # some expectation
+  mock_remote_service(Proto::UserService, :client, request: expected_request)
+  create_user(request)
+end
+```
+
+Feedback
+
+Feedback and comments are welcome:
+
+Web: [rand9.com](http://rand9.com)
+Twitter: [@localshred](https://twitter.com/localshred)
+Github: [github](https://github.com/localshred)

data/Rakefile

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

data/lib/protobuf/rspec.rb

@@ -0,0 +1,2 @@
+require 'protobuf/rspec/version'
+require 'protobuf/rspec/helpers'

data/lib/protobuf/rspec/helpers.rb

@@ -0,0 +1,197 @@
+require 'protobuf/rpc/rpc.pb'
+
+# RSpec Helpers designed to give you mock abstraction of client or service layer.
+# Require as protobuf/rspec/helpers and include into your running RSpec configuration.
+#
+# @example Configure RSpec to use Protobuf Helpers
+#     require 'protobuf/rspec'
+#     RSpec.configure do |config|
+#       config.include Protobuf::Rspec::Helpers
+#     end
+module Protobuf
+  module RSpec
+    module Helpers
+
+      ClientMock = Struct.new("ClientMock", :request, :response, :error)
+
+      # Call a local service to test responses and behavior based on the given request.
+      # Should use to outside-in test a local RPC Service without testing the underlying socket implementation.
+      # 
+      # @example Test a local service method
+      #     # Implementation
+      #     module Proto
+      #       class UserService < Protobuf::Rpc::Service
+      #         def create
+      #           user = User.create_from_proto(request)
+      #           self.response = ProtoRepresenter.new(user).to_proto
+      #         end
+      #       end
+      #     end
+      # 
+      #     # Spec
+      #     describe Proto::UserService do
+      #       describe '#create' do
+      #         it 'creates a new user' do
+      #           create_request = Proto::UserCreate.new(...)
+      #           client = call_local_service(Proto::UserService, :create, create_request)
+      #           client.response.should eq(some_response_object)
+      #         end
+      #       end
+      #     end
+      #
+      # @param [Class] klass the service class constant
+      # @param [Symbol, String] method a symbol or string denoting the method to call
+      # @param [Protobuf::Message] request the request message of the expected type for the given method
+      # @param [Fixnum] timeout force timeout on service call
+      # @return [ClientMock] an object which contains the request and potential response or error objects
+      def call_local_service(klass, method, request, timeout=5)
+        service = klass.new
+        response = service.rpcs[method].response_type.new
+        service.stub(:request).and_return(request)
+        service.stub(:response).and_return(response)
+        def service.response= res
+          @response = res
+          self.stub(:response).and_return(@response)
+        end
+        def service.rpc_failed message
+          @custom_error = message
+          send_response
+        end
+        def service.send_response
+          @send_response_called = true
+        end
+
+        client_mock = ClientMock.new
+        client_mock.request = request
+
+        begin
+          yield(service) if block_given?
+          service.__send__("rpc_#{method}")
+        rescue
+          client_mock.error = $!
+        else
+          client_mock.error = service.instance_variable_get(:@custom_error)
+        ensure
+          if client_mock.error.nil?
+            if service.instance_variable_get(:@async_responder)
+              Timeout.timeout(timeout) do
+                sleep 0.5 until service.instance_variable_get(:@send_response_called)
+              end
+            end
+            client_mock.response = service.instance_variable_get(:@response) || response
+          end
+        end
+
+        client_mock
+      end
+      alias :call_service :call_local_service
+
+      # Create a mock service that responds in the way you are expecting to aid in testing client -> service calls.
+      # In order to test your success callback you should provide a :response object. Similarly, to test your failure
+      # callback you should provide an :error object. If you would like to test the object that is given as a request
+      # you should provide a :request object.
+      #
+      # @example Testing the client on_success callback
+      #     # Method under test
+      #     def create_user(request)
+      #       status = 'unknown'
+      #       Proto::UserService.client.create(request) do |c|
+      #         c.on_success do |response|
+      #           status = response.status
+      #         end
+      #       end
+      #       status
+      #     end
+      #     ...
+      #     
+      #     # spec
+      #     it 'verifies the on_success method behaves correctly' do
+      #       mock_remote_service(Proto::UserService, :client, response: mock('response_mock', status: 'success'))
+      #       create_user(request).should eq('success')
+      #     end
+      #
+      # @example Testing the client on_failure callback
+      #     # Method under test
+      #     def create_user(request)
+      #       status = nil
+      #       Proto::UserService.client.create(request) do |c|
+      #         c.on_failure do |error|
+      #           status = 'error'
+      #           ErrorReporter.report(error.message)
+      #         end
+      #       end
+      #       status
+      #     end
+      #     ...
+      #     
+      #     # spec
+      #     it 'verifies the on_success method behaves correctly' do
+      #       mock_remote_service(Proto::UserService, :client, error: mock('error_mock', message: 'this is an error message'))
+      #       ErrorReporter.should_receive(:report).with('this is an error message')
+      #       create_user(request).should eq('error')
+      #     end
+      #
+      # @example Testing the given client request object
+      #     # Method under test
+      #     def create_user
+      #       request = ... # some operation to build a request on state
+      #       Proto::UserService.client.create(request) do |c|
+      #         ...
+      #       end
+      #     end
+      #     ...
+      #     
+      #     # spec
+      #     it 'verifies the request is built correctly' do
+      #       expected_request = ... # some expectation
+      #       mock_remote_service(Proto::UserService, :client, request: expected_request)
+      #       create_user(request)
+      #     end
+      #     
+      # @param [Class] klass the service class constant
+      # @param [Symbol, String] method a symbol or string denoting the method to call
+      # @param [Hash] cb_mocks provides expectation objects to invoke on_success (with :response), on_failure (with :error), and the request object (:request)
+      # @return [Mock] the stubbed out client mock
+      def mock_remote_service(klass, method, cb_mocks={})
+        cb_mocks = {:error => mock('error', :message => nil, :code => nil)}.merge(cb_mocks)
+        klass.stub(:client).and_return(client = mock('Client'))
+        client.stub(method).and_yield(client)
+        if cb_mocks[:request]
+          client.should_receive(method).with(cb_mocks[:request])
+        else
+          client.should_receive(method)
+        end
+
+        if cb_mocks[:response]
+          client.stub(:on_success).and_yield(cb_mocks[:response])
+        else
+          client.stub(:on_success)
+        end
+
+        if cb_mocks[:error]
+          client.stub(:on_failure).and_yield(cb_mocks[:error])
+        else
+          client.stub(:on_failure)
+        end
+        client
+      end
+      alias :mock_service :mock_remote_service
+
+      # Stubs out a protobuf message object internals so that we can just test the needed fields.
+      # It's debatable if this is actually helpful since the protobuf message is so lean in the first place.
+      # 
+      # @param [Class, String] klass the message class constant or the message name
+      # @param [Hash] stubs the stubbed fields and values
+      # @return [OpenStruct] the mocked message
+      def mock_proto(klass, stubs={})
+        proto_instance = OpenStruct.new({:mock_name => klass}.merge(stubs))
+        proto_instance.stub!(:has_field? => true)
+        proto = mock(klass)
+        proto.stub!(:tap).and_yield(proto_instance)
+        klass.stub!(:new).and_return(proto)
+        proto_instance
+      end
+
+    end
+  end
+end

data/lib/protobuf/rspec/version.rb

@@ -0,0 +1,5 @@
+module Protobuf
+  module RSpec
+    VERSION = "0.0.1"
+  end
+end

data/protobuf-rspec.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "protobuf/rspec/version"
+
+Gem::Specification.new do |s|
+  s.name        = "protobuf-rspec"
+  s.version     = Protobuf::RSpec::VERSION
+  s.authors     = ["BJ Neilsen"]
+  s.email       = ["bj.neilsen@gmail.com"]
+  s.homepage    = "http://github.com/localshred/protobuf-rspec"
+  s.summary     = %q{Protobuf RSpec helpers for testing services and clients. Meant to be used with the protobuf gem. Decouple external services/clients from each other using the given helper methods.}
+  s.description = s.summary
+
+  s.rubyforge_project = "protobuf-rspec"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  s.add_runtime_dependency "protobuf", "~> 1.1"
+  s.add_runtime_dependency "rspec", "~> 2.8"
+  s.add_development_dependency "yard", "~> 0.7"
+  s.add_development_dependency "redcarpet", "~> 2.1"
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: protobuf-rspec
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- BJ Neilsen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-10 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: protobuf
+  requirement: &2160846800 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2160846800
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &2160845600 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2160845600
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &2160844920 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: *2160844920
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: &2160843920 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: *2160843920
+description: Protobuf RSpec helpers for testing services and clients. Meant to be
+  used with the protobuf gem. Decouple external services/clients from each other using
+  the given helper methods.
+email:
+- bj.neilsen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- lib/protobuf/rspec.rb
+- lib/protobuf/rspec/helpers.rb
+- lib/protobuf/rspec/version.rb
+- protobuf-rspec.gemspec
+homepage: http://github.com/localshred/protobuf-rspec
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: protobuf-rspec
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Protobuf RSpec helpers for testing services and clients. Meant to be used
+  with the protobuf gem. Decouple external services/clients from each other using
+  the given helper methods.
+test_files: []
+has_rdoc: