waitfor 0.0.1 → 0.1.0

data/Manifest.txt

@@ -6,8 +6,11 @@ lib/waitfor.rb
 lib/waitfor/fixnum.rb
 lib/waitfor/timer.rb
 lib/waitfor/version.rb
-spec/waitfor_spec.rb
-spec/timer_spec.rb
+lib/waitfor/waitfor_timeout_error.rb
 spec/fixnum_spec.rb
 spec/spec.opts
-spec/spec_helper.rb
+spec/spec_helper.rb
+spec/spec_helper_spec.rb
+spec/waitfor_spec.rb
+spec/timer_spec.rb
+spec/waitfor_timeout_error_spec.rb

data/README.rdoc

@@ -4,44 +4,72 @@
 
 == DESCRIPTION:
 
-Continuously executes a Block until the Block returns true or the time limit is reached, at which point an error is raised.
+Blocks execution until a specified statement becomes true, or a specified time interval is reached, at which point an error is raised.
+
 Useful for strengthening tests involving asynchronous or non-blocking operations.
 
 == FEATURES/PROBLEMS:
 
-* Accepts arguments of second / seconds or minute / minutes
-* Allows for custom RuntimeError messages
-
-* No custom Error support yet
-* Resolution of delay between Block executions is currently 1 second, not yet configurable
+* Accepts time intervals in two formats
+  * Simple time DSL of seconds or minutes
+    * 30.seconds
+    * 5.minutes
+  * Hash with symbols :seconds or :minutes
+    * :seconds => 30
+    * :minutes => 5
+  * Singular forms ( 1.second or :minute => 1 ) accepted as well
+* Allows for custom exceptions, custom error messages or both
+  * For custom exceptions, add ':exception => YourException' to the options
+    * Use either :exception or :error for custom exceptions ( both are identical in functionality )
+  * For custom messages, add ':message => "Your Custom Message"' to the options
+
+* Resolution of delay between Ruby block executions is currently 1 second, not yet configurable
+* Must use hash if specifying custom exceptions or messages, can't mix and match simple time DSL with hash ( yet )
 
 == SYNOPSIS:
 
-This gem is used with asynchronous or non-blocking operations where the action of doing something is separate from whether that action succeeded.
+This gem is used in cases where the execution of an operation occurs asynchronously but a method to determine the operation's status exists. In these cases
+you want to 'wait for' that operation to either complete by continuously checking the status or fail at a specified timeout.
 
-The example below executes an asynchronous operation, then waits for up to 30 seconds for the status of the object to change by continuously checking whether it was successful.
-The Block will continue to be executed until it either returns true or 30 seconds elapses. If the time limit is reached, then a RuntimeError is raised.
+The example below runs a non-blocking operation which can not return whether it succeeded or failed. WaitFor blocks execution, in this case, for up to 30 seconds
+while it continuously runs a Ruby block supplied by the user. The Ruby block in this example determines whether the previous non-blocking operation has run to completion.
+As the Ruby block returns false, the timer continues to count down. If it returns true, then it breaks out of the loop and continues on its way. However, if the time elapsed
+becomes greater than the time permitted, 30 seconds in this example, then an exception is raised.
 
-    object.some_async_operation
+    object.some_nonblocking_operation
 
     WaitFor.upto 30.seconds do
-      object.succeeded?
+      object.completed?
     end
 
-A custom error message is specified in the example below. ( Custom errors are not yet supported. )
+Custom exception and message are specified in the examples below.
 
-    WaitFor.upto( 2.minutes, "Timeout after 2 minutes!" ) do
+    WaitFor.upto( :minute => 1, :exception => EventFailedToOccurError ) do
       event.happened?
     end
 
-Finally, a real world example taken from a FunFX test script I wrote. Here a button is clicked and we want to wait for the new screen to appear before moving on.
+    WaitFor.upto( :minute => 1, :message => "Event took longer than 1 minute to complete" ) do
+      event.happened?
+    end
+
+    WaitFor.upto( :minute => 1, :exception => EventFailedToOccurError, :message => "Event took longer than 1 minute to complete" ) do
+      event.happened?
+    end
+
+Finally, a few more "real world" examples.
 
     button.click
 
-    WaitFor.upto 1.minute do
+    WaitFor.upto( :minute => 1, :message => "New screen did not appear within 1 minute after clicking button" ) do
       Check.whether( new_screen ).is :visible
     end
 
