clean_test 0.10.0

data/lib/clean_test/any.rb

@@ -0,0 +1,169 @@
+require 'faker'
+
+module Clean # :nodoc:
+  module Test # :nodoc:
+    # Public: Provides the ability to vend arbitrary values without using literals, or
+    # long calls to Faker.  This has two levels of utility:
+    #
+    # helper methods - #any_number, #any_int, #any_string provide arbitrary primitives 
+    #                  to make it clear what numbers, ints, and strings in your tests are
+    #                  relevant.  Arbitrary values should use one of these any_ helpers.
+    #
+    # any sort of any - you can define your own "any" values by using #new_any, which allows you to 
+    #                   extend things if you like.  Of course, you could just make your own any_method as well.
+    #
+    # Example:
+    #
+    #     class Person
+    #       def initialize(first_name,last_name,age)
+    #         # ...
+    #       end
+    #     end
+    #
+    #     test_that "someone under 18 is a minor" {
+    #       Given {
+    #         # First name and last name aren't relevant to the test
+    #         @person = Person.new(any_string,any_string,17)
+    #       }
+    #       When {
+    #         @minor = @person.minor?
+    #       }
+    #       Then {
+    #         assert @minor
+    #       }
+    #     }
+    #
+    #     test_that "full_name gives the full name" {
+    #       Given {
+    #         # Age isn't relevant; it just needs to be positive
+    #         @person = Person.new("Dave","Copeland",any_int :positive)
+    #       }
+    #       When {
+    #         @full_name = @person.full_name
+    #       }
+    #       Then {
+    #         assert_equal "Dave Copeland",@full_namej
+    #       }
+    #     }
+    module Any
+      MAX_RAND = 50000 # :nodoc:
+
+      # Public: Get any number; one that doesn't matter
+      #
+      # options - options to control what sort of number comes back:
+      #           :positive - make sure that the number is greater than zero
+      #           :negative - make sure that the number is less than zero
+      def any_number(*options)
+        any :number,options
+      end
+
+      # Public: Returns an integer.  options is the same as for #any_number
+      def any_int(*options)
+        any :int,options
+      end
+
+      # Public: Get an arbitrary string of any potential length (the real max is 2048 characters if you don't override it)
+      #
+      # options - options to control the returned string:
+      #           :max - the max size of the string you want
+      #           :min - the minimum size we want to come back
+      #
+      # Example
+      #
+      #     any_string :max => 255 # => ensure it'll fit into a varchar(255)
+      #     any_string :min => 1024 # at least 1024 characters
+      #
+      def any_string(options = {})
+        any :string,options
+      end
+
+      # Public: Get a predefined, arbitrary any.  
+      #
+      # sym - the any that has been defined already.  By default, the following are defined:
+      #       :string - does any_string
+      #       String  - does any_string
+      #       :number  - does any_number
+      #       Numeric  - does any_number
+      #       Float  - does any_number
+      #       :int  - does any_int
+      #       Fixnum  - does any_int
+      #       Integer  - does any_int
+      # options - whatever options are relevant to the user-defined any
+      #
+      # Example
+      #
+      #     new_any(:foo) do |options|
+      #       if options[:bar]
+      #         'bar'
+      #       else
+      #         'quux'
+      #       end
+      #     end
+      #
+      #     some_foo = any :foo
+      #     some_other_foo = any :foo, :bar => true
+      def any(sym,options = {})
+        anies[sym].call(options)
+      end
+
+      # Public: Create a new any that can be retrieved via #any
+      #
+      # any - the identifer of your new any. Can be anything though a Symbol or classname would be appropriate
+      # block - the block that will be called whenever you #any your any.
+      def new_any(any,&block)
+        anies[any] = block
+      end
+
+      private
+
+      def anies
+        @anies ||= default_anies
+      end
+
+      ANY_STRING = Proc.new do |options| # :nodoc:
+        max_size = options[:max] || rand(2048)
+        min_size = options[:min] || rand(1024)
+        min_size = max_size if min_size > max_size
+
+        size = rand(max_size)
+
+        size = min_size if size < min_size
+
+        string = Faker::Lorem.words(1).join('')
+        while string.length < size
+          string += Faker::Lorem.words(1).join('') 
+        end
+
+        string[0..(max_size-1)]
+      end
+
+      ANY_NUMBER = Proc.new do |options| # :nodoc:
+        number = (rand(2 * MAX_RAND) - MAX_RAND).to_f/100.0
+        if options.include? :positive
+          number + MAX_RAND
+        elsif options.include? :negative
+          number - MAX_RAND
+        else
+          number
+        end
+      end
+
+      ANY_INT = Proc.new do |options| # :nodoc:
+        (ANY_NUMBER.call(options)).to_i
+      end
+
+      def default_anies
+        { :string => ANY_STRING,
+          String => ANY_STRING,
+          :number => ANY_NUMBER,
+          Numeric => ANY_NUMBER,
+          Float => ANY_NUMBER,
+          :int => ANY_INT,
+          Fixnum => ANY_INT,
+          Integer => ANY_INT,
+        }
+      end
+    end
+  end
+end
+

