bogus 0.0.2 → 0.0.3.rc.1

data/features/getting_started.md

@@ -0,0 +1,36 @@
+## Installation
+
+To install Bogus, all you need to do is add:
+
+    gem "bogus"
+
+to your Gemfile.
+
+## Configuration
+
+In your `spec_helper.rb`, require bogus:
+
+    require 'bogus/rspec'
+
+Bogus will hook into RSpec on it's own, but if you want to be explicit about the used mock framework, you can put this in your `spec_helper.rb`:
+
+    RSpec.configure do |c|
+      # already done by requiring bogus/rspec
+      c.mock_with Bogus::RSpecAdapter
+    end
+
+And configure it to look for classes in your namespace:
+
+    Bogus.configure do |c|
+      c.search_modules << My::Namespace
+    end
+
+You will probably also want to create a configuration file for your fakes (for example `spec/support/fakes.rb`):
+
+    Bogus.fakes do
+      # fakes go here
+    end
+
+and require it in your gem file:
+
+    require_relative 'support/fakes.rb'

data/features/license.md

@@ -0,0 +1,9 @@
+# The MIT License (MIT)
+
+Copyright (c) 2012-2013 Adam Pohorecki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/features/readme.md

@@ -0,0 +1,173 @@
+Bogus is a library that aims to reduce the risks associated with isolated unit testing.  
+
+## The problem
+
+It is not uncommon to encounter code like this in isolated unit tests:
+
+    it "returns the average score" do
+      scores = stub(get: [5, 9])
+      students = stub(all: ["John", "Mary"])
+
+      report_card = ReportCard.new(scores, students)
+
+      report_card.average_score.should == 7
+    end
+
+_NOTE:  In the above example we use mocha syntax, but this patten is common
+to all the major mocking frameworks_
+
+The test above not only ensures that `ReportCard` can calculate the average score for all the students, but it also specifies how this class will interact with it's collaborators and what those collaborators will be.
+
+This style of testing enables us to practice so called *programming by wishful thinking*.  We can implement `ReportCard` and get it to work before it's collaborators are implemented.  This way we can design our system top-down and only implement what we need. This is a Very Good Thing(tm).
+
+However, the same freedom that comes from not having to implement the collaborators, can quickly turn against us. Once implement `ReportCard`, what test will tell us that `Scores` and `Students` are not implemented yet?
+
+The kind of stubbing that you see in the example above requires us to write integrated or end-to-end test *just to make sure that the objects we implemented fit together*.  This is a problem, because those tests can be quite slow and hard to set up in a way that covers all the integration points between our objects.
+
+Another problem is that it's quite likely that `Students` and `Scores` will be collaborating with more objects than the `ReportCard`. If so, you will find yourself typing code like this over and over again:
+
+    students = stub(all: ["John", "Mary"])
+
+This is duplication. It is also a problem, because if you decide to change the interface of the `Students` class, suddenly you will have to remember every place you created that stub and fix it. Your tests won't help you, because they don't have any idea what the `Students` interface should look like.
+
+## The solution
+
+Bogus makes your test doubles more assertive. They will no longer be too shy to tell you: "Hey, you are stubbing the wrong thing!".
+
+Let's reexamine our previous example, this time Bogus-style:
+
+    it "returns the average score" do
+      students = fake(:students, get: [5, 9])
+      scores = fake(:scores, all: ["John", "Mary"])
+
+      report_card = ReportCard.new(scores, students)
+
+      report_card.average_score.should == 7
+    end
+
+Can you spot the difference? Not much, huh?
+
+However, the code above will not only make sure that the `ReportCard` works, it will also make sure that classes `Students` and `Scores` exist and have an interface that matches what you stub on them.
+
+## DRY out your fake definitions
+
+By now you know how Bogus can help you with making sure that your stubs match the interface of your production classes. However, the attentive reader has probably spotted a problem with the solution above already. If all you need to change in your tests is the word `stub` to `fake` and give it some name, then how is that any better when it comes to scattering the fake interface definition all over your specs?
+
+The answer is: it's just slightly better. The reason it's better is that you only need to ever stub methods that return meaningful values. Let us explain.
+
+### Tell-don't-ask methods
+
+Let's say we have a `PushNotifier` class:
+
+    class PushNotifier
+      def notify_async(messages)
+      end
+    end
+
+Now if you test an object that collaborates with our `PushNotifier`, you would do something like this:
+
+    fake(:push_notifier)
+
+    it "send push notifications when comment is added" do
+      comment_adder = CommentAdder.new(push_notifier)
+
+      comment_adder.add("Hello world!")
+
+      push_notifier.should have_received.notify_async("Comment: 'Hello world!' added.")
+    end
+
+While not really impressive, this feature is worth mentioning because it will eliminate a lot of the mocking and stubbing from your tests.
+
+### Global fake configuration
+
+Bogus also has a solution for DRYing stubbing of the methods that return values. All you need to do is to provide a reasonable default return value for those methods in the global fake configuration.
+
+      Bogus.fakes do
+        fake(:students) do
+          all []
+        end
+
+        fake(:scores) do
+          get []
+        end
+      end
+
+Now you will only need to stub those methods when you actually care about their return value, which is exactly what we want.
+
+## Contract tests
+
+Bogus is not the only mocking library to implement fakes and safe mocking. However, it is the first library to implement the concept of contract tests [as defined by J. B. Rainsberger][contracts].
+
+Let's start with an example:
+
+    stub(scores).get(["John", "Mary"]) { [5, 9] }
+
+We already know that Bogus makes sure for us that the `Scores` class exists, has a `get` method and that this method can be called with one argument.
+
+It would also be nice to know that the input/output that we stub makes sense for this method.
+
+Contract tests are an idea, that whenever we stub `Scores#get` with argument `["John", "Mary"]` to return the value `[5, 9]`, we should add a test for the Scores class, that calls method `get` with those same arguments and have the same return value.
+
+A contract test like that could look like this:
+
+    it "returns scrores for students" do
+      scores = Scores.new(redis)
+      scores.add("John", 5)
+      scores.add("Mary", 9)
+
+      scores.get(["John", "Mary"]).should == [5, 9]
+    end
+
+Obviously Bogus won't be able to write those tests for you. However it can remind you if you forget to add one.
+
+To add contract test verification, the only thing you need to do is add the line:
+
+    verify_contract(:students)
+
+to your tests for `Students` class.
+
+## Not only for people who use Dependency Injection
+
+The examples above all have one thing in common: they assume that your code has some way of injecting dependencies. We believe it should, and that's why we wrote [Dependor][dependor].
+
+However, we are aware that this practice is not very common in the Ruby community. That's why Bogus supports replacing classes with fakes.
+
+Let's assume, that you have production code like this:
+
+    class PushNotifier
+      def self.notify_async(message)
+        # ...
+      end
+    end
+
+    class CommentAdder
+      def self.add(parent, comment)
+        PushNotifier.notify_async("comment added")
+        # ...
+      end
+    end
+
+You can test it easily, with all the benefits of fakes, safe stubbing and contracts:
+
+    describe CommentAdder do
+      fake_class(PushNotifier)
+
+      it "should send a push notification" do
+        CommentAdder.add("the user", "the comment")
+
+        PushNotifier.should have_received.notify_async("comment added")
+      end
+    end
+
+    describe PushNotifier do
+      verify_contract(:push_notifier)
+
+      it "notifies about comments asynchronously" do
+        PushNotifier.notify_async("comment added")
+
+        # ...
+      end
+    end
+
+[contracts]: http://www.infoq.com/presentations/integration-tests-scam
+[dependor]: https://github.com/psyho/dependor