+    website_cluster.propagate_new_entry "Good news everyone!"
+
+    WaitFor.upto( :seconds => 30, :exception => WebsiteFailedToUpdateError ) do
+      website_cluster.each_node_reports "Good news everyone!"
+    end
+
 == REQUIREMENTS:
 
 * Ruby >= 1.8.6

data/Rakefile

@@ -12,7 +12,7 @@ $hoe = Hoe.spec 'waitfor' do
   self.developer 'James Bobowski', 'james.bobowski@gmail.com'
   self.rubyforge_name       = self.name
   self.version              = WaitFor::VERSION::STRING
-  self.description          = "Continuously executes a Block until the Block returns true or the time limit is reached, at which point an error is raised"
+  self.description          = "Blocks execution until a specified statement becomes true, or a specified time interval is reached, at which point an error is raised."
 end
 
 require 'newgem/tasks'

data/lib/waitfor/timer.rb

@@ -1,13 +1,35 @@
 class Timer #:nodoc:
-  def initialize( seconds, exception_message = "Timeout Error Waiting for Event" )
-    @seconds           = seconds
-    @exception_message = exception_message
-    @start_time        = Time.now
+  def initialize( options )
+    @seconds = Timer.to_seconds options
+
+    if options.instance_of? Hash
+      @exception = options[ :exception ]
+      @exception = options[ :error ] || @exception 
+      @message   = options[ :message ]
+    end
+
+    @exception ||= WaitFor::TimeoutError
+    @start_time = Time.now
+  end
+
+  def self.to_seconds( options )
+    # Not a hash, already converted to seconds, return as is
+    return options if options.instance_of? Fixnum
+    
+    seconds = options[ :second ] || 0
+    seconds = options[ :seconds ] || seconds
+
+    minutes = options[ :minute ] || 0
+    minutes = options[ :minutes ] || minutes
+
+    return seconds + minutes * 60 
   end
 
   def out_of_time?
-    out_of_time = ( Time.now - @start_time ) > @seconds
-    raise @exception_message if out_of_time
-    out_of_time
+    if ( Time.now - @start_time ) > @seconds
+      raise @exception, @message
+    end
+
+    false
   end
 end

data/lib/waitfor/version.rb

@@ -1,8 +1,8 @@
 module WaitFor #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 0
-    TINY  = 1
+    MINOR = 1
+    TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/waitfor/waitfor_timeout_error.rb

@@ -0,0 +1,5 @@
+module WaitFor #:nodoc:
+  class TimeoutError < RuntimeError #:nodoc:
+
+  end
+end

data/lib/waitfor.rb

@@ -6,8 +6,8 @@ require 'waitfor/timer'
 
 module WaitFor
   class << self
-    def upto( length_of_time )
-      timer = Timer.new length_of_time
+    def upto( options )
+      timer = Timer.new options
       until yield or timer.out_of_time?
         sleep 1
       end

data/spec/spec_helper.rb

@@ -10,9 +10,30 @@ $:.unshift( File.dirname( __FILE__ ) + '/../lib' )
 require File.dirname( __FILE__ ) + '/../lib/waitfor.rb'
 require File.dirname( __FILE__ ) + '/../lib/waitfor/fixnum.rb'
 require File.dirname( __FILE__ ) + '/../lib/waitfor/timer.rb'
+require File.dirname( __FILE__ ) + '/../lib/waitfor/waitfor_timeout_error.rb'
 
 def timer
   start_time = Time.now
   yield
   Time.now - start_time
 end
+
+class CustomTestError < RuntimeError
+
+end
+
+class ToggleBetweenFalseAndTrue
+  def initialize
+    @status = false
+  end
+
+  def status
+    if @status
+      @status = false
+      true
+    else
+      @status = true
+      false
+    end
+  end
+end

data/spec/spec_helper_spec.rb

