benchmark_unit 0.0.1 → 0.1

data/CHANGELOG

@@ -1,2 +1,2 @@
 
-v0.0.1. First release.
+v0.1. First release.

data/Manifest

@@ -3,6 +3,7 @@ lib/benchmark/assertions.rb
 lib/benchmark/float.rb
 lib/benchmark/ruby_seconds.rb
 lib/benchmark/unit.rb
+lib/benchmark_unit.rb
 LICENSE
 Manifest
 README

data/README

@@ -1,10 +1,47 @@
 
 benchmark_unit
 
-Adds machine-independent benchmark assertions to your unit tests.
+Machine-independent benchmark assertions for your unit tests.
 
 == License
 
 Copyright 2007 Cloudburst, LLC. See included LICENSE file.
 
 The public certificate for this gem is at http://rubyforge.org/frs/download.php/25331/evan_weaver-original-public_cert.pem.
+
+== Features
+
+* Test::Unit-compatible
+* machine-independent measurement units
+
+== Installation
+
+  sudo gem install benchmark_unit
+
+== Usage
+
+First, require the library. Then, in a regular Test::Unit::TestCase, call either <tt>assert_faster</tt> or <tt>assert_slower</tt>. Pass a number of RubySeconds and a block to benchmark. 
+
+  require 'benchmark/unit'
+  
+  class MyTest < Test::Unit::TestCase
+    
+    def test_speed_of_critical_method
+      assert_faster(3) do
+        MyCriticalMethod("data")
+      end
+    end
+      
+  end
+
+You do not have to manually run the block multiple times; the library does that for you.
+  
+To find how many RubySeconds to start with, just omit the argument to the <tt>assert_faster</tt> or <tt>assert_slower</tt> call. The test will fail and report how long your block took. Add a little bit and use that as your initial failure point.
+
+See Benchmark::RubySeconds for more details.
+
+== Reporting problems
+
+* http://rubyforge.org/forum/forum.php?forum_id=20547
+
+Patches and contributions are very welcome. Please note that contributors are required to assign copyright for their additions to Cloudburst, LLC.

data/benchmark_unit.gemspec

@@ -1,25 +1,25 @@
 
-# Gem::Specification for Benchmark_unit-0.0.1
+# Gem::Specification for Benchmark_unit-0.1
 # Originally generated by Echoe
 
 Gem::Specification.new do |s|
   s.name = %q{benchmark_unit}
-  s.version = "0.0.1"
+  s.version = "0.1"
 
   s.specification_version = 2 if s.respond_to? :specification_version=
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Evan Weaver"]
   s.date = %q{2008-01-08}
-  s.description = %q{Adds machine-independent benchmark assertions to your unit tests.}
+  s.description = %q{Machine-independent benchmark assertions for your unit tests.}
   s.email = %q{}
