waitfor 0.1.0 → 0.1.7

data/History.txt

@@ -1,4 +1,32 @@
+=== 0.1.7 2011-04-19
+
+* Bug fix related to not accumulating seconds when minutes was specified
+* Enhanced rspec tests
+
+=== 0.1.6 2011-03-23
+
+* Various bug fixes.
+
+=== 0.1.5 2011-03-23
+
+* Additional refactoring to separate out the option parsing in preparation for new functionality
+
+=== 0.1.3 2010-11-14
+
+* Minor refactoring and enhancement of tests
+
+=== 0.1.2 2010-11-13
+
+* Updated tests to use mocks to increase their speed dramatically
+
+=== 0.1.1 2010-02-05
+
+* Updated tests to use standard benchmarking library
+
+=== 0.1.0 2010-02-03
+
+* Added new time formats, custom exceptions and messages
+
 === 0.0.1 2010-01-24
 
-* 1 major enhancement:
-  * Initial release
+* Initial release

data/Manifest.txt

@@ -1,16 +1,22 @@
 History.txt
 Manifest.txt
-README.rdoc
 Rakefile
+README.rdoc
 lib/waitfor.rb
 lib/waitfor/fixnum.rb
+lib/waitfor/timeout_error.rb
 lib/waitfor/timer.rb
 lib/waitfor/version.rb
-lib/waitfor/waitfor_timeout_error.rb
+lib/waitfor/settings/configuration.rb
+lib/waitfor/settings/legacy_parser.rb
+lib/waitfor/settings/parser.rb
+spec/configuration_spec.rb
 spec/fixnum_spec.rb
+spec/legacy_parser_spec.rb
+spec/parser_spec.rb
 spec/spec.opts
 spec/spec_helper.rb
 spec/spec_helper_spec.rb
-spec/waitfor_spec.rb
+spec/timeout_error_spec.rb
 spec/timer_spec.rb
-spec/waitfor_timeout_error_spec.rb
+spec/waitfor_spec.rb

data/README.rdoc

@@ -4,44 +4,62 @@
 
 == DESCRIPTION:
 
-Blocks execution until a specified statement becomes true, or a specified time interval is reached, at which point an error is raised.
+Simple solution to the sleep( ) test anti-pattern.
 
-Useful for strengthening tests involving asynchronous or non-blocking operations.
+Blocks execution until a supplied block returns true, or a specified time interval is reached, at which point an error is raised.
 
-== FEATURES/PROBLEMS:
+    object.some_nonblocking_operation
+
+    WaitFor.upto 30.seconds do
+      object.completed?
+    end
+
+== FEATURES:
 
 * 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
+  * Legacy mode with seconds or minutes
+    * 30.seconds
+    * 5.minutes
 * 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 )
+* Resolution of delay between Ruby block executions is currently 1 second ( and not yet configurable )
+* Must use hash if specifying custom exceptions or messages, can't mix and match simple time DSL with hash
 
 == SYNOPSIS:
 
-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.
+Simple solution to the sleep( ) test anti-pattern.
 
-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.
+Blocks execution until a supplied block returns true, or a specified time interval is reached, at which point an error is raised.
 
-    object.some_nonblocking_operation
+Useful for adding elasticity to tests involving asynchronous or non-blocking operations. Instead of sleep( )'ing in a test, add a WaitFor.
+Reduces test execution time by waiting only as long as required. Adds robustness by giving test steps enough time to execute, reducing
+fail-positive failures from timeouts.
 
-    WaitFor.upto 30.seconds do
+Whereas you might normally do something like this:
+
+    object.some_asynchronous_operation
+
+    # Wait for it to finish and let's hope it doesn't take 31 seconds, because then the test might fail without good reason!
+    # Let's also hope it takes no less than 29 seconds, because then we're making the test slow!
+    sleep( 30 )
+
+It would be far superior to use WaitFor in this manner:
+
+    object.some_asynchronous_operation
+
+    WaitFor.upto 60.seconds do
       object.completed?
     end
 
+Here the test could take as long as 60 seconds and still pass, likewise, if it took only 1 second, it would continue on with minimal delay. We've removed the brittleness that sleep() adds.
+
 Custom exception and message are specified in the examples below.
 
     WaitFor.upto( :minute => 1, :exception => EventFailedToOccurError ) do
@@ -58,17 +76,16 @@ Custom exception and message are specified in the examples below.
 
 Finally, a few more "real world" examples.
 
-    button.click
+    page.click "Link"
 
-    WaitFor.upto( :minute => 1, :message => "New screen did not appear within 1 minute after clicking button" ) do
-      Check.whether( new_screen ).is :visible
+    WaitFor.upto( :minute => 1, :message => "New page did not appear within 1 minute after clicking link" ) do
+      page.has_loaded? && page.title == "Home"
     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
