test_unit-given 0.9.3 → 0.9.4

data/README.rdoc

@@ -6,16 +6,31 @@ License:: Distributes under the Apache License, see LICENSE.txt in the source di
 
 Get your Test::Unit test cases fluent, without RSpec, magic, or crazy meta-programming.
 
-This gives you two simple tools to make your test cases readable:
+This gives you some simple tools to make your test cases readable:
 
 * Given/When/Then to delineate which parts of your tests do what
 * A method "test_that" that defines test cases with strings instead of method names (much like +test+ in Rails tests)
+* A module Any that defines methods to create arbitrary values, so it's clear in your tests what values are what, but without having to use long method names like `Faker::Lorem.words(2).join(' ')`
 
 == Install
 
     gem install test_unit-given
 
-== Example
+== `test_that`
+
+    class SomeTest < Test::Unit::Given::TestCase
+      test_that {
+        # do a test
+      }
+
+      test_that "description of our test" do
+        # do a test
+      end
+    end
+
+Yes, just like `test` from Rails, but without having to have ActiveSupport
+
+== Given/When/Then
 
     class Circle
       def initialize(radius)
@@ -212,6 +227,67 @@ Again, things are a bit out of order, but if you invert Then and When, you'll st
       end
     end
 
+== Any
+
+Our tests tend to have a lot of arbitrary or meaningless values.  They also have a lot of very important and meaningfule values.  Often both of these are expressed as literals in our code.  What the Any module gives you is the ability to hide arbitrary values behind a method call.  This will ensure that the values truly are arbitrary, and will also mean that any literals left in your tests are important.  For example, you might have a test like this:
+
+
+    def test_something
+      service = mock()
+      service.expects(:remote_call).with({ :method => 'process', :amount => 45.6}).returns(87)
+      object_under_test = ObjectUnderTest.new('foo',service)
+
+      assert_equal 8700,object_under_test.doit
+    end
+
+What's being tested here?  What values are meaningfule and which aren't?  Let's apply Any to make it clear:
+
+    def test_something
+      service = mock()
+      service_return = any_int
+      service.expects(:remote_call).with({ :method => any_string, :amount => any_number}).returns(service_return)
+      object_under_test = ObjectUnderTest.new(any_string,service)
+
+      assert_equal (service_return * 100),object_under_test.doit
+    end
+
+*Now* it's clear that we're expecting our object under test to multiple the return of our service call by 100.  The only value that has any meaning to this test is the integer 100, and that's the only literal that's there.  Beauty.
+
+=== What about Faker or Sham?
+
+They simply don't provide a concise API to do this, nor do they really communicate this concept.  We aren't passing _fake_ strings or numbers, we're passing *arbitrary* strings and numbers.  It's worth making that clear in our tests that certainly values that must not be nil, don't matter to the test.  That they are random each time keeps us honest.
+
+=== What if I need some sort of restriction?
+
+Two ways to do that.  The built-in any_* methods provide limited options:
+
+    def test_truncate
+      person = Person.new
+      person.name = any_string :min => 256
+      person.age = any_int :positive
+      person.save!
+      assert_equal 255,person.name.length
+    end
+
+The second way is to create your own any:
+
+    def setup
+      new_any :age do |options|
+        age = any_number % 80
+        age += 18 if options == :adult
+        age
+      end
+    end
+
+    def test_truncate
+      person = Person.new
+      person.name = any_string :min => 256
+      person.age = any :age, :adult
+      person.save!
+      assert_equal 255,person.name.length
+    end
+
+
 == WTF?  Why?
 
 Just because you're using Test::Unit doesn't mean you can't write fluent, easy to understand tests.

data/Rakefile

@@ -21,7 +21,7 @@ RDoc::Task.new do |rd|
   rd.main = "README.rdoc"
   rd.generator = 'hanna'
   rd.rdoc_files.include("README.rdoc","lib/**/*.rb","bin/**/*")
-  rd.title = 'Methadone - Power Up your Command Line Apps'
+  rd.title = 'Test::Unit::Given - make your unit tests clear'
   rd.markup = "tomdoc"
 end
 CLOBBER << 'coverage'

data/lib/test/unit/given/any.rb

