aidmock 0.1.0 → 0.2.0

data/.gitignore

@@ -1,2 +1,5 @@
 /.bundle/
 .DS_Store
+coverage
+rdoc
+pkg

data/README.textile

@@ -1,5 +1,242 @@
 h1. Aidmock
 
-Hi, we are under development, but if you wanna know more about what this project is for, check our "motivation":https://github.com/wilkerlucio/aidmock/wiki/Motivation page.
+Aidmock is an safe mock and interfacing library for Ruby.
 
-We will have something usable for you in soon :)
+Aidmock doesn't target any specific mock or test framework. Our goal is to provide a wide solution, that supports the major mock and test frameworks. For now we are only supporting RSpec 2 and RSpec Mocks, but more drivers for other frameworks will be available soon.
+
+The basic idea of Aidmock is we believe that Mocks are good, but they can be scary too, leading to false positives. Aidmock tries to make it safer. To read more about motivation, see the "motivation":https://github.com/wilkerlucio/aidmock/wiki/Motivation page.
+
+Aidmock also generate some sanity checks for your interfaces, so defining interfaces can be a nice point when starting the defition of your classes. Let's start with setup and configuration, then we will see how to define our interfaces.
+
+h2. Installation
+
+To install Aidmock just run:
+
+bc. gem install aidmock
+
+Or add it to your Gemfile:
+
+bc. gem "aidmock"
+
+h2. Configuration
+
+In order to use Aidmock, you need to configure it on your test environment. Since it's only working on RSpec for now you need to configure your @spec_helper@:
+
+bc..
+RSpec.configure do |config|
+  config.before :all do
+    Aidmock.setup # it will do any nescessary setup, like extending your framework mocks
+  end
+
+  config.after :each do
+    Aidmock.verify # it will verify created mocks after each spec
+  end
+end
+
+# load or write your interfaces here
+
+Aidmock::Sanity.sanitize # it will run sanity checks, just call it after have all interfaces defined
+
+h2. How It Works
+
+Aidmock runs after each test you do. It will get the mocks/stubs defined by your test and match these doubles with the interface you have defined for that object. If your mock doesn't respect your interface, it will raise an error, preventing you from having a false positive. Simple :)
+
+h3. Remember to constrain your mocks
+
+Sometimes you wanna do something like this:
+
+bc. obj = mock
+obj.should_receive(:something)
+
+With Aidmock we can't detect the class with only this, so, for a safe mocking on this cases you should constrain the mock for one class or module that you already interfaced:
+
+bc. obj = mock.constrained_to(SomeInterface)
+obj.should_receive(:something)
+
+This way can clear parse it.
+
+h3. No interface warn
+
+By default, Aidmock will warn you when you try to mock/stub something that you haven't interfaced. You can remove this warn with following snippet:
+
+bc. Aidmock.warn_undefined_interface = false
+
+h2. Interfacing
+
+The major point of Aidmock is interfacing: it's when you define how your object's are supposed to work. It's really like you define methods on static languages as C or Java, but it's more dynamic and cool to work with. :)
+
+Let's try it and define a simple interface:
+
+bc.. Aidmock.interface Person do
+  method :first_name, String
+  method :first_name=, nil, String
+
+  method :last_name, String
+  method :last_name=, nil, String
+
+  method :full_name, String
+end
+
+p. Ok, let's take some time to look at what we are doing. We use a DSL created by Aidmock to define the class interface. In this case we use @method@ to describe an instance method. The first argument is the method name, the second one is the return, and after return we can send any number of params we want: they are the arguments.
+
+The return and arguments in fact are matchers; they match if the value used corresponds to the matcher. In the example above, we used two different kind of matchers: the @KindOfMatcher@ (when we used the String class, it created this matcher) and the @AnythingMatcher@ (when we used nil).
+
+This interface will automatically create some specs that check if these methods are defined on @Person@ class and if they respect the method arity. And most important, when you stub or mock the Person, it will check the interface and if you are mocking with correct params and return values; this will make your double safe.
+
+h3. Class Methods
+
+For interfacing class methods just use @class_method@ instead of @method@. Everything else is same for both.
+
+h3. Method Names
+
+The method names can be specified as symbol or regexp. Use symbol for method exact names and regexp for dynamic names.
+
+bc. Aidmock.Interface MyAR do
+  method :table, Symbol
+  method /find_by_.+/, String
+end
+
+h2. Matchers
+
+In section above we saw a simple example of how to create an interface. Now we will go deeper and see all the available matchers and how to use them.
+
+h3(#conversions). Matcher Conversion
+
+In most of cases, instead of creating a matcher directly, you will use a "Matcher Conversion". It takes simple values and create matchers based on them. In the table above you can see all available conversions:
+
+|_. Object Type  |_. Matcher       |_. Description                                                                                          |
+| Class          | KindOfMatcher   | if object is class, it will create a @KindOfMatcher@ with the given class                              |
+| Array          | AnyMatcher      | if the object is an array, it will create an @AnyMatcher@, where each item of array will be an matcher |
+| nil            | AnythingMatcher | if the object is nil, it will create an @AnythingMatcher@                                              |
+| Symbol         | DuckTypeMatcher | if the object is a symbol, it will create an @DuckTypeMatcher@ that responds to it                     |
+| Hash           | HashMatcher     | if the object is an hash, it will create an @HashMatcher@ with given hash                              |
+
+h3(#any_matcher). AnyMatcher
+
+This matcher can be used when you want to have more than one matcher option. It takes a list of matchers (or use a value to be converted by "conversions":#conversions) and it will match if any of these matchers matches.
+
+DSL helper: @any_of(*matchers)@
+Conversion: use an array
+
+Example:
+
+bc. method :concat, String, [String, Fixnum]
+method :concat, String, any_of(String, Fixnum) # same as line above
+
+h3(#anything_matcher). AnythingMatcher
+
+This matcher will simply accept anything.
+
+DSL Helper: @anything@
+Conversion: use a @nil@
+
+Example:
+
+bc. method :puts, nil
+method :puts, anything #same as line above
+
+h3(#duck_type_matcher). DuckTypeMatcher
+
+Duck type matcher will check if an object responds to all the given methods.
+
+DSL Helper: @respond_to(*methods)@
+Conversion: use a symbol
+
+Example:
+
+bc. method :write, :to_s
+method :write, respond_to(:to_s) # same as line above
+
+h3(#instance_of_matcher). InstanceOfMatcher
+
+Check if the object is the instance of given class.
+
+DSL Helper: @instance_of(klass)@
+
+Example:
+
+bc. method :to_s, instance_of(String)
+
+h3(#kind_of_matcher). KindOfMatcher
+
+Check the object is the kind of given class.
+
+DSL Helper: @kind_of(klass)@
+Conversion: use any class
+
+Example:
+
+bc. method :find, ActiveRecord::Base
+method :find, kind_of(ActiveRecord::Base) # same as above line
+
+h3(#hash_matcher). HashMatcher
+
+The hash matcher checks if the argument is a hash and each key defined on it. If the user sends a hash with a key that is not present on the hash definition, it will fail. It also checks the value type of each key. By default it will ignore if the user doesn't send all expected options (which is a common pattern for options arguments), but it has a strict mode that will require all the keys to be defined.
+
+DSL Helper: @hash_including(hash, strict = false)@
+Conversion: use any hash
+
+Example:
+
+bc. method :find, {:conditions => [String, Array], :order => String}
+method :find, has_including(:conditions => [String, Array], :order => String) # same as above
+method :find, has_including({:conditions => [String, Array], :order => String}, true) # will require to be called with all keys defined
+
+h3(#not_nil_arg_matcher). NotNilArgMatcher
+
+By default, all matchers will accept a @nil@ value. If you want to require the value (making a @nil@ return false), you can use this matcher. You also need to send a matcher as param (to check when value is not nil, you can use the conversions too).
+
+DSL Helper: @not_nil(matcher)@ or @nn(matcher)@
+
+Example:
+
+bc. method :name=, nil, nn(String)
+method :name=, nil, not_nil(String) # same as above
+
+h3(#optional_arg_matcher). OptionalArgMatcher
+
+When you want optional arguments, the @OptionalArgMatcher@ will solve it for you. This matcher is only valid for arguments.
+
+DSL Helper: @optional(matcher)@ or @o(matcher)@
+
+Example:
+
+bc. method :something, nil, o(String)
+method :something, nil, optional(String) # same as above
+
+h3(#splat_arg_matcher). SplatArgMatcher
+
+When you want to use splat arguments (example: @def thing(*args)@) this matcher will interface it, you also need to send an matcher (or conversion) to it, and each value of splat will be matched by this matcher. This matcher is only valid for arguments.
+
+DSL Helper: @splat(matcher)@ or @s(matcher)@
+
+Example:
+
+bc. method :something, s(nil) # will accept splat with anything(nil will be converted one AnythingMatcher)
+method :something, splat(nil) # same as above
+
+h2. Class Inheritance and Modules
+
+Aidmock respects your class inheritance and module definition, so, the below example will be valid:
+
+bc.. class Animal
+  def scream(noise)
+    puts noise.to_s + "!!!"
+  end
+end
+
+class Dog < Animal
+end
+
+Aidmock.interface Animal do
+  method :scream, String, :to_s
+end
+
+it "test inheritance" do
+  dog = Dog.allocate
+  dog.stub(:scream).with("ha").and_return("ha!!!") # this stub will be verified as you expect
+end
+
+h2. Feedback
+
+Aidmock still be somekind of experimental project, any feedback will help a lot. Please use github issues for reporting any bug and/or suggestion :)

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/aidmock.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{aidmock}
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Wilker Lucio"]
-  s.date = %q{2011-01-10}
+  s.date = %q{2011-01-17}
   s.description = %q{Aidmock, safe mocking and interfacing for Ruby}
   s.email = %q{wilkerlucio@gmail.com}
   s.extra_rdoc_files = [
@@ -23,6 +23,7 @@ Gem::Specification.new do |s|
      "Rakefile",
      "VERSION",
      "aidmock.gemspec",
+     "examples/integration_spec.rb",
      "examples/mock_spec.rb",
      "lib/aidmock.rb",
      "lib/aidmock/basic_object.rb",
@@ -55,6 +56,7 @@ Gem::Specification.new do |s|
      "spec/aidmock/sanity_spec.rb",
      "spec/aidmock_spec.rb",
      "spec/spec_helper.rb",
+     "examples/integration_spec.rb",
      "examples/mock_spec.rb"
   ]
 

data/examples/integration_spec.rb

@@ -0,0 +1,56 @@
+$: << File.expand_path("../../lib", __FILE__)
+require 'aidmock'
+
+RSpec.configure do |config|
+  config.before :all do
+    Aidmock.setup
+  end
+
+  config.after :each do
+    Aidmock.verify
+  end
+end
+
+class Address
+  def full_address
+    "testing"
+  end
+end
+
+class Person
+  def name
+    "John"
+  end
+
+  def full_info(address)
+    "#{name} - #{address.full_address}"
+  end
+end
+
+Aidmock.interface Person do
+  method :name, String
+  method :full_info, String, :full_address
+end
+
+Aidmock.interface Address do
+  method :full_address, String
+end
+
+Aidmock::Sanity.sanitize
+
+describe Person do
+  before :each do
+    @person = Person.new
+  end
+
+  context ".full_info" do
+    it "should return some" do
+      address = mock.constrained_to(Address)
+      address.stub(:full_address) { "my street" }
+
+      @person.stub(:name).and_return("my name")
+
+      @person.full_info(address).should == "my name - my street"
+    end
+  end
+end

data/lib/aidmock.rb

@@ -26,6 +26,7 @@ module Aidmock
   autoload :MethodDescriptor, 'aidmock/method_descriptor'
   autoload :VoidClass, 'aidmock/void_class'
   autoload :Frameworks, 'aidmock/frameworks'
+  autoload :TestFrameworks, 'aidmock/test_frameworks'
   autoload :Matchers, 'aidmock/matchers'
   autoload :Sanity, 'aidmock/sanity'
 
@@ -50,6 +51,18 @@ module Aidmock
       @interfaces ||= {}
     end
 
+    def framework
+      ::Aidmock::Frameworks::RSpec
+    end
+
+    def test_framework
+      ::Aidmock::TestFrameworks::RSpec
+    end
+
+    def setup
+      framework.extend_doubles
+    end
+
     protected
 
     def verify_double(double)
@@ -87,13 +100,10 @@ module Aidmock
     end
 
     def extract_class(object)
+      return object.aidmock_class if object.respond_to? :aidmock_class and object.aidmock_class != nil
       object.instance_of?(Class) ? object : object.class
     end
 
-    def framework
-      ::Aidmock::Frameworks::RSpec
-    end
-
     def create_or_update_interface(klass, &block)
       interface = interfaces[klass] || Interface.new(klass)
       interface.instance_eval &block

data/lib/aidmock/frameworks.rb

@@ -23,5 +23,15 @@ module Aidmock
     autoload :RSpec, 'aidmock/frameworks/rspec'
 
     MockDescriptor = Struct.new(:object, :method, :result, :arguments)
+
+    module DoubleExtensions
+      attr_reader :aidmock_class
+
+      def constrained_to(interface)
+        @aidmock_class = interface
+
+        self
+      end
+    end
   end
 end

data/lib/aidmock/frameworks/rspec.rb

@@ -43,6 +43,10 @@ module Aidmock
           mocks
         end
 
+        def extend_doubles
+          ::RSpec::Mocks::Mock.send(:include, ::Aidmock::Frameworks::DoubleExtensions)
+        end
+
         protected
 
         def parse_double_result(double)

data/spec/aidmock/frameworks/rspec_spec.rb

@@ -30,6 +30,20 @@ end
 describe Aidmock::Frameworks::RSpec do
   framework = Aidmock::Frameworks::RSpec
 
+  context ".extend_doubles" do
+    it "save and retrieve aidmock class" do
+      framework.extend_doubles
+      obj = mock.constrained_to(String)
+      obj.aidmock_class.should == String
+    end
+
+    it "save and retrieve aidmock class for stub" do
+      framework.extend_doubles
+      obj = stub.constrained_to(String)
+      obj.aidmock_class.should == String
+    end
+  end
+
   context ".mocks" do
     context "caller object" do
       it "return the object" do

data/spec/aidmock_spec.rb

@@ -113,6 +113,20 @@ describe Aidmock do
   end
 
   context ".extract_class" do
+    it "return aidmock_class if object responds to it" do
+      obj = mock
+      obj.stub!(:aidmock_class) { Fixnum }
+
+      Aidmock.send(:extract_class, obj).should == Fixnum
+    end
+
+    it "return class itself if object aidmock_class is nil" do
+      obj = mock
+      obj.stub!(:aidmock_class) { nil }
+
+      Aidmock.send(:extract_class, obj).should == ::RSpec::Mocks::Mock
+    end
+
     it "return the object class if it's an instance" do
       Aidmock.send(:extract_class, "string").should == String
     end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Wilker Lucio
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-10 00:00:00 -03:00
+date: 2011-01-17 00:00:00 -03:00
 default_executable: 
 dependencies: []
 
@@ -34,6 +34,7 @@ files:
 - Rakefile
 - VERSION
 - aidmock.gemspec
+- examples/integration_spec.rb
 - examples/mock_spec.rb
 - lib/aidmock.rb
 - lib/aidmock/basic_object.rb
@@ -92,4 +93,5 @@ test_files:
 - spec/aidmock/sanity_spec.rb
 - spec/aidmock_spec.rb
 - spec/spec_helper.rb
+- examples/integration_spec.rb
 - examples/mock_spec.rb