whitestone 1.0.1 → 1.0.2

data/Announcements.txt

@@ -0,0 +1,72 @@
+2012-01-27 ruby-talk
+
+Whitestone 1.0.1, a unit testing library, was released on 2012-01-02.  This
+update, 1.0.2, improves the implementation of float-equality testing,
+especially regarding numbers near zero. As it stands, floats are considered
+equal if their 14th significant figure is off by one. There is no provision
+for specifying a tolerance: it is supposed to just work, and if it doesn't
+then it's a bug.
+
+Key features of Whitestone include terse testing code, colorful and
+helpful output, custom assertions, a powerful and intuitive test
+runner, simple debugger integration. The homepage explains and
+demonstrates it well.
+
+Here are the assertion methods:
+  T  -- assert true
+  F  -- assert false
+  N  -- assert object is nil
+  Eq -- assert two objects are equal
+  Mt -- assert string matches regular expression
+  Id -- assert two objects are identical (same object)
+  E  -- assert error is raised
+  Ko -- assert an object is kind_of a class/module
+  Ft -- assert two floats are essentially equal
+  C  -- assert object is thrown
+
+Homepage: http://gsinclair.github.com/whitestone.html
+Code: http://github.com/gsinclair/whitestone
+Licence: MIT
+
+Regards,
+Gavin
+
+-------------------------------------------------------------------------------
+
+2012-01-02 ruby-talk
+
+Hi all,
+
+A long time ago, I imagined my ideal unit testing library.  In the middle of
+2010, I created it (using Suraj N Karaputi's "dfect" v2.1.0 as a starting point)
+and called it "attest", but never got around to releasing it.  Well now I have.
+Except the name "attest" is taken, so I renamed it "whitestone": it's the nicest
+sounding word in /usr/share/dict/words containing the word "test".
+
+It's not going to take over the testing world, but it's what keeps my Ruby
+projects in line.  If you're interested in testing libraries, you'll find it
+worth a look.  Note: "test" not "spec".  And there's no mocks, stubs, etc.
+either.  I'm not knocking those things, but they haven't been necessary for my
+projects.
+
+Here are the assertion methods:
+  T  -- assert true
+  F  -- assert false
+  N  -- assert object is nil
+  Eq -- assert two objects are equal
+  Mt -- assert string matches regular expression
+  Id -- assert two objects are identical (same object)
+  E  -- assert error is raised
+  Ko -- assert an object is kind_of a class/module
+  Ft -- assert two floats are essentially equal
+  C  -- assert object is thrown
+
+Key features include terse code, colorful and helpful output, custom assertions,
+a powerful and intuitive test runner, simple debugger integration.
+
+Homepage: http://gsinclair.github.com/whitestone.html
+Code: http://github.com/gsinclair/whitestone
+Licence: MIT
+
+Regards,
+Gavin

data/History.txt

@@ -1,3 +1,15 @@
+=== 1.0.2 / 2012-01-27
+
+* Improved the implementation and testing of float equality (Ft).
+  There is a backwards-incompatible change in that Ft no longer
+  accepts an epsilon argument. If Ft doesn't work for you with
+  the built-in value (1e-13) then it's probably a bug in this
+  library. Theoretically, this should be version 2.0.0, but that
+  seems silly and I don't think anyone will be affected. Sorry
+  if you are.
+
+* Correct Ruby dependency set in the gemspec (>= 1.8.7).
+
 === 1.0.1 / 2012-01-02
 
 * Correction in README.txt

data/doc/whitestone.markdown

@@ -795,7 +795,11 @@ They are hardcoded and it would be a major effort to customise them!
 ### History
 
 * July 2010: originally developed under the name 'attest' but not released
-* 1 January 2012: version 1.0.0
+* 2 JAN 2012: version 1.0.0
+* 2 JAN 2012: version 1.0.1 with corrected README.txt
+* 27 JAN 2012: version 1.0.2 with improved implementation and testing of float
+  equality (Ft). Note slight backwards incompatibility: Ft no longer accepts
+  'epsilon' argument.
 
 ### Future plans
 

data/lib/whitestone/assertion_classes.rb

@@ -263,25 +263,52 @@ module Whitestone
     end  # class Assertion::KindOf
 
     class FloatEqual < Base
-      EPSILON = 0.000001
+      # Experiments have shown this value to be a reliable threshold for
+      # ratio-based comparison, but that may be machine-dependant and may be
+      # overturned by more experiments. With this epsilon, floats appear to be
+      # considered equal if their first 13 significant figures are the same.
+      #
+      # Example: 1.1 - 1.0 gives 0.10000000000000009, which differs from 0.1 in
+      # the 17th digit. Therefore, I could, and perhaps should, be more
+      # aggressive and set an even smaller ratio like 1e-16. But I assume that
+      # complicated calculations involving floats would compound representation
+      # errors, so at the moment I choose to be conservative.
+      #
+      # It is by design that the programmer cannot specify a value for epsilon.
+      # This should "just work", and if someone finds a case where this epsilon
+      # is not sufficient for normal use, it is probably a bug in this library
+      # that needs to be addressed. If someone wants to experiment with
+      # different epsilon values, then they can do, for example
+      #   WhiteStone::Assertion::FloatEqual.const_set :EPSILON, 1e-16
+      EPSILON = 1e-13
       def initialize(mode, *args, &block)
         super
         no_block_allowed
         type_check(args, Numeric)
-        @actual, @expected, @epsilon = two_or_three_arguments(args).map { |x| x.to_f }
-        @epsilon ||= EPSILON
+        @actual, @expected = two_arguments(args).map { |x| x.to_f }
+        @epsilon = EPSILON
       end
       def run
-        if @actual.zero? or @expected.zero?
-          # There's no scale, so we can only go on difference.
-          (@actual - @expected) < @epsilon
+        if @actual.zero? and @expected.zero?
+          true
+        elsif @actual.zero? or @expected.zero?
+          # Precisely one of our values is zero. Ratios don't work in this case,
+          # so we work around by adding 0.01 to both to get them away from zero.
+          # We check first to be sure that this would actually work.
+          if (@actual - @expected).abs < 0.00001
+            floats_essentially_equal?(@actual + 0.01, @expected + 0.01)
+          else
+            # They differ by more than 0.00001 so they're clearly not equal enough.
+            false
+          end
         else
-          # We go by ratio. The ratio of two equal numbers is one, so the ratio
-          # of two practically-equal floats will be very nearly one.
-          @ratio = (@actual/@expected - 1).abs
-          @ratio < @epsilon
+          floats_essentially_equal?(@actual, @expected)
         end
       end
+      def floats_essentially_equal?(a, b)
+        @ratio = (a/b - 1).abs
+        @ratio < EPSILON
+      end
       def message
         String.new.tap { |str|
           case @mode
@@ -289,7 +316,7 @@ module Whitestone
             str << Col["Float equality test failed"].yb
             str << "\n" << Col["  Should be: #{@expected.inspect}"].gb
             str << "\n" << Col["        Was: #{@actual.inspect}"].rb
-            str << "\n" <<     "    Epsilon: #{@epsilon}"
+            str << "\n" <<     "    Epsilon: #{EPSILON}"
             if @ratio
               str << "\n" <<   "      Ratio: #{@ratio}"
             end
@@ -298,7 +325,7 @@ module Whitestone
             str << Col[line].yb
             str << "\n" << Col["    Value 1: ", @actual.inspect  ].fmt(:yb, :rb)
             str << "\n" << Col["    Value 2: ", @expected.inspect].fmt(:yb, :rb)
-            str << "\n" <<     "    Epsilon: #{@epsilon}"
+            str << "\n" <<     "    Epsilon: #{EPSILON}"
             if @ratio
               str << "\n" <<   "      Ratio: #{@ratio}"
             end

data/lib/whitestone/version.rb

@@ -1,3 +1,3 @@
 module Whitestone
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

data/test/whitestone_test.rb

@@ -122,28 +122,41 @@ D "Assertion classes" do
   end
 
   D 'Ft' do
-    Ft  Math::PI, 3.141592    # default tolerance 0.00001
-    Ft! Math::PI, 3.14
-    Ft  Math::PI, 3.14, 0.1   # tolerance for this line is 0.1
-    Ft  Math::PI, 3.14, 0.01
-    Ft  Math::PI, 3.14, 0.001
-    Ft! Math::PI, 3.14, 0.0001
+    D 'basic' do
+      Ft 45.44332211, 45.443322110000000000001
+      Ft! 109.123456, 109.123457   # These are too close to be considered
+                                   # essentially equal.
+    end
     D 'test values of massively differing magnitude' do
       a = 0.000000000837
       b = 0.0000000004315    # a and b are _not_ "essentially" equal
-      c = 100.000000000837
-      d = 100.0000000004315  # c and d _are_ "essentially" equal
       Ft! a, b
       Ft! b, a
+      c = 100.000000000000837
+      d = 100.0000000000004315  # c and d _are_ "essentially" equal
       Ft  c, d
       Ft  d, c
     end
+    D "anomolies like (1.1 - 1.0) does not equal 0.1" do
+      Ft 1.1 - 1.0, 0.1
+      Ft 1.1 - 1.0 - 0.1, 0.0
+      Ft 0.1 + 0.1, 0.2
+      Ft 0.2 + 0.1, 0.3  # This doesn't work when using ==
+      Ft 0.3 + 0.1, 0.4
+      Ft 0.4 + 0.1, 0.5
+      Ft 0.5 + 0.1, 0.6
+      Ft 0.6 + 0.1, 0.7
+      Ft 0.7 + 0.1, 0.8  # Nor does this one
+      Ft 0.8 + 0.1, 0.9
+      Ft 0.9 + 0.1, 1.0
+    end
     D 'integer values' do
       Ft 4,   4
       Ft 4.0, 4
       Ft 4,   4.0
       Ft -13, -13
       Ft -13.0, -13
+      Ft! 4, 5
     end
     D 'zero' do
       Ft 0,   0
@@ -154,26 +167,84 @@ D "Assertion classes" do
       Ft -1.1102230246251565e-16, 0.0
     end
     D 'numbers near zero' do
-      Ft  0, 0.00000000000124, 0.0000000001
-      Ft  0, 0.00000000000124, 0.00000000001
-      Ft  0, 0.00000000000124, 0.000000000001
-      Ft  0, 0.00000000000124, 0.0000000000001
-      # The next test fails but I don't know what we really should expect.
-      # Ft! 0, 0.00000000000124, 1e-25
+      Ft! 0, 0.001
+      Ft! 0, 0.0001
+      Ft! 0, 0.00001
+      Ft! 0, 0.000001
+      Ft! 0, 0.0000001
+      Ft! 0, 0.00000001
+      Ft! 0, 0.000000001
+      Ft! 0, 0.0000000001
+      Ft! 0, 0.00000000001
+      Ft! 0, 0.000000000001
+      Ft! 0, 0.0000000000001
+      Ft! 0, 0.00000000000001
+      Ft  0, 0.000000000000001      # This is the first float that is
+      Ft  0, 0.0000000000000001     # essentially equal to zero.
+      Ft  0, 0.00000000000000001
+      Ft  0, 0.000000000000000001
     end
     D '(near) equal and negative' do
-      a = -2.0000051298352
-      b = -2.0000051298336
-      Ft a, b, 0.000000001
-      Ft b, a, 0.000000001
-    end
-    D 'tiny numbers' do
-      Ft  1.234567e-50, 1.234568e-50
-      Ft! 1.234567e-50, 1.234567e-51
-    end
-    D 'huge numbers' do
-      Ft  1.234567e50, 1.234568e50
-      Ft! 1.234567e50, 1.234567e51
+      a = -2.000000000051298352
+      b = -2.000000000051298336
+      Ft a, b
+      Ft b, a
+    end
+    D "13th digit differs: not equal enough" do
+      Ft! 1.234567890123e50,  1.23456789122e50
+      Ft! 1.234567890123e40,  1.23456789122e40
+      Ft! 1.234567890123e30,  1.23456789122e30
+      Ft! 1.234567890123e20,  1.23456789122e20
+      Ft! 1.234567890123e10,  1.23456789122e10
+      Ft! 1.234567890123e0,   1.23456789122e0
+      Ft! 1.234567890123e-10, 1.23456789122e-10
+      Ft! 1.234567890123e-20, 1.23456789122e-20
+      Ft! 1.234567890123e-30, 1.23456789122e-30
+      Ft! 1.234567890123e-40, 1.23456789122e-40
+    end
+    D "14th digit differs: equal enough" do
+      Ft 1.2345678901234e90,  1.2345678901233e90
+      Ft 1.2345678901234e90,  1.2345678901234e90
+      Ft 1.2345678901234e90,  1.2345678901235e90
+      Ft 1.2345678901234e50,  1.2345678901233e50
+      Ft 1.2345678901234e50,  1.2345678901234e50
+      Ft 1.2345678901234e50,  1.2345678901235e50
+      Ft 1.2345678901234e10,  1.2345678901233e10
+      Ft 1.2345678901234e10,  1.2345678901234e10
+      Ft 1.2345678901234e10,  1.2345678901235e10
+      Ft 1.2345678901234e0,   1.2345678901233e0
+      Ft 1.2345678901234e0,   1.2345678901234e0
+      Ft 1.2345678901234e0,   1.2345678901235e0
+      Ft 1.2345678901234e-10, 1.2345678901233e-10
+      Ft 1.2345678901234e-10, 1.2345678901234e-10
+      Ft 1.2345678901234e-10, 1.2345678901235e-10
+      Ft 1.2345678901234e-50, 1.2345678901233e-50
+      Ft 1.2345678901234e-50, 1.2345678901234e-50
+      Ft 1.2345678901234e-50, 1.2345678901235e-50
+      Ft 1.2345678901234e-90, 1.2345678901233e-90
+      Ft 1.2345678901234e-90, 1.2345678901234e-90
+      Ft 1.2345678901234e-90, 1.2345678901235e-90
+      D "but it can only be off by 1" do
+        Ft! 1.2345678901234e90, 1.2345678901231e90
+        Ft! 1.2345678901234e90, 1.2345678901232e90
+        Ft! 1.2345678901234e90, 1.2345678901236e90
+        Ft! 1.2345678901234e90, 1.2345678901237e90
+        Ft! 1.2345678901234e10, 1.2345678901231e10
+        Ft! 1.2345678901234e10, 1.2345678901232e10
+        Ft! 1.2345678901234e10, 1.2345678901236e10
+        Ft! 1.2345678901234e10, 1.2345678901237e10
+        Ft! 1.2345678901234e-10, 1.2345678901231e-10
+        Ft! 1.2345678901234e-10, 1.2345678901232e-10
+        Ft! 1.2345678901234e-10, 1.2345678901236e-10
+        Ft! 1.2345678901234e-10, 1.2345678901237e-10
+        Ft! 1.2345678901234e-90, 1.2345678901231e-90
+        Ft! 1.2345678901234e-90, 1.2345678901232e-90
+        Ft! 1.2345678901234e-90, 1.2345678901236e-90
+        Ft! 1.2345678901234e-90, 1.2345678901237e-90
+      end
+    end
+    D "Ft does not allow epsilon argument" do
+      E(AssertionSpecificationError) { Ft? 3.14159265, 3.1415, 0.01 }
     end
   end
 

data/whitestone.gemspec

@@ -27,5 +27,5 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency "bundler"
 
-  s.required_ruby_version = '>= 1.8.6'    # Not sure about this.
+  s.required_ruby_version = '>= 1.8.7'    # Doesn't work on 1.8.6 (tested).
 end

metadata

@@ -1,61 +1,61 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: whitestone
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 1.0.2
   prerelease: 
-  version: 1.0.1
 platform: ruby
-authors: 
+authors:
 - Gavin Sinclair
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-01-01 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-01-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: col
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2152166400 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 1.0.1
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: differ
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *2152166400
+- !ruby/object:Gem::Dependency
+  name: differ
+  requirement: &2152165520 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "0.1"
+      - !ruby/object:Gem::Version
+        version: '0.1'
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: bundler
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *2152165520
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: &2152165060 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id003
-description: "    Unit testing library with colourful, helpful error messages,\n    small testing code footprint, good debugger integration.\n    (Derivative work of Dfect/Detest.)\n"
-email: 
+  prerelease: false
+  version_requirements: *2152165060
+description: ! "    Unit testing library with colourful, helpful error messages,\n
+  \   small testing code footprint, good debugger integration.\n    (Derivative work
+  of Dfect/Detest.)\n"
+email:
 - gsinclair@gmail.com
-executables: 
+executables:
 - whitestone
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
+- Announcements.txt
 - Gemfile
 - History.txt
 - LICENSE
@@ -94,33 +94,31 @@ files:
 - whitestone.gemspec
 homepage: http://gsinclair.github.com/whitestone.html
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: 1.8.6
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.8.7
+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: ""
-rubygems_version: 1.8.11
+rubyforge_project: ''
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Succinct and simple unit testing
-test_files: 
+test_files:
 - test/_setup.rb
 - test/custom_assertions.rb
 - test/insulation.rb
 - test/whitestone_test.rb
+has_rdoc: