bogus 0.0.2 → 0.0.3.rc.1

data/features/configuration_options.feature

@@ -1,7 +1,6 @@
 Feature: Configuration Options
 
-  Bogus can be configured, similarly to many other frameworks with a configure block.
-  This feature describes the configuration options available.
+  Bogus can be configured, similarly to many other frameworks with a configure block.  This feature describes the configuration options available.
 
   Scenario: search_modules
     Given a file named "foo.rb" with:

data/features/{contract_tests_mocks.feature → contract_tests/contract_tests_mocks.feature}

@@ -1,5 +1,7 @@
 Feature: Contract tests with mocks
 
+  Whenever you mock something, you specify a contract on the arguments/return value pair.  Bogus can check automatically Whether this contract was satisfied.
+
   Background:
     Given a file named "foo.rb" with:
     """ruby
@@ -45,9 +47,10 @@ Feature: Contract tests with mocks
       it "does not check out the book from library if not available" do
         student = Student.new
         mock(library).has_book?("Moby Dick") { false }
-        dont_allow(library).checkout("Moby Dick")
 
         student.read("Moby Dick", library)
+
+        library.should_not have_received.checkout("Moby Dick")
       end
     end
     """

data/features/{contract_tests_spies.feature → contract_tests/contract_tests_spies.feature}

@@ -1,5 +1,7 @@
 Feature: Contract tests with spies
 
+  Whenever you spy on method invocations, it creates a contract specifying that some method can be called with a particular set of arguments. It can be automatically verified by Bogus, whether the method was actually called with those arguments.
+
   Background:
     Given a file named "foo.rb" with:
     """ruby

data/features/{contract_tests_stubs.feature → contract_tests/contract_tests_stubs.feature}

@@ -1,5 +1,19 @@
 Feature: Contract tests with stubs
 
+  Whenever you stub any method, a contract is specified on the input/output values of that method.
+
+  When stubbing using the short syntax:
+
+      fake(:fake_name, method_name: :return_value)
+
+  the contract can only be specified on the return value.
+
+  The longer syntax:
+
+      stub(fake).method_name(args) { :return_value }
+
+  will also create a contract on the method input parameters.
+
   Background:
     Given a file named "foo.rb" with:
     """ruby

data/features/contract_tests/readme.md

@@ -0,0 +1,26 @@
+Whenever you write test code like this:
+
+    mock(library).checkout("Moby Dick") { raise NoSuchBookError }
+
+There are some assumptions this code makes:
+
+1. There is an object in my system that can play the role of a library.
+2. The library object has a `#checkout` method that takes one argument.
+3. The system under test is supposed to call `#checkout` with argument `"Moby Dick"` at least once.
+4. There is some context in which, given argument "Moby Dick", the `#checkout` method raises `NoSuchBookError`.
+
+While using fakes makes sure that the assumptions 1 and 2 are satisfied, and assumption number 3 is verified by the mocking system, in order to make sure that the assumption no 4 is also true, you need to write a test for the library object.
+
+Bogus will not be able to write that test for you, but it can remind you that you should do so.
+
+Whenever you use named fakes:
+
+    fake(:library)
+
+Bogus will remember any interactions set up on that fake.
+
+If you want to verify that you remembered to test all the scenarios specified by stubbing/spying/mocking on the fake object, you can put the following code in the tests for "the real thing" (i.e. the Library class in our example):
+
+    verify_contract(:library)
+
+This will record all of the interactions you make with that class and make the tests fail if you forget to test some scenario that you recorded using a fake object.

data/features/{return_value_contracts.feature → contract_tests/return_value_contracts.feature}

@@ -1,5 +1,9 @@
 Feature: Return value contracts
 
+  In order to be able to record the stubbed value, Bogus requires that the block you pass when stubbing is free of side effects and idempotent.
+
+  If it's not, the behavior of contract verification is not defined.
+
   Background:
     Given a file named "foo.rb" with:
     """ruby
@@ -51,7 +55,7 @@ Feature: Return value contracts
     end
     """
 
-  Scenario: Fails when returned values differ
+  Scenario: Bogus makes sure that all the return values recorded by stubbing are also present in tests of the real object
     Then spec file with following content should fail:
     """ruby
     describe AuthenticationService do
@@ -66,7 +70,7 @@ Feature: Return value contracts
     end
     """
 