+    print "/tmp/file"
+
+    WaitFor.upto( 30.seconds ) { files_in_queue( "/tmp/print/queue" ).count == 1 }
 
 == REQUIREMENTS:
 
@@ -82,7 +99,7 @@ Finally, a few more "real world" examples.
 
 (The MIT License)
 
-Copyright (c) 2010 James Bobowski
+Copyright (c) 2010-2011 James Bobowski
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -9,10 +9,10 @@ Hoe.plugin :newgem
 # Generate all the Rake tasks
 # Run 'rake -T' to see list of generated tasks (from gem root directory)
 $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          = "Blocks execution until a specified statement becomes true, or a specified time interval is reached, at which point an error is raised."
+  self.developer      'James Bobowski', 'james.bobowski@gmail.com'
+  self.rubyforge_name = self.name
+  self.version        = WaitFor::VERSION::STRING
+  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.rb

@@ -1,16 +1,40 @@
+# @author James Bobowski
+
 $:.unshift( File.dirname( __FILE__ ) ) unless
   $:.include?( File.dirname( __FILE__ ) ) || $:.include?( File.expand_path( File.dirname( __FILE__ ) ) )
 
 require 'waitfor/fixnum'
+require 'waitfor/timeout_error'
 require 'waitfor/timer'
+require 'waitfor/settings/configuration'
+require 'waitfor/settings/legacy_parser'
+require 'waitfor/settings/parser'
 
 module WaitFor
   class << self
+    # Execute the given block until it returns true or the specified timeout is reached.
+    #
+    # @param [Hash] options the options for upon( )
+    # @option options [Fixnum] :seconds Timeout in seconds
+    # @option options [String] :minutes Timeout in minutes
+    # @option options [String] :exception Exception to throw if timeout is reached
+    # @option options [String] :message Custom message for exception if timeout is reached
+    # @yield Block to execute until it returns true
+    #
+    # @example
+    #   WaitFor.upto( 30.seconds ) do
+    #     has_event_happened?
+    #   end
+    #
+    # @example
+    #   WaitFor.upto( :minute => 1, :seconds => 30 ) do
+    #     has_event_happened?
+    #   end
     def upto( options )
       timer = Timer.new options
       until yield or timer.out_of_time?
-        sleep 1
+        Kernel.sleep 1
       end
     end
   end
-end
+end

data/lib/waitfor/fixnum.rb

@@ -1,14 +1,30 @@
-class Fixnum #:nodoc:
-  def second
-    self.seconds
+begin
+  # Attempt to access the Rails version because this will work in a Rails environment.
+  Rails.version
+  # If NameError is thrown, then we know we aren't in a Rails environment.
+rescue NameError
+  # Since we aren't in a Rails environment, we'll need to monkeypatch Fixnum to support .seconds and .minutes
+  class Fixnum
+    # Return the current number unmodified since it is already in seconds.
+    #
+    # @return [Fixnum] the current unmodified.
+    def seconds
+      self
+    end
+
+    # Convert the current number into seconds.
+    #
+    # @return [Fixnum] the current number as seconds.
+    def minutes
+      self * 60
+    end
+
+    # Alias for seconds.
+    #
+    alias :second :seconds
+
+    # Alias for minutes.
+    #
+    alias :minute :minutes    
   end
-  def seconds
-    self
-  end
-  def minute
-    self.minutes
-  end
-  def minutes
-    self * 60
-  end
-end
+end

data/lib/waitfor/settings/configuration.rb

@@ -0,0 +1,35 @@
+# @author James Bobowski
+module WaitFor
+  module Settings
+    class Configuration
+
+      attr_accessor :seconds, :exception, :message
+
+      # A new instance of Configuration.
+      #
+      # @param [Hash|Fixnum] options settings for configuration such as `:seconds`, `:minutes`, `:exception` and `:message` or just a Fixnum representing seconds
+      def initialize( options )
+        # Initialize seconds to zero, so that from there we can add seconds to it.
+        @seconds = 0
+        # Determine which parser should be used, then call it, passing ourselves in for assignment of the parsed values.
+        parser_factory( options ).parse( options, self )
+      end
+
+      private
+
+      # Determine which parser should be used based on the type of object passed in.
+      #
+      # @param [Hash|Fixnum] options settings for Configuration
+      # @return [Class] class of parser to use for this type of settings object
+      def parser_factory( options )
+        if options.instance_of? Fixnum
+          WaitFor::Settings::LegacyParser
+        elsif options.instance_of? Hash
+          WaitFor::Settings::Parser
+        else
+          raise "Unable to parse configuration options."
+        end
+      end
+    end
+  end
+end

data/lib/waitfor/settings/legacy_parser.rb