@@ -0,0 +1,30 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe "timer method" do
+  it "should report an elapsed time of at least 1 second but not more than 2 seconds for the code 'sleep 1'" do
+    elapsed_time = timer {
+      sleep 1
+    }
+
+    elapsed_time.should be > 1
+    elapsed_time.should be < 2
+  end
+end
+
+describe CustomTestError do
+  it "should be of a kind of RuntimeError" do
+    exception = CustomTestError.new
+    exception.should be_a_kind_of( RuntimeError )
+  end
+end
+
+describe ToggleBetweenFalseAndTrue do
+  it "should have a status method that returns false then true then false then true" do
+    event = ToggleBetweenFalseAndTrue.new
+
+    event.status.should be( false )
+    event.status.should be( true )
+    event.status.should be( false )
+    event.status.should be( true )
+  end
+end

data/spec/timer_spec.rb

@@ -1,25 +1,83 @@
 require File.dirname(__FILE__) + '/spec_helper.rb'
 
-describe Timer do
-  it "should not raise an error when set for two seconds and checked after one second" do
-    timer = Timer.new 2.seconds
-    sleep 1
+describe Timer, "when checking out_of_time?" do
+  it "should return false when set for 5 seconds and queried immediately" do
+    timer = Timer.new 5
     timer.out_of_time?.should be( false )
   end
 
-  it "should raise an error when set for two seconds and checked after one second" do
-    timer = Timer.new 1.seconds
-    sleep 2
+  it "should raise a WaitFor::TimeoutError when set for 0 seconds and queried immediately" do
+    timer = Timer.new 0.seconds
     lambda {
       timer.out_of_time?.should be( true )
-    }.should raise_error( RuntimeError, "Timeout Error Waiting for Event" )
+    }.should raise_error( WaitFor::TimeoutError )
+  end
+end
+
+describe Timer, "when inputting duration in to_seconds" do
+  it "should accept a Fixnum value of 5 as 5 seconds" do
+    Timer.to_seconds( 1 ).should be( 1 )
+  end
+
+  it "should accept a simple time DSL using a singular value of '1.second' as 1 second" do
+    Timer.to_seconds( 1.second ).should be( 1 )
+  end
+
+  it "should accept a simple time DSL using a plural value of '5.seconds' as 5 seconds" do
+    Timer.to_seconds( 5.seconds ).should be( 5 )
+  end
+
+  it "should accept a simple time DSL using a singular value of '1.minute' as 60 seconds" do
+    Timer.to_seconds( 1.minute ).should be( 60 )
+  end
+
+  it "should accept a simple time DSL using a plural value of '5.minutes' as 300 seconds" do
+    Timer.to_seconds( 5.minutes ).should be( 300 )
+  end
+
+  it "should accept a hash using a singular value of ':second => 1' as 1 second" do
+    Timer.to_seconds( :second => 1 ).should be( 1 )
+  end
+
+  it "should accept a hash using a plural value of ':seconds => 5' as 5 seconds" do
+    Timer.to_seconds( :seconds => 5 ).should be( 5 )
+  end
+
+  it "should accept a hash using a singular value of ':minute => 1' as 60 seconds" do
+    Timer.to_seconds( :minute => 1 ).should be( 60 )
   end
 
-  it "should raise a custom error when set for one second and checked after two second" do
-    timer = Timer.new( 1.seconds, "Custom Error" )
-    sleep 2
+  it "should accept a hash using a plural value of ':minutes => 5' as 300 seconds" do
+    Timer.to_seconds( :minutes => 5 ).should be( 300 )
+  end
+end
+
+describe Timer, "when inputting custom errors" do
+  it "should raise a CustomTestError when passed the value of ':exception => CustomTestError" do
+    timer = Timer.new :seconds => 0, :exception => CustomTestError
     lambda {
       timer.out_of_time?.should be( true )
-    }.should raise_error( RuntimeError, "Custom Error" )
+    }.should raise_error( CustomTestError )
   end
-end
+
+  it "should raise a CustomTestError when passed the value of ':error => CustomTestError" do
+    timer = Timer.new :seconds => 0, :error => CustomTestError
+    lambda {
+      timer.out_of_time?.should be( true )
+    }.should raise_error( CustomTestError )
+  end
+
+  it "should raise an error with the custom message 'Custom Error Message' when passed the value of ':message => 'Custom Error Message'" do
+    timer = Timer.new :seconds => 0, :message => "Custom Error Message"
+    lambda {
+      timer.out_of_time?.should be( true )
+    }.should raise_error( "Custom Error Message" )
+  end
+
+  it "should raise a CustomTestError with the custom message 'Custom Error Message' when passed the value of ':exception => CustomTestError' and ':message => 'Custom Error Message'" do
+    timer = Timer.new :seconds => 0, :exception => CustomTestError, :message => "Custom Error Message"
+    lambda {
+      timer.out_of_time?.should be( true )
+    }.should raise_error( CustomTestError, "Custom Error Message" )
+  end
+end