data/lib/clean_test/given_when_then.rb

@@ -0,0 +1,186 @@
+module Clean # :nodoc:
+  module Test # :nodoc:
+    # A means of documenting the parts of your test code according
+    # to the class "Given/When/Then" system.
+    # This does no enforcement of any kind and is merely documentation to make
+    # your tests readable.
+    #
+    # Example:
+    #
+    #     Given {
+    #       @circle = Circle.new(10)
+    #     }
+    #     When {
+    #       @area = @circle.area
+    #     }
+    #     Then {
+    #       assert_equal 314,@area
+    #     }
+    #
+    # There are also two additional methods provided ,#the_test_runs and
+    # #mocks_shouldve_been_called to assist with creating readable tests that use mocks.  See those
+    # methods for an example
+    module GivenWhenThen
+      # Public: Set up the conditions for the test
+      #
+      # existing_block - a callable object (e.g. a Proc) that will be called immediately
+      #                  by this Given.  If nil, &block is expected to be passed
+      # block          - a block given to this call that will be executed immediately
+      #                  by this Given.  If existing_block is non-nil, this is ignored
+      #
+      # Examples
+      #     
+      #     Given {
+      #       @foo = "bar"
+      #     }
+      #
+      # Returns the block that was executed
+      def Given(existing_block=nil,&block)
+        call_block_param_or_block_given(existing_block,&block)
+      end
+      # Public: Execute the code under test
+      #
+      # existing_block - a callable object (e.g. a Proc) that will be called immediately
+      #                  by this When.  If nil, &block is expected to be passed
+      # block          - a block given to this call that will be executed immediately
+      #                  by this When.  If existing_block is non-nil, this is ignored
+      #
+      # Examples
+      #     
+      #     When {
+      #       @foo.go
+      #     }
+      #
+      # Returns the block that was executed
+      def When(existing_block=nil,&block)
+        Given(existing_block,&block)
+      end
+
+      # Public: Verify the results of the test
+      #
+      # existing_block - a callable object (e.g. a Proc) that will be called immediately
+      #                  by this Then.  If nil, &block is expected to be passed
+      # block          - a block given to this call that will be executed immediately
+      #                  by this Then.  If existing_block is non-nil, this is ignored
+      #
+      # Examples
+      #     
+      #     Then {
+      #       assert_equal "bar",@foo
+      #     }
+      #
+      # Returns the block that was executed
+      def Then(existing_block=nil,&block)
+        Given(existing_block,&block)
+      end
+
+      # Public: Continue the previous Given/When/Then in a new block.  The reason
+      # you might do this is if you wanted to use the existing block form of a
+      # Given/When/Then, but also need to do something custom.  This allows you to 
+      # write your test more fluently.
+      #
+      # existing_block - a callable object (e.g. a Proc) that will be called immediately
+      #                  by this Then.  If nil, &block is expected to be passed
+      # block          - a block given to this call that will be executed immediately
+      #                  by this Then.  If existing_block is non-nil, this is ignored
+      #
+      # Examples
+      #     
+      #     def circle(radius)
+      #       lambda { @circle = Circle.new(radius) }
+      #     end
+      #
+      #     Given circle(10)
+      #     And {
+      #       @another_circle = Circle.new(30)
+      #     }
+      #
+      # Returns the block that was executed
+      def And(existing_block=nil,&block)
+        Given(existing_block,&block)
+      end
+
+      # Public: Continue the previous Given/When/Then in a new block.  The reason
+      # you might do this is if you wanted to use the existing block form of a
+      # Given/When/Then, but also need to do something custom, and that custom thing
+      # contradicts or overrides the flow, so an "And" wouldn't read properly.  This allows you to 
+      # write your test more fluently.
+      #
+      # existing_block - a callable object (e.g. a Proc) that will be called immediately
+      #                  by this Then.  If nil, &block is expected to be passed
+      # block          - a block given to this call that will be executed immediately
+      #                  by this Then.  If existing_block is non-nil, this is ignored
+      #
+      # Examples
+      #     
+      #     def options
+      #       lambda {
+      #         @options = {
+      #           :foo => 'bar',
+      #           :quux => 'baz',
+      #         }
+      #       }
+      #     end
+      #
+      #     Given options
+      #     But {
+      #       @options[:foo] = 'baz'
+      #     }
+      #
+      # Returns the block that was executed
+      def But(existing_block=nil,&block)
+        Given(existing_block,&block)
+      end
+
+      # Public: Used to make clear the structure of tests using mocks.
+      # This returns a no-op, and is intended to be used with a "When"
+      # to delineate the creation of a mock in a Given, and the 
+      # expectations of a mock in a "Then"
+      #
+      # Example:
+      #
+      #     Given {
+      #       @google = mock()
+      #     }
+      #     When the_test_runs
+      #     Then {
+      #       @google.expects(:search).with('foo').returns('bar')
+      #     }
+      #     Given {
+      #       @my_search = Search.new(@google)
+      #     }
+      #     When {
+      #       @result = @my_search.find('foo')
+      #     }
+      #     Then {
+      #       assert_equal 'Found bar',@result
+      #     }
+      #     And mocks_shouldve_been_called
+      def the_test_runs
+        lambda {}
+      end
+
+      # Public: Similar to #test_runs, this is used to make clear what
+      # you are testing and what the assertions are.  Since many Ruby mock
+      # frameworks do not require an explicit "verify" step, you often have tests
+      # that have no explicit asserts, the assertions being simply that the mocks were called
+      # as expected.  This step, which is a no-op, allows you to document that you are 
+      # expecting mocks to be called. See the example in #mocks_are_called for usage.
+      def mocks_shouldve_been_called
+        lambda {}
+      end
+
+      private
+
+      def call_block_param_or_block_given(existing_block,&block)
+        if existing_block.nil?
+          block.call
+          block
+        else
+          existing_block.call
+          existing_block
+        end
+      end
+    end
+  end
+end