-  Scenario: Passes when interfaces match
+  Scenario: Bogus does not fail the tests if all the recorded values have been also recorded on the real object
     Then spec file with following content should pass:
     """ruby
     describe AuthenticationService do

data/features/{anonymous_doubles.feature → fakes/anonymous_doubles.feature}

@@ -1,14 +1,21 @@
 Feature: Anonymous test doubles
 
-  Anonymous test doubles can be useful as a stepping stone towards
-  actual fakes and when migrating from another testing library.
+  Anonymous test doubles can be useful as a stepping stone towards actual fakes and when migrating from another testing library.
 
-  In contrast with other testing libraries, Bogus makes it's fakes
-  respond to all methods by default and makes those calls chainable.
-  This way you can spy on methods without stubbing them first.
+  In contrast with other testing libraries, Bogus makes it's fakes respond to all methods by default and makes those calls chainable.  This way you can spy on methods without stubbing them first.
 
-  It is not advisable to use those for anything else than an intermediate step.
-  Fakes that mimic an actual class have many more benefits.
+  It is not advisable to use those for anything else than an intermediate step.  Fakes that mimic an actual class have many more benefits.
+
+  The syntax for defining fakes is:
+
+      fake(method_1: return_value, method_2: proc{return_value2})
+
+  If you pass a proc as a return value to a fake, the proc will be called to obtain the value.  This can be used for instance to raise errors in stubbed methods.
+
+  If you want to actually return a proc from a method, you need to use a slightly longer syntax:
+
+      factory = fake()
+      stub(factory).make_validator{ proc{ false } }
 
   Background:
     Given a file named "foo.rb" with:
@@ -34,7 +41,7 @@ Feature: Anonymous test doubles
       let(:jake) { Student.new("Jake") }
       
       it "allows stubbing any method with any parameters" do
-        stub(library).register_junior { "the card" }
+        stub(library).register_junior(any_args) { "the card" }
 
         jake.sign_up(library)
 
@@ -58,6 +65,15 @@ Feature: Anonymous test doubles
     end
     """
 
+  Scenario: Stubbing methods inline by passing a block
+    Then the following test should pass:
+    """ruby
+    library = fake(register_junior: proc{ raise "library full!" })
+    expect {
+      library.register_junior("Jake")
+    }.to raise_error("library full!")
+    """
+
   Scenario: Mocking any method with any parameters
     Then spec file with following content should pass:
     """ruby

data/features/{fake_objects.feature → fakes/fake_objects.feature}

@@ -1,7 +1,29 @@
 Feature: Faking existing classes
 
-  Bogus makes it easy to create fakes, which behave like a null-object and
-  have the same interface as the object being faked.
+  You create a fake by calling the `fake` method:
+
+      fake(fake_name, options) { ClassToCopy }
+
+  If you omit the fake_name, you will get an anonymous fake, otherwise the name will be used to identify the fake for the purposes of contract tests. If you omit the block returning the class to copy, fake name will also be used to guess that.
+
+  Usually you will want the fake to return an instance of the copied class.  Otherwise, you can pass `:as => :class` option to copy the class and return the copy, not an instance of it.
+
+  Options can also include methods to stub on the returned fake, which makes:
+
+      fake(:foo, bar: "value")
+
+  Equivalent to:
+
+      foo = fake(:foo)
+      stub(foo).bar(any_args) { "value" }
+
+  For your convenience, Bogus also defines the following macro:
+
+      fake(:foo, bar: "value")
+
+  Which is equivalent to:
+
+      let(:foo) [ fake(:foo, bar: "value")]
 
   Background:
     Given a file named "foo.rb" with:
@@ -90,5 +112,18 @@ Feature: Faking existing classes
     end
     """
 
-  Scenario: Fakes which are objects
-    Given pending
+  Scenario: Fakes with inline return values
+    Then spec file with following content should pass:
+    """ruby
+    describe "library class fake" do
+      let(:library) { fake(:library, checkout: "checked out", 
+                                     return_book: "returned") }
+
+      it "sets the default return value for provided functions" do
+        library.checkout("Moby Dick").should == "checked out"
+        library.checkout("Three Musketeers").should == "checked out"
+        library.return_book("Moby Dick").should == "returned"
+        library.return_book("Three Musketeers").should == "returned"
+      end
+    end
+    """