data/features/safe_stubbing/argument_matchers.feature

@@ -0,0 +1,30 @@
+Feature: Argument matchers
+
+  Bogus supports some argument matchers for use, when you don't really care about exact equality of arguments passed in or spied on.
+
+  Background:
+    Given a file named "foo.rb" with:
+    """ruby
+    class Catalog
+      def self.books_by_author_and_title(author, title)
+      end
+    end
+    """
+
+  Scenario: Stubbing methods with any arguments
+    Then the following test should pass:
+    """ruby
+    stub(Catalog).books_by_author_and_title(any_args) { :some_book }
+
+    Catalog.books_by_author_and_title("Mark Twain", "Tom Sawyer").should == :some_book
+    """
+
+  Scenario: Stubbing methods with some wildcard arguments
+    Then the following test should pass:
+    """ruby
+    stub(Catalog).books_by_author_and_title("Mark Twain", anything) { :twains_book }
+
+    Catalog.books_by_author_and_title("Mark Twain", "Tom Sawyer").should == :twains_book
+    Catalog.books_by_author_and_title("Mark Twain", "Huckleberry Finn").should == :twains_book
+    """
+

data/features/safe_stubbing/readme.md

@@ -0,0 +1,35 @@
+Bogus let's you stub methods on any object, not just fakes, which makes this feature usable even in scenarios when you don't follow the Inversion of Control Principle.
+
+When you stub/mock a method in Bogus, it will automatically ensure that:
+
+1. The method actually exists
+2. It can take the number of arguments you passed
+
+Those of you familiar with RR stubbing syntax, will fill right at home with Bogus:
+
+    stub(object).method_name(*arguments) { return_value }
+
+One key difference is for when you want to stub a method for any arguments:
+
+    # RR syntax
+    stub(object).method_name { return_value }
+
+    # Bogus syntax
+    stub(object).method_name(any_args) { return_value }
+
+One other, quite important thing, is that Bogus does not erase the method signature when stubbing:
+
+    class Library
+      def self.checkout(book)
+      end
+    end
+
+The following would be OK in RR:
+
+    stub(Library).checkout { "foo" }
+    Library.checkout("a", "b") # returns "foo"
+
+But not in Bogus:
+
+    stub(Library).checkout(any_args) { "foo" }
+    Library.checkout("a", "b") # raises an error