@@ -0,0 +1,44 @@
+# @author James Bobowski
+module WaitFor
+  module Settings
+    class LegacyParser
+
+      attr_accessor :params, :config
+
+      # Parse parameters and return Configuration object.
+      #
+      # @param [Fixnum] params parameters
+      # @param [Configuration] config new Configuration object to populate with options
+      # @return [Configuration] the configured Configuration object
+      def self.parse( params, config )
+        parser = WaitFor::Settings::LegacyParser.new( params, config )
+        parser.parse
+        parser.config
+      end
+
+      # Create a new Parser.
+      #
+      # @param [Fixnum] params parameters
+      # @param [Configuration] config new Configuration object to populate with options
+      # @return [Configuration] the configured Configuration object
+      def initialize( params, config )
+        @params, @config = params, config
+
+        # Default exception since legacy does not support specifying an exception.
+        @config.exception = WaitFor::TimeoutError
+      end
+
+      # Call all parsing methods in order.
+      def parse
+        parse_time
+      end
+
+      private
+
+      # Parse seconds or minutes and set the Configuration's object seconds attribute.
+      def parse_time
+        @config.seconds = @params
+      end      
+    end
+  end
+end

data/lib/waitfor/settings/parser.rb

@@ -0,0 +1,59 @@
+# @author James Bobowski
+module WaitFor
+  module Settings
+    class Parser
+
+      attr_accessor :params, :config
+
+      # Parse parameters and return Configuration object.
+      #
+      # @param [Fixnum] params parameters
+      # @param [Configuration] config new Configuration object to populate with options
+      # @return [Configuration] the configured Configuration object
+      def self.parse( params, config )
+        parser = WaitFor::Settings::Parser.new( params, config )
+        parser.parse
+        parser.config
+      end
+
+      # Create a new Parser.
+      #
+      # @param [Fixnum] params parameters
+      # @param [Configuration] config new Configuration object to populate with options
+      # @return [Configuration] the configured Configuration object
+      def initialize( params, config )
+        @params, @config = params, config
+      end
+
+      # Call all parsing methods in order.
+      def parse
+        parse_seconds
+        parse_minutes
+        parse_exception
+        parse_message
+      end
+
+      private
+
+      # Parse seconds and add to the Configuration's object seconds attribute.
+      def parse_seconds
+        @config.seconds += ( @params[ :second ] || 0 ) + ( @params[ :seconds ] || 0 )
+      end
+
+      # Parse minutes and add to the Configuration's object seconds attribute.
+      def parse_minutes
+        @config.seconds += ( ( @params[ :minute ] || 0 ) + ( @params[ :minutes ] || 0 ) ) * 60
+      end
+
+      # Parse exception and set the Configuration's object exception attribute.
+      def parse_exception
+        @config.exception = @params[ :exception ] || WaitFor::TimeoutError
+      end
+
+      # Parse message and set the Configuration's object message attribute.
+      def parse_message
+        @config.message = @params[ :message ] || "WaitFor timed out!"
+      end
+    end
+  end
+end

data/lib/waitfor/timeout_error.rb

@@ -0,0 +1,4 @@
+# @author James Bobowski
+module WaitFor
+  class TimeoutError < RuntimeError; end;
+end

data/lib/waitfor/timer.rb

@@ -1,35 +1,44 @@
-class Timer #:nodoc:
-  def initialize( options )
-    @seconds = Timer.to_seconds options
-
-    if options.instance_of? Hash
-      @exception = options[ :exception ]
-      @exception = options[ :error ] || @exception 
-      @message   = options[ :message ]
+# @author James Bobowski
+module WaitFor
+  class Timer
+    # A new instance of Timer.
+    #
+    # @param [Hash] options for Timer configuration such as `:seconds`, `:minutes`, `:exception` and `:message`
+    def initialize( options )
+      @config = WaitFor::Settings::Configuration.new( options )
+      @start_time = Time.now
     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
+    # Returns whether the elapsed time has surpassed the allotted time
+    #
+    # @return [Boolean] of elapsed time is greater or equal to the set number of seconds
+    # @raise [WaitFor::TimeoutError] Timeout error if time limit is reached
+    def out_of_time?
+      raise_exception if timed_out?
+      false
+    end
 
-    minutes = options[ :minute ] || 0
-    minutes = options[ :minutes ] || minutes
+    private
 
-    return seconds + minutes * 60 
-  end
+    # Determine whether the amount of time elapsed is greater than the limit.
+    #
+    # @return [Boolean] whether the amount of time elapsed is greater than the limit.
+    def timed_out?
+      elapsed_time >= @config.seconds
+    end
 
-  def out_of_time?
-    if ( Time.now - @start_time ) > @seconds
-      raise @exception, @message
+    # Calculate the number of seconds that have passed since object was initialized.
+    #
+    # @return [Fixnum] number seconds that have passed since object was initialized.     
+    def elapsed_time
+      Time.now - @start_time
     end
 
-    false
+    # Raise the exceptions for this object.
+    #
+    # @raise [WaitFor::TimeoutError] Timeout error    
+    def raise_exception
+      raise @config.exception, @config.message
+    end
   end
-end
+end