data/features/fakes/global_fake_configuration.feature

@@ -0,0 +1,88 @@
+Feature: Global fake configuration
+
+  In an ideal world, all our fakes would follow the tell-don't-ask principle, which would eliminate the need for stubbing, and would be instances of classes that match the fake name, which would eliminate the need for configuration of things like (`as: :class` / `as: :instance`).
+
+  However, in reality we often need to add this kind of configuration to our fake definitions, and the more collaborators a fake has, the more duplication we introduce this way.
+
+  To eliminate this duplication, Bogus comes with a DSL to configure the fakes in one place, and unify their use in all your tests.
+
+  To globally configure your fakes, all you need to do is to place code like this:
+
+      Bogus.fakes do
+        fake(:fake_name, as: :class, class: proc{SomeClass}) do
+          method_1 { return_value_1 } 
+          method_2 return_value_2
+        end
+      end
+
+  in your spec helper, or a file required from it.
+
+  Background:
+    Given a file named "foo.rb" with:
+    """ruby
+    class PublicLibrary
+      def self.books_by_author(name)
+      end
+    end
+    """
+
+    Given a file named "fakes.rb" with:
+    """ruby
+    Bogus.fakes do
+      fake(:library, as: :class, class: proc{PublicLibrary}) do
+        books_by_author []
+      end
+    end
+    """
+
+  Scenario: Globally configured fakes have all the properties configured
+    Then spec file with following content should pass:
+    """ruby
+    require_relative "fakes"
+
+    describe "The library fake" do
+      fake(:library)
+
+      it "is a class" do
+        # because of the as: :class specified in the fake definition
+        library.should be_an_instance_of(Class)
+      end
+
+      it "is a copy of PublicLibrary" do
+        # because of the block passed into configuration
+        library.name.should == "PublicLibrary"
+      end
+
+      it "returns has stubbed books_by_author" do
+        # because of the inline-stubbed books_by_author
+        library.books_by_author("Mark Twain").should == []
+      end
+    end
+    """
+
+  Scenario: Overwriting stubbed methods using fake macro
+    Then spec file with following content should pass:
+    """ruby
+    require_relative "fakes"
+
+    describe "The library fake" do
+      fake(:library, books_by_author: ["Some Book"])
+
+      it "can be overridden in the shortcut definition" do
+        library.books_by_author("Charles Dickens").should == ["Some Book"]
+      end
+    end
+    """
+
+  Scenario: Overwriting stubbed methods using fake helper function
+    Then spec file with following content should pass:
+    """ruby
+    require_relative "fakes"
+
+    describe "The library fake" do
+      it "can be overridden in the helper" do
+        library = fake(:library, books_by_author: ["Some Book"])
+        library.books_by_author("Charles Dickens").should == ["Some Book"]
+      end
+    end
+    """

data/features/fakes/readme.md

@@ -0,0 +1,11 @@
+Fakes in Bogus are essentially lightweight objects that mimic the original object's interface.
+
+Let's say that we have a `Library` class that is used to manage books and a `Student`, who can interact with the `Library` in some way.
+
+In order to test the `Student` in isolation, we need to replace the `Library`, with some test double. Typically, you would do that by creating an anonymous stub/mock object and stubbing the required methods on it.
+
+Using those stubs, you specify the desired interface of the library object.
+
+The problems with that approach start when you change the `Library` class. For example, you could rename the `#checkout` method to `#checkout_book`. If you used the standard approach, where your stubs are not connected in any way to the real implementation, your tests will keep happily passing, even though the collaborator interface just changed.
+
+Bogus saves you from this problem, because your fakes have the exact same interface as the real collaborators, so whenever you change the collaborator, but not the tested object, you will get an exception in your tests.

data/features/fakes/replacing_classes.feature