data/spec/waitfor_spec.rb

@@ -1,7 +1,7 @@
 require File.dirname( __FILE__ ) + '/spec_helper.rb'
 
-describe WaitFor do
-  it "should pass in under one second if block returns true immediately" do
+describe WaitFor, "when event is true" do
+  it "should halt execution for under 1 second" do
     elapsed_time = timer {
       WaitFor.upto 1.second do
         true
@@ -10,8 +10,10 @@ describe WaitFor do
 
     elapsed_time.should be < 1.second
   end
+end
 
-  it "should take at least two seconds before raising an error" do
+describe WaitFor, "when event is false" do
+  it "should halt execution for at least 2 seconds, but less than 4 seconds before raising an error" do
     elapsed_time = timer {
       lambda {
         WaitFor.upto 2.seconds do
@@ -20,6 +22,53 @@ describe WaitFor do
       }.should raise_error
     }
     
-    elapsed_time.should be_close( 2, 0.25 )
+    elapsed_time.should be > 2
+    elapsed_time.should be < 4
+  end
+end
+
+describe WaitFor, "when event is false and has custom exception" do
+  it "should raise a CustomTestError error" do
+    lambda {
+      WaitFor.upto( :seconds => 0, :exception => CustomTestError ) do
+        false
+      end
+    }.should raise_error( CustomTestError )
+  end
+end
+
+describe WaitFor, "when event is false and has custom message" do
+  it "should raise an error with a custom message" do
+    lambda {
+      WaitFor.upto( :seconds => 0, :message => "Custom Error Message" ) do
+        false
+      end
+    }.should raise_error( "Custom Error Message" )
+  end
+end
+
+describe WaitFor, "when event is false and has custom exception with a custom message" do
+  it "should raise a CustomTestError error with a custom message" do
+    lambda {
+      WaitFor.upto( :seconds => 0, :exception => CustomTestError, :message => "Custom Error Message" ) do
+        false
+      end
+    }.should raise_error( CustomTestError, "Custom Error Message" )
   end
 end
+
+describe WaitFor, "when event is initially false but becomes true " do
+  it "should halt execution for at least 1 second but no more than 3 seconds before continuing on" do
+    event = ToggleBetweenFalseAndTrue.new
+
+    elapsed_time = timer {
+      WaitFor.upto 2.seconds do
+        event.status
+      end
+    }
+
+    elapsed_time.should be > 1
+    elapsed_time.should be < 3
+  end
+end
+

data/spec/waitfor_timeout_error_spec.rb

@@ -0,0 +1,6 @@
+describe WaitFor::TimeoutError do
+  it "should be of a kind of RuntimeError" do
+    exception = WaitFor::TimeoutError.new
+    exception.should be_a_kind_of( RuntimeError )
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: waitfor
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors: 
 - James Bobowski
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-24 00:00:00 -06:00
+date: 2010-02-03 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -22,7 +22,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 2.3.3
     version: 
-description: Continuously executes a Block until the Block returns true or the time limit is reached, at which point an error is raised
+description: Blocks execution until a specified statement becomes true, or a specified time interval is reached, at which point an error is raised.
 email: 
 - james.bobowski@gmail.com
 executables: []
@@ -35,17 +35,20 @@ extra_rdoc_files:
 files: 
 - History.txt
 - Manifest.txt
-- README.rdoc
 - Rakefile
+- README.rdoc
 - lib/waitfor.rb
 - lib/waitfor/fixnum.rb
 - lib/waitfor/timer.rb
 - lib/waitfor/version.rb
-- spec/waitfor_spec.rb
-- spec/timer_spec.rb
+- lib/waitfor/waitfor_timeout_error.rb
 - spec/fixnum_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
+- spec/spec_helper_spec.rb
+- spec/timer_spec.rb
+- spec/waitfor_spec.rb
+- spec/waitfor_timeout_error_spec.rb
 has_rdoc: true
 homepage: http://github.com/jamesbobowski/waitfor
 licenses: []