@@ -0,0 +1,137 @@
+require 'faker'
+
+module Test
+  module Unit
+    module Given
+      # 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.
+      module Any
+        MAX_RAND = 50000
+
+        # 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|
+          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|
+          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|
+          (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
+end
+

data/lib/test/unit/given/test_case.rb

@@ -1,5 +1,6 @@
 require 'test/unit'
 require 'test/unit/given/simple'
+require 'test/unit/given/any'
 require 'test/unit/given/test_that'
 
 module Test
@@ -21,6 +22,7 @@ module Test
       class TestCase < Test::Unit::TestCase
         include Simple
         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

data/lib/test/unit/given/version.rb

@@ -1,7 +1,7 @@
 module Test
   module Unit
     module Given
-      VERSION = "0.9.3"
+      VERSION = "0.9.4"
     end
   end
 end

data/test/test_any.rb

@@ -0,0 +1,144 @@
+require 'test/unit'
+require 'test/unit/given'
+
+class TestAny < Test::Unit::Given::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_unit-given.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |s|
   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"]
+  s.add_dependency("faker")
   s.add_development_dependency("rdoc")
   s.add_development_dependency("rake")
   s.add_development_dependency("simplecov")

metadata

@@ -1,105 +1,113 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: test_unit-given
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.9.4
   prerelease: 
-  version: 0.9.3
 platform: ruby
-authors: 
-  - David Copeland
+authors:
+- David Copeland
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-11-21 00:00:00 Z
-dependencies: 
-  - !ruby/object:Gem::Dependency 
-    name: rdoc
-    prerelease: false
-    requirement: &id001 !ruby/object:Gem::Requirement 
-      none: false
-      requirements: 
-        - - ">="
-          - !ruby/object:Gem::Version 
-            version: "0"
-    type: :development
-    version_requirements: *id001
-  - !ruby/object:Gem::Dependency 
-    name: rake
-    prerelease: false
-    requirement: &id002 !ruby/object:Gem::Requirement 
-      none: false
-      requirements: 
-        - - ">="
-          - !ruby/object:Gem::Version 
-            version: "0"
-    type: :development
-    version_requirements: *id002
-  - !ruby/object:Gem::Dependency 
-    name: simplecov
-    prerelease: false
-    requirement: &id003 !ruby/object:Gem::Requirement 
-      none: false
-      requirements: 
-        - - ">="
-          - !ruby/object:Gem::Version 
-            version: "0"
-    type: :development
-    version_requirements: *id003
-description: We don't need no stinkin' RSpec!  Get all the fluency you want in your Test::Unit tests, with no magic required, using straight Ruby syntax
-email: 
-  - davetron5000@gmail.com
+date: 2011-11-23 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: &70233017866940 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70233017866940
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: &70233017866520 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70233017866520
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70233017866100 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70233017866100
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: &70233000056260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70233000056260
+description: We don't need no stinkin' RSpec!  Get all the fluency you want in your
+  Test::Unit tests, with no magic required, using straight Ruby syntax
+email:
+- davetron5000@gmail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
-  - .gitignore
-  - .rvmrc
-  - Gemfile
-  - LICENSE.txt
-  - README.rdoc
-  - Rakefile
-  - lib/test/unit/given.rb
-  - lib/test/unit/given/simple.rb
-  - lib/test/unit/given/test_case.rb
-  - lib/test/unit/given/test_that.rb
-  - lib/test/unit/given/version.rb
-  - test/bootstrap.rb
-  - test/test_circle.rb
-  - test/test_simple_given.rb
-  - test/test_test_that.rb
-  - test_unit-given.gemspec
-homepage: ""
+files:
+- .gitignore
+- .rvmrc
+- Gemfile
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- lib/test/unit/given.rb
+- lib/test/unit/given/any.rb
+- lib/test/unit/given/simple.rb
+- lib/test/unit/given/test_case.rb
+- lib/test/unit/given/test_that.rb
+- lib/test/unit/given/version.rb
+- test/bootstrap.rb
+- test/test_any.rb
+- test/test_circle.rb
+- test/test_simple_given.rb
+- test/test_test_that.rb
+- test_unit-given.gemspec
+homepage: ''
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
-  - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+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 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: test_unit-given
-rubygems_version: 1.8.9
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Use Given/When/Then in your Test::Unit tests
-test_files: 
-  - test/bootstrap.rb
-  - test/test_circle.rb
-  - test/test_simple_given.rb
-  - test/test_test_that.rb
+test_files:
+- test/bootstrap.rb
+- test/test_any.rb
+- test/test_circle.rb
+- test/test_simple_given.rb
+- test/test_test_that.rb