data/lib/clean_test/test_case.rb

@@ -0,0 +1,32 @@
+require 'test/unit'
+require 'clean_test/given_when_then'
+require 'clean_test/any'
+require 'clean_test/test_that'
+
+module Clean # :nodoc:
+  module Test # :nodoc:
+    # Public: A Base class brings in all modules that are part
+    # of Clean::Test.
+    #
+    # Example
+    #
+    #     class TestCircle < Clean::Test::TestCase
+    #       test_that {
+    #         Given { @circle = Circle.new(10) }
+    #         When  { @area = @circle.area }
+    #         Then  { assert_equal 314,@area }
+    #       }
+    #     end
+    class TestCase < ::Test::Unit::TestCase
+      include GivenWhenThen
+      include TestThat
+      include Any
+      if RUBY_VERSION =~ /^1\.8\./
+        # Avoid the stupid behavior of 
+        # complaining that no tests were specified for 1.8.-like rubies
+        def default_test
+        end
+      end
+    end
+  end
+end

data/lib/clean_test/test_that.rb

@@ -0,0 +1,65 @@
+module Clean # :nodoc:
+  module Test # :nodoc:
+    # Public: Module that, when included, makes a class method, +#test_that+ available
+    # to create test methods in a more fluent way.  See ClassMethods.
+    module TestThat
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+
+        # Public: Create a new test method with the given optional description and
+        # body.
+        #
+        # description - a string describing what is being tested; write this as a follow on
+        #               from the phrase "test that".  If nil, a name will be constructed
+        #               based on the block
+        # block - the body of the test.
+        #
+        # Example
+        #
+        #     # Create a rails-style test method
+        #     test_that "area is computed based on positive radius" do
+        #       Given {
+        #         @circle = Circle.new(10)
+        #       }
+        #       When {
+        #         @area = @circle.area
+        #       }
+        #       Then {
+        #         assert_equal 314,@area
+        #       }
+        #     end
+        #
+        #     # Create an "anonymous" test, where the test body
+        #     # is clear enough as to what's being tested
+        #     test_that {
+        #       Given a_circle(:radius => 10)
+        #       When get_area
+        #       Then area_should_be(314)
+        #     }
+        def test_that(description=nil,&block)
+          raise "You must provide a block" if block.nil?
+          description = make_up_name(block) if description.nil?
+          test_name = "test_#{description.gsub(/\s+/,'_')}".to_sym
+          defined = instance_method(test_name) rescue false
+          raise "#{test_name} is already defined in #{self}" if defined
+          define_method(test_name, &block)
+        end
+
+        private 
+
+        def make_up_name(some_proc)
+          if some_proc.respond_to? :source_location
+            name,location = some_proc.source_location
+            "anonymous test at #{name}, line #{location}"
+          else
+            "anonymous test for proc #{some_proc.object_id}"
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/clean_test/version.rb