-  s.files = ["CHANGELOG", "lib/benchmark/assertions.rb", "lib/benchmark/float.rb", "lib/benchmark/ruby_seconds.rb", "lib/benchmark/unit.rb", "LICENSE", "Manifest", "README", "test/unit/benchmark_unit_test.rb", "benchmark_unit.gemspec"]
+  s.files = ["CHANGELOG", "lib/benchmark/assertions.rb", "lib/benchmark/float.rb", "lib/benchmark/ruby_seconds.rb", "lib/benchmark/unit.rb", "lib/benchmark_unit.rb", "LICENSE", "Manifest", "README", "test/unit/benchmark_unit_test.rb", "benchmark_unit.gemspec"]
   s.has_rdoc = true
   s.homepage = %q{http://blog.evanweaver.com/files/doc/fauna/benchmark_unit/}
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{fauna}
   s.rubygems_version = %q{1.0.1}
-  s.summary = %q{Adds machine-independent benchmark assertions to your unit tests.}
+  s.summary = %q{Machine-independent benchmark assertions for your unit tests.}
   s.test_files = ["test/unit/benchmark_unit_test.rb"]
 end
 
@@ -32,9 +32,9 @@ end
 # Echoe.new("benchmark_unit") do |p|
 #   p.author = "Evan Weaver" 
 #   p.project = "fauna"
-#   p.summary = "Adds machine-independent benchmark assertions to your unit tests."  
+#   p.summary = "Machine-independent benchmark assertions for your unit tests."  
 #   p.url = "http://blog.evanweaver.com/files/doc/fauna/benchmark_unit/"  
 #   p.docs_host = 'blog.evanweaver.com:~/www/bax/public/files/doc/'
 #   p.require_signed = true  
-#   p.test_pattern = ["**/test/**/*.rb"]
+#   p.test_pattern = ["test/**/*.rb"]
 # end

data/lib/benchmark/assertions.rb

@@ -1,21 +1,29 @@
 
-require 'test/unit/assertions'
+require 'test/unit'
 
-module Test
+module Benchmark #:nodoc:
   module Unit
     module Assertions
       
-      def assert_faster(target = 1/0.0, &block)
-        compare_benchmark(target, :faster, &block)
+      # Assert that the average execution time of the block is faster than the target number of RubySeconds (i.e., takes less time). Default target is 0 (everything fails).
+      def assert_faster(target = 0, &block)
+        clean_backtrace do
+          compare_benchmark(target, :faster, &block)
+        end
       end
       
-      def assert_slower(target = 0, &block) # Infinity
-        compare_benchmark(target, :slower, &block)
+      # Assert that the average execution time of the block is slower than the target number of RubySeconds (i.e., takes more time). Default target is Infinity (everything fails).
+      def assert_slower(target = 1/0.0, &block) # Infinity
+        clean_backtrace do
+          compare_benchmark(target, :slower, &block)
+        end
       end      
       
       private
       
       def compare_benchmark(target, operator)
+        raise unless [:faster, :slower].include? operator
+      
         time, multiplier = 0, 1
 
         while (time < 0.01) do
@@ -39,15 +47,39 @@ module Test
         end
         
         time = total / iterations
-        message = "Time #{time.inspect} expected to be #{operator} than #{target.inspect}."
+        message = "<#{time.inspect} RubySeconds> is not #{operator} than #{target.inspect} RubySeconds."
         
-        if operator == :faster        
-          assert((time < target), message)
-        elsif operator == :slower
-          assert((time > target), message)
+        assert_block message do 
+          if operator == :faster        
+            time < target
+          elsif operator == :slower
+            time > target
+          end
         end
+
       end
-      
+
+      # Strip our library files from the assertion backtrace.
+      def clean_backtrace(&block) #:nodoc:
+        # Modified from Rails' version
+        begin
+          yield
+        rescue Object => error
+          library_path = Regexp.new(
+            File.expand_path("#{File.dirname(__FILE__)}/(assertions|unit)") + 
+            '|benchmark.rb.*measure'
+          )
+          error.backtrace.reject! { |line| File.expand_path(line) =~ library_path }
+          raise
+        end
+      end
+          
     end
   end
 end
+
+#:stopdoc:
+
+class Test::Unit::TestCase
+  include Benchmark::Unit::Assertions
+end

data/lib/benchmark/float.rb

@@ -1,5 +1,6 @@
 
 class Float
+  # Return <tt>self</tt> in RubySeconds for this machine.
   def to_ruby_seconds
     Benchmark::RubySeconds.new(self)
   end  

data/lib/benchmark/ruby_seconds.rb

@@ -1,38 +1,38 @@
 
-module Benchmark
+module Benchmark #:nodoc:
+
+=begin rdoc
+RubySeconds are a machine-independent time measurement derived from benchmarking your hardware on some typical Ruby code. A RubySecond should be consistent enough for testing purposes across most architectures--hopefully within a 1/2 order of magnitude.
+
+To see what your machine's RubySecond is in clock-seconds, call Benchmark::RubySeconds.size. 
+=end
   class RubySeconds
   
     PRECISION = 0.05
       
-    attr_accessor :value
+    attr_reader :value
       
-    # Create a RubySeconds object from wall clock seconds.
+    # Create a RubySeconds object from clock-seconds.
     def initialize(seconds)
       @value = seconds.to_f / RubySeconds.size
     end
     
     # Delegate to the float. Inheriting from Float doesn't work well.
-    def method_missing(*args)
+    def method_missing(*args) #:nodoc:
       @value.send(*args)
     end
     
-    def to_s
+    def to_s #:nodoc:
       @value.to_s
     end
   
     class << self
     
-      # Measure the "standard" Ruby unit of time.
-      def measure
-        Benchmark.measure do
-          4.times { quanta }
-        end.total / 4.0
-      end
-      
-      # Approach a stable unit size and memoize it.
+      # Return the size of a single RubySecond in clock-seconds for this machine.
       def size
         @size ||= begin
           last, size = 0, measure
+          # Gradually approach a stable unit size, up to PRECISION %
           while (size < last or (size - last) / size > PRECISION) do
             last, size = size, measure
           end
@@ -40,12 +40,19 @@ module Benchmark
         end
       end
       
-      private 
+      protected
+
+      # Measure the "standard" Ruby unit of time on this machine.
+      def measure 
+        Benchmark.measure do
+          4.times { quanta }
+        end.total / 4.0
+      end      
       
-      # Perform some common Ruby operations so we can measure how long they take.
+      # Perform some typical Ruby operations.
       def quanta
         # Allocate things
-        array = [:symbol, "a = 3 if true", 2, Math::PI**2, "large string"*30] * 100
+        array = [[:symbol, "a = 3 if true", 2, Math::PI**2, "large string"*30]] * 100
         # Re-assign
         array.flatten!
         # Process things with a closure
@@ -64,6 +71,7 @@ module Benchmark
         recurse(20)
       end
       
+      # Recurse <tt>i</tt> times.
       def recurse(i)
         recurse(i - 1) if i > 0
       end

data/lib/benchmark/unit.rb

@@ -1,18 +1,21 @@
 
 require 'benchmark'
 
-require 'rubygems'
-require 'ruby-debug'; Debugger.start
+if ENV['DEBUG']
+  require 'rubygems'
+  require 'ruby-debug'; Debugger.start
+end
 
 require 'benchmark/ruby_seconds'
 require 'benchmark/assertions'
 require 'benchmark/float'
 
-module Benchmark
+module Benchmark #:nodoc:
   module Unit
 
     CLOCK_TARGET = 2
     
+    # Measure a single run of a block in RubySeconds.
     def self.measure
       RubySeconds.new(
         Benchmark.measure do

data/lib/benchmark_unit.rb

@@ -0,0 +1,2 @@
+
+require 'benchmark/unit'

data/test/unit/benchmark_unit_test.rb

@@ -1,33 +1,63 @@
 
 $LOAD_PATH << File.dirname(__FILE__) + "/../../lib"
 
+# Test both requires
 require 'benchmark/unit'
-require 'test/unit'
+require 'benchmark_unit'
 
-# STDERR.puts "RubySeconds.size is #{Benchmark::RubySeconds.size}"
+STDERR.puts "RubySeconds.size is #{Benchmark::RubySeconds.size}" if ENV['DEBUG']
 
 class BenchmarkUnitTest < Test::Unit::TestCase
   
   def test_faster
-    assert_faster do
-      # Do nothing
-    end 
     assert_faster(3) do
       "string" * 100
     end
+    
+    assert_raises Test::Unit::AssertionFailedError do
+      assert_faster do
+        # Do nothing
+      end 
+    end
   end
 
   def test_slower
-    assert_slower do
-      "string" * 100
-    end   
     assert_slower(1.1) do
       "string" * 30000000
     end
-  end 
+    
+    assert_raises Test::Unit::AssertionFailedError do
+      assert_slower do
+        "string" * 3000
+      end   
+    end
+  end
+  
+  #  def test_sleep
+  #    # Loops forever due to thread scheduling issues
+  #    assert_slower(2) do
+  #      sleep(3 * Benchmark::RubySeconds.size)
+  #    end    
+  #  end
   
   def test_failed_assertion_has_clean_backtrace
-    # XXX Todo
+    begin
+      assert_slower(3) do
+        "fast"
+      end
+    rescue Test::Unit::AssertionFailedError => e
+      assert e.backtrace.to_s !~ /compare_benchmark|benchmark.rb/
+    end
+  end
+
+  def test_exception_has_clean_backtrace
+    begin
+      assert_faster(3) do
+        raise "o crap"
+      end
+    rescue RuntimeError => e
+      assert e.backtrace.to_s !~ /compare_benchmark|benchmark.rb/
+    end
   end
   
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: benchmark_unit
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: "0.1"
 platform: ruby
 authors: 
 - Evan Weaver
@@ -34,7 +34,7 @@ date: 2008-01-08 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
-description: Adds machine-independent benchmark assertions to your unit tests.
+description: Machine-independent benchmark assertions for your unit tests.
 email: ""
 executables: []
 
@@ -48,6 +48,7 @@ files:
 - lib/benchmark/float.rb
 - lib/benchmark/ruby_seconds.rb
 - lib/benchmark/unit.rb
+- lib/benchmark_unit.rb
 - LICENSE
 - Manifest
 - README
@@ -78,6 +79,6 @@ rubyforge_project: fauna
 rubygems_version: 1.0.1
 signing_key: 
 specification_version: 2
-summary: Adds machine-independent benchmark assertions to your unit tests.
+summary: Machine-independent benchmark assertions for your unit tests.
 test_files: 
 - test/unit/benchmark_unit_test.rb

metadata.gz.sig

@@ -1 +1,2 @@
-N>�"�aĿ/��G��rO��Gl.	�J	Bt3�hbl�k�g�aS�Q�(m�갳]�d/�����=���;��7_JV͔z����@Bm�Q]P��(G��.��0�:���N���$`g�S��
G	�C��6�3]��!�����>�ߵP�7V�LE��ya��|[w�M���*�(��=��� r�:&�n�|'�YgQ��D�?��b��U�) �ڵ4J�[M�Mz�`����~�
k%@��7"��T �g�
+��Dm��v "�t��ʄ�2xl�@�rb��E��.w�~`g��p��7.S�-	|d#��/��%v�s@�
fo-K��t���c��R]x…&�#XED�,�E>h�d6����V�1j�>����ns���
+�5:�d������x��8�?���3��!����(��1#���t�����T���gC�e��u�X`�fE����<)TdžA�����������G{��K���g���xbLH	�=��