@@ -0,0 +1,148 @@
+Feature: Replacing classes with fakes
+
+  Bogus is an opinionated piece of software. One of the opinions we have is that you should use dependency injection to make your code more modular and your classes easier to compose. However, we respect the fact, that this is currently not very popular among Ruby developers.
+
+  In order to make life easier for people who choose not to use Dependency Injection, Bogus makes it convenient to replace chosen classes in your tests with fakes.
+
+  All you need to do, is put the following code in your describe:
+
+      fake_class(FooBar, foo: "bar")
+
+  Which is a shortcut for:
+
+      before do
+        fake_class(FooBar, foo: "bar")
+      end
+  
+  Background:
+    Given a file named "app.rb" with:
+    """ruby
+    require "yaml"
+
+    class Library
+      FILE =  "library.yml"
+
+      def self.books
+        YAML.load_file(FILE)
+      end
+    end
+
+    class BookIndex
+      def self.by_author(author)
+        Library.books.select{|book| book[:author] == author}
+      end
+    end
+    """
+
+    And a file named "spec_helper.rb" with:
+    """ruby
+    require 'bogus/rspec'
+
+    require_relative 'app'
+    """
+
+  Scenario: Replacing classes and contracts
+    Given a file named "library_spec.rb" with:
+    """ruby
+    require_relative 'spec_helper'
+    require 'fileutils'
+    
+    describe Library do
+      verify_contract(:library)
+
+      it "reads the books from the yaml file" do
+        books = [{name: "Tom Sawyer", author: "Mark Twain"}, 
+                 {name: "Moby Dick", author: "Herman Melville"}]
+        File.open(Library::FILE, "w") { |f| f.print books.to_yaml }
+
+        Library.books.should == books
+      end
+
+      after do
+        FileUtils.rm_rf(Library::FILE)
+      end
+    end
+    """
+
+    And a file named "book_index_spec.rb" with:
+    """ruby
+    require_relative 'spec_helper'
+
+    describe BookIndex do
+      verify_contract(:book_index)
+
+      it "returns books written by author" do
+        tom_sawyer = {name: "Tom Sawyer", author: "Mark Twain"}
+        moby_dick = {name: "Moby Dick", author: "Herman Melville"}
+
+        fake_class(Library, books: [tom_sawyer, moby_dick])
+
+        BookIndex.by_author("Mark Twain").should == [tom_sawyer]
+      end
+    end
+    """
+
+    When I run `rspec book_index_spec.rb library_spec.rb`
+    Then all the specs should pass
+    
+  Scenario: Replacing classes and contracts with a different fake name
+    Given a file named "library_spec.rb" with:
+    """ruby
+    require_relative 'spec_helper'
+    require 'fileutils'
+    
+    describe Library do
+      verify_contract(:book_repository)
+
+      it "reads the books from the yaml file" do
+        books = [{name: "Tom Sawyer", author: "Mark Twain"}, 
+                 {name: "Moby Dick", author: "Herman Melville"}]
+        File.open(Library::FILE, "w") { |f| f.print books.to_yaml }
+
+        Library.books.should == books
+      end
+
+      after do
+        FileUtils.rm_rf(Library::FILE)
+      end
+    end
+    """
+
+    And a file named "book_index_spec.rb" with:
+    """ruby
+    require_relative 'spec_helper'
+
+    describe BookIndex do
+      verify_contract(:book_index)
+
+      it "returns books written by author" do
+        tom_sawyer = {name: "Tom Sawyer", author: "Mark Twain"}
+        moby_dick = {name: "Moby Dick", author: "Herman Melville"}
+
+        fake_class(Library, fake_name: :book_repository,
+                            books: [tom_sawyer, moby_dick])
+
+        BookIndex.by_author("Mark Twain").should == [tom_sawyer]
+      end
+    end
+    """
+
+    When I run `rspec book_index_spec.rb library_spec.rb`
+    Then all the specs should pass
+    
+  Scenario: Replacing classes with a macro
+    Given a file named "book_index_spec.rb" with:
+    """ruby
+    require_relative 'spec_helper'
+
+    describe BookIndex do
+      fake_class(Library, books: [])
+
+      it "returns books written by author" do
+        BookIndex.by_author("Mark Twain").should == []
+      end
+    end
+    """
+
+    When I run `rspec book_index_spec.rb`
+    Then all the specs should pass