@@ -0,0 +1,5 @@
+module Clean # :nodoc:
+  module Test # :nodoc:
+    VERSION = "0.10.0"
+  end
+end

data/test/bootstrap.rb

@@ -0,0 +1,5 @@
+require 'simplecov'
+SimpleCov.start do
+  add_filter "/test/*.rb"
+end
+

data/test/test_any.rb

@@ -0,0 +1,144 @@
+require 'test/unit'
+require 'clean_test/test_case'
+
+class TestAny < Clean::Test::TestCase
+  test_that {
+    Given { random_seeded_for_negative_float }
+    When  { @number = any_number }
+    Then { 
+      assert @number < 0,"any_number should be negative, but we got #{@number}" 
+      assert @number.to_i != @number,"Expected a float"
+    }
+  }
+  test_that {
+    Given { random_seeded_for_positive }
+    When  { @number = any_number }
+    Then  { assert @number > 0,"any_number should be positive, but we got #{@number}" }
+  }
+
+  test_that {
+    Given { random_seeded_for_negative_float }
+    When  { @number = any_number :positive }
+    Then  { assert @number > 0,"We specified :positive, but got a negative" }
+  }
+
+  test_that {
+    Given { random_seeded_for_positive }
+    When  { @number = any_number :negative }
+    Then  { assert @number < 0,"We specified :negative, but got a positive" }
+  }
+
+  test_that {
+    Given { random_seeded_for_negative_float }
+    When  { @number = any_int }
+    Then  { 
+      assert @number < 0,"Expected int to be negative"
+      assert_equal @number.to_i,@number,"Expected an int, not a #{@number.class}" 
+    }
+  }
+
+  test_that {
+    Given { random_seeded_for_negative_float }
+    When  { @int = any_int :positive }
+    Then  { assert @int > 0,"We specified :positive, but got a negative" }
+  }
+
+  test_that {
+    Given { random_seeded_for_positive }
+    When  { @int = any_int :negative }
+    Then  { assert @int < 0,"We specified :negative, but got a positive" }
+  }
+
+  test_that {
+    Given { random_seeded_for_long_string }
+    When  { @string = any_string }
+    Then  { 
+      assert @string.length < 1441,"expected less than our rand value, but got #{@string.length}" 
+      assert_equal String,@string.class
+    }
+  }
+
+  test_that {
+    Given { random_seeded_for_long_string }
+    When  { @string = any_string :max => 255 }
+    Then  { 
+      assert @string.length <= 255,"Expected a string of less than 256 characters, got #{@string.length}" 
+      assert_equal String,@string.class
+    }
+  }
+
+  test_that {
+    Given { random_seeded_for_long_string }
+    When  { @string = any_string :min => 1000 }
+    Then  { 
+      assert @string.length > 1000,"Expected a string of at least 1500 characters, got one of #{@string.length} characters" 
+      assert_equal String,@string.class
+    }
+  }
+
+  test_that "we can register custom anys" do 
+    Given {
+      new_any :foo do
+        "bar"
+      end
+    }
+    When {
+      @result = any :foo
+    }
+    Then {
+      assert_equal 'bar',@result
+    }
+  end
+
+  test_that "custom anys can take options" do 
+    Given {
+      new_any :foo do |options|
+        if options[:baaz]
+          'quux'
+        else
+          'bar'
+        end
+      end
+    }
+    When {
+      @result = any :foo, :baaz => true
+    }
+    Then {
+      assert_equal 'quux',@result
+    }
+  end
+
+  [String,[Integer,Fixnum],Fixnum,Float,[Numeric,Float]].each do |klass|
+    test_that "can get an any #{klass}" do 
+      Given {
+        @class = @expected_class = klass
+        if @class.kind_of? Array
+          @expected_class = @class[1]
+          @class = @class[0]
+        end
+      }
+      When {
+        @value = any @class
+      }
+      Then {
+        assert_not_nil @value
+        assert_equal @expected_class,@value.class
+      }
+    end
+  end
+
+  private
+
+  def random_seeded_for_long_string
+    Random.srand(34)
+  end
+
+  def random_seeded_for_negative_float
+    Random.srand(45)
+  end
+
+  def random_seeded_for_positive
+    Random.srand(2)
+  end
+
+end

data/test/test_circle.rb

@@ -0,0 +1,17 @@
+require 'clean_test/test_case'
+
+class Circle
+  def initialize(radius)
+    @radius = radius
+  end
+
+  def area; (3.14 * @radius * @radius).to_i; end
+end
+
+class TestCircle < Clean::Test::TestCase
+  test_that {
+    Given { @circle = Circle.new(10) }
+    When  { @area = @circle.area     }
+    Then  { assert_equal 314,@area   }
+  }
+end