data/features/{safe_mocking.feature → safe_stubbing/safe_mocking.feature}

@@ -1,5 +1,19 @@
 Feature: Safe mocking
 
+  In Bogus you normally use the following pattern to make sure right messages were sent between the tested object and it's collaborators:
+
+  1. Stub the collaborator method in let or before
+  2. In one test ensure that the tested method returns the right thing
+  3. In another test use `have_received` to ensure that the method on collaborator was called with right arguments.
+
+  However, there are cases when the more general stub in let or before is not enough. Then, we can use mocking to reduce the amount of code written.
+
+  The syntax for mocking is:
+
+      mock(object).method_name(*args) { return_value }
+
+  You can only mock methods that actually exist on an object. It will also work with methods that the object `responds_to?`, but (obviously) without being able to check the method signature.
+
   Background:
     Given a file named "foo.rb" with:
     """ruby

data/features/{safe_stubbing.feature → safe_stubbing/safe_stubbing.feature}

@@ -1,9 +1,10 @@
 Feature: Safe stubbing
 
-  Most Ruby test double libraries let you stub methods that don't exist.
-  Bogus is different in this respect: not only does it not allow stubbing 
-  methods that don't exist, it also ensures that the number of arguments
-  you pass to those methods matches the method definition.
+  Most Ruby test double libraries let you stub methods that don't exist.  Bogus is different in this respect: not only does it not allow stubbing methods that don't exist, it also ensures that the number of arguments you pass to those methods matches the method definition.
+
+  The stubbing syntax is:
+
+      stub(object).method_name(arg1, arg2, ...) { return_value }
 
   Background:
     Given a file named "foo.rb" with:
@@ -60,3 +61,16 @@ Feature: Safe stubbing
       end
     end
     """
+ 
+  Scenario: Stubbing methods multiple times
+    Then spec file with following content should fail:
+    """ruby
+    describe Library do
+      it "stubbing with too many arguments" do
+        library = Library.new
+
+        stub(library).checkout("some book") { :bought }
+        stub(library).checkout("book", "and one argument too many") { :whatever }
+      end
+    end
+    """

data/features/{spies.feature → safe_stubbing/spies.feature}

@@ -1,9 +1,8 @@
 Feature: Spies
 
-  Object Oriented Programming is all about messages sent between the objects.
-  If you follow principles like "Tell, Don't Ask", you will enable yourself
-  to combine Bogus's powerful feature of faking objects with it's ability 
-  to verify object interactions.
+  Object Oriented Programming is all about messages sent between the objects.  If you follow principles like "Tell, Don't Ask", you will enable yourself to combine Bogus's powerful feature of faking objects with it's ability to verify object interactions.
+
+  Typically, stubbing libraries force you to first stub a method, so that you can later make sure it was called. However, if you use fakes, Bogus lets you verify that a method was called (or not) without stubbing it first.
 
   Background:
     Given a file named "foo.rb" with:
@@ -76,3 +75,19 @@ Feature: Spies
       end
     end
     """
+
+  Scenario: Spying on previously stubbed methods
+    Then spec file with following content should pass:
+    """ruby
+    describe Student do
+      fake(:library)
+
+      it "studies using books from library" do
+        stub(library).checkout("Moby Dick") { "checked out" }
+
+        library.checkout("Moby Dick").should == "checked out"
+
+        library.should have_received.checkout("Moby Dick")
+      end
+    end
+    """

data/features/step_definitions/rspec_steps.rb

@@ -6,13 +6,8 @@ Given /^a spec file named "([^"]*)" with:$/ do |file_name, string|
     Given a file named "#{file_name}" with:
     """ruby
     require 'bogus/rspec'
-
     require_relative 'foo'
 
-    RSpec.configure do |config|
-      config.mock_with :rr
-    end
-
     #{string}
     """
   }
@@ -64,3 +59,17 @@ Then /^spec file with following content should fail:$/ do |string|
     Then the specs should fail
   }
 end
+
+Then /^the following test should pass:$/ do |string|
+  steps %Q{
+    When I run spec with the following content:
+    """ruby
+    describe Bogus do
+      specify do
+        #{string}
+      end
+    end
+    """
+    Then all the specs should pass
+  }
+end

data/features/support/env.rb

@@ -1 +1,5 @@
 require 'aruba/cucumber'
+
+Before('@known_bug') do
+  pending("This scenario fails because of a known bug")
+end

data/lib/bogus.rb

@@ -2,7 +2,9 @@ require 'dependor'
 
 require_relative 'bogus/takes'
 require_relative 'bogus/record_interactions'
+require_relative 'bogus/proxies_method_calls'
 require_relative 'bogus/rspec_extensions'
+require_relative 'bogus/rspec_adapter'
 
 all_files = Dir[File.expand_path('../**/*.rb', __FILE__)]
 all_files = all_files.reject{|f| f.include?('bogus/rspec') }.sort

data/lib/bogus/adds_recording.rb

@@ -1,11 +1,15 @@
-class Bogus::AddsRecording
-  extend Bogus::Takes
+module Bogus
+  class AddsRecording
+    extend Takes
 
-  takes :converts_name_to_class, :create_proxy_class, :overwrites_classes
+    takes :converts_name_to_class, :create_proxy_class, :overwrites_classes,
+      :overwritten_classes
 
-  def add(name)
-    klass = converts_name_to_class.convert(name)
-    new_klass = create_proxy_class.call(name, klass)
-    overwrites_classes.overwrite(klass, new_klass)
+    def add(name, klass = nil)
+      klass ||= converts_name_to_class.convert(name)
+      new_klass = create_proxy_class.call(name, klass)
+      overwrites_classes.overwrite(klass.name, new_klass)
+      overwritten_classes.add(klass.name, klass)
+    end
   end
 end