test-loop 7.0.1 → 8.0.0

data/README.md

@@ -8,11 +8,6 @@ detects and tests changes in your application in an efficient manner:
 2. Forks to run your test files without overhead and in parallel.
 3. Avoids running unchanged test blocks inside changed test files.
 
-It relies on file modification times to determine what parts of your Ruby
-application have changed, applies a lambda mapping function to determine which
-test files in your test suite correspond to those changes, and uses diffing to
-find and run only those test blocks that have changed inside your test files.
-
 
 > IMPORTANT note for Ruby on Rails users!
 > ---------------------------------------
@@ -22,7 +17,7 @@ find and run only those test blocks that have changed inside your test files.
 >     config.cache_classes = false
 >
 > Otherwise, test-loop will appear to ignore class-level changes in your
-> models, controllers, etc. and will thereby cause you great frustration!
+> models, controllers, helpers, etc. thereby causing you great frustration!
 
 
 Features
@@ -92,67 +87,81 @@ Configuration
 -------------
 
 test-loop looks for a configuration file named `.test-loop` in the current
-working directory.  This configuration file is a Ruby script in which you
-can query and modify the `Test::Loop::Config` OpenStruct object as follows:
-
-* `Test::Loop::Config.overhead_file_globs` is an array of file globbing
-  patterns that describe a set of Ruby scripts that are loaded into the main
-  Ruby process as overhead.
-
-* `Test::Loop::Config.reabsorb_file_globs` is an array of file globbing
-  patterns that describe a set of files which cause the overhead to be
-  reabsorbed whenever they change.
-
-* `Test::Loop::Config.test_file_matchers` is a hash that maps a file globbing
-  pattern describing a set of source files to a lambda function yielding a
-  file globbing pattern describing a set of test files that need to be run.
-  In other words, whenever the source files (the hash key; left-hand side of
-  the mapping) change, their associated test files (the hash value; right-hand
+working directory.  This configuration file is a normal Ruby script in which
+you can query and modify the `Test::Loop` OpenStruct configuration as follows:
+
+* `Test::Loop.overhead_file_globs` is an array of file globbing patterns that
+  describe a set of Ruby scripts that are loaded into the main Ruby process as
+  overhead.
+
+* `Test::Loop.reabsorb_file_globs` is an array of file globbing patterns that
+  describe a set of files which cause the overhead to be reabsorbed whenever
+  they change.
+
+* `Test::Loop.test_file_matchers` is a hash that maps a file globbing pattern
+  describing a set of source files to a lambda function yielding a file
+  globbing pattern describing a set of test files that need to be run.  In
+  other words, whenever the source files (the hash key; left-hand side of the
+  mapping) change, their associated test files (the hash value; right-hand
   side of the mapping) are run.
 
-  For example, if test files had the same names as their source files but the
-  letters were in reverse order like this:
+  For example, if test files had the same names as their source files followed
+  by an underscore and the file name in reverse like this:
 
-  * lib/hello.rb => test/olleh.rb
-  * app/world.rb => spec/ldrow.rb
+  * lib/hello.rb => test/hello_olleh.rb
+  * app/world.rb => spec/world_ldrow.rb
 
   Then you would add the following to your configuration file:
 
-      Test::Loop::Config.test_file_matchers['{lib,app}/**/*.rb'] = lambda do |path|
+      Test::Loop.test_file_matchers['{lib,app}/**/*.rb'] = lambda do |path|
         extn = File.extname(path)
         name = File.basename(path, extn)
-        "{test,spec}/**/#{name.reverse}#{extn}" # <== notice the reverse()
+        "{test,spec}/**/#{name}_#{name.reverse}#{extn}"
+      end
+
+* `Test::Loop.test_name_parser` is a lambda function that is passed a line of
+  source code to determine whether that line can be considered as a test
+  definition, in which case it must return the name of the test being defined.
+
+* `Test::Loop.before_each_test` is a lambda function that is executed inside
+  the worker process before loading the test file.  It is passed (1) the path
+  to the test file, (2) the path to the log file containing the live output of
+  running the test file, and (3) an array containing the names of tests (which
+  were identified by `Test::Loop.test_name_parser`) inside the test file that
+  have changed since the last run of the test file.
+
+  The default implementation of this function instructs Test::Unit and RSpec
+  to only run certain test blocks inside the test file. This accelerates your
+  test-driven development cycle and improves productivity!
+
+  If you wish to add extend the default implementation, store and recall it:
+
+      default_implementation = Test::Loop.before_each_test
+
+      Test::Loop.before_each_test = lambda do |test_file, log_file, test_names|
+        default_implementation.call test_file, log_file, test_names
+        # do something additional ...
+      end
+
+  Or if you want to completely replace the default implementation:
+
+      Test::Loop.before_each_test = lambda do |test_file, log_file, test_names|
+        # your replacement here ...
       end
 
-* `Test::Loop::Config.test_name_parser` is a lambda function that is passed a
-  line of source code to determine whether that line can be considered as a
-  test definition, in which case it must return the name of the test being
-  defined.
-
-* `Test::Loop::Config.before_each_test` is a lambda function that is executed
-  inside the worker process before loading the test file.  It is passed (1)
-  the path to the test file, (2) the path to the log file containing the live
-  output of running the test file, and (3) an array containing the names of
-  tests (which were identified by `Test::Loop::Config.test_name_parser`)
-  inside the test file that have changed since the last run of the test file.
-
-  These test names should be passed down to your chosen testing library,
-  instructing it to skip all other tests except those passed down to it.  This
-  accelerates your test-driven development cycle and improves productivity!
-
-* `Test::Loop::Config.after_each_test` is a lambda function that is executed
-  inside the master process after a test has finished running.  It is passed
-  (1) the path to the test file, (2) the path to the log file containing the
-  output of running the test file, (3) a `Process::Status` object describing
-  the exit status of the worker process that ran the test file, (4) the time
-  when test execution began, and (5) how many seconds it took for the overall
-  test execution to complete.
+* `Test::Loop.after_each_test` is a lambda function that is executed inside
+  the master process after a test has finished running.  It is passed (1) the
+  path to the test file, (2) the path to the log file containing the output of
+  running the test file, (3) a `Process::Status` object describing the exit
+  status of the worker process that ran the test file, (4) the time when test
+  execution began, and (5) how many seconds it took for the overall test
+  execution to complete.
 
   For example, to display a summary of the test execution results as an
   on-screen-display notification while also displaying the log file if the
   test failed, add the following to your configuration file:
 
-      Test::Loop::Config.after_each_test = lambda do |test_file, log_file, run_status, started_at, elapsed_time|
+      Test::Loop.after_each_test = lambda do |test_file, log_file, run_status, started_at, elapsed_time|
         success = run_status.success?
 
         title = '%s at %s in %0.1fs' %

data/bin/test-loop

@@ -26,207 +26,202 @@ require 'ostruct'
 require 'diff/lcs'
 
 module Test
-  module Loop
-    CONFIG_FILE = File.join(Dir.pwd, '.test-loop')
-
-    Config = OpenStruct.new(
-      :overhead_file_globs => ['{test,spec}/{test,spec}_helper.rb'],
-
-      :reabsorb_file_globs => ['{test,spec}/{test,spec}_helper.rb',
-                               'config/*.{rb,yml}', 'Gemfile.lock',
-                               File.basename(CONFIG_FILE)],
-
-      :test_file_matchers => {
-        # source files that correspond to test files
-        '{lib,app}/**/*.rb' => lambda do |path|
-          extn = File.extname(path)
-          name = File.basename(path, extn)
-          "{test,spec}/**/#{name}_{test,spec}#{extn}"
-        end,
-
-        # the actual test files themselves
-        '{test,spec}/**/*_{test,spec}.rb' => lambda {|path| path }
-      },
-
-      :test_name_parser => lambda do |line|
-        case line
-        when /^\s*def\s+test_(\w+)/ then $1
-        when /^\s*(test|context|should|describe|it)\b.+?(['"])(.*?)\2/ then $3
-        end
-      end,
-
-      :before_each_test => lambda do |test_file, log_file, test_names|
-        unless test_names.empty?
-          test_name_pattern = test_names.map do |name|
-            # sanitize string interpolation and non-method-name characters
-            name.gsub(/\#\{.*?\}/, ' ').strip.gsub(/\W+/, '.*')
-          end.join('|')
-
-          case File.basename(test_file)
-          when /(\b|_)test(\b|_)/ # Test::Unit
-            ARGV.push '--name', "/#{test_name_pattern}/"
-          when /(\b|_)spec(\b|_)/ # RSpec
-            ARGV.push '--example', test_name_pattern
-          end
-        end
-      end,
+  Loop = OpenStruct.new
+
+  Loop.config_file_path = File.join(Dir.pwd, '.test-loop')
+
+  Loop.overhead_file_globs = ['{test,spec}/{test,spec}_helper.rb']
+
+  Loop.reabsorb_file_globs = Loop.overhead_file_globs +
+    ['config/*.{rb,yml}', 'Gemfile.lock', File.basename(Loop.config_file_path)]
 
-      :after_each_test =>
-        lambda {|test_file, log_file, run_status, started_at, elapsed_time|}
-    )
+  Loop.test_file_matchers = {
+    # source files that correspond to test files
+    '{lib,app}/**/*.rb' => lambda do |path|
+      extn = File.extname(path)
+      name = File.basename(path, extn)
+      "{test,spec}/**/#{name}_{test,spec}#{extn}"
+    end,
 
-    def self.run
+    # the actual test files themselves
+    '{test,spec}/**/*_{test,spec}.rb' => lambda {|path| path }
+  }
+
+  Loop.test_name_parser = lambda do |line|
+    case line
+    when /^\s*def\s+test_(\w+)/ then $1
+    when /^\s*(test|context|should|describe|it)\b.+?(['"])(.*?)\2/ then $3
+    end
+  end
+
+  Loop.before_each_test = lambda do |test_file, log_file, test_names|
+    unless test_names.empty?
+      test_name_pattern = test_names.map do |name|
+        # sanitize string interpolation and non-method-name characters
+        name.gsub(/\#\{.*?\}/, ' ').strip.gsub(/\W+/, '.*')
+      end.join('|')
+
+      case File.basename(test_file)
+      when /(\b|_)test(\b|_)/ # Test::Unit
+        ARGV.push '--name', "/#{test_name_pattern}/"
+      when /(\b|_)spec(\b|_)/ # RSpec
+        ARGV.push '--example', test_name_pattern
+      end
+    end
+  end
+
+  Loop.after_each_test =
+    lambda {|test_file, log_file, run_status, started_at, elapsed_time|}
+
+  class << Loop
+    def run
       register_signals
       load_user_config
       absorb_overhead
       run_test_loop
     rescue Exception => error
       STDERR.puts error.inspect, error.backtrace
-      sleep 1
+      pause_momentarily
       reload_master_process
     end
 
-    class << self; private
-      SCRIPT_NAME = File.basename($0)
-      EXEC_VECTOR = [$0, *ARGV].map {|s| s.dup.freeze }.freeze
+    private
 
-      def notify message
-        # using print() because puts() is not an atomic operation
-        print "#{SCRIPT_NAME}: #{message}\n"
-      end
+    SCRIPT_NAME = File.basename($0).freeze
+    EXEC_VECTOR = [$0, *ARGV].map {|s| s.dup.freeze }.freeze
 
-      def register_signals
-        trap(:INT) { destroy_process_group }
-        master_pid = $$ # kill only the workers, not the master
-        trap(:USR1) { destroy_process_group unless $$ == master_pid }
-        trap(:QUIT) { reload_master_process }
-        trap(:TSTP) {} # ignore until ready for testing in run_test_loop()
-      end
+    def notify message
+      # using print() because puts() is not an atomic operation
+      print "#{SCRIPT_NAME}: #{message}\n"
+    end
 
-      def destroy_process_group
-        Process.kill :KILL, -$$
-      end
+    def register_signals
+      trap(:INT) { destroy_process_group }
+      master_pid = $$ # kill only the workers, not the master
+      trap(:USR1) { destroy_process_group unless $$ == master_pid }
+      trap(:QUIT) { reload_master_process }
+      trap(:TSTP) {} # ignore until ready for testing in run_test_loop()
+    end
 
-      def reload_master_process
-        notify 'Restarting loop...'
-        Process.kill :USR1, -$$
-        exec(*EXEC_VECTOR)
-      end
+    def destroy_process_group
+      Process.kill :KILL, -$$
+    end
 
-      def load_user_config
-        if File.exist? CONFIG_FILE
-          notify 'Loading configuration...'
-          load CONFIG_FILE
-        end
+    def reload_master_process
+      notify 'Restarting loop...'
+      Process.kill :USR1, -$$
+      exec(*EXEC_VECTOR)
+    end
+
+    def pause_momentarily
+      sleep 1
+    end
+
+    def load_user_config
+      if File.exist? config_file_path
+        notify 'Loading configuration...'
+        load config_file_path
       end
+    end
 
-      def absorb_overhead
-        notify 'Absorbing overhead...'
-        $LOAD_PATH.unshift 'lib', 'test', 'spec'
-        Dir[*Config.overhead_file_globs].each do |file|
-          require File.basename(file, File.extname(file))
-        end
+    def absorb_overhead
+      notify 'Absorbing overhead...'
+      $LOAD_PATH.unshift 'lib', 'test', 'spec'
+      Dir[*overhead_file_globs].each do |file|
+        require File.basename(file, File.extname(file))
       end
+    end
 
-      def run_test_loop
-        @running_files = []
-        @running_files_lock = Mutex.new
-
-        @lines_by_file = {} # path => readlines
-        @last_ran_at = @started_at = Time.now
-        trap(:TSTP) { @last_ran_at = Time.at(0); @lines_by_file.clear }
-
-        notify 'Ready for testing!'
-        loop do
-          # figure out what test files need to be run
-          test_files = Config.test_file_matchers.map \
-          do |source_glob, test_matcher|
-            Dir[source_glob].select {|file| File.mtime(file) > @last_ran_at }.
-            map {|path| Dir[test_matcher.call path] }
-          end.flatten.uniq
-
-          test_files = @running_files_lock.
-            synchronize { test_files - @running_files }
-
-          # fork worker processes to run the test files in parallel
-          @last_ran_at = Time.now
-          test_files.each {|f| run_test_file f }
-
-          # reabsorb test execution overhead as necessary
-          if Dir[*Config.reabsorb_file_globs].
-             any? {|file| File.mtime(file) > @started_at }
-          then
-            reload_master_process
-          end
+    def run_test_loop
+      @running_files = []
+      @running_files_lock = Mutex.new
 
-          sleep 1
-        end
-      end
+      @lines_by_file = {} # path => readlines
+      @last_ran_at = @started_at = Time.now
+      trap(:TSTP) { @last_ran_at = Time.at(0); @lines_by_file.clear }
 
-      def run_test_file test_file
-        @running_files_lock.synchronize { @running_files.push test_file }
-        log_file = test_file + '.log'
-
-        # cache the contents of the test file for diffing below
-        new_lines = File.readlines(test_file)
-        old_lines = @lines_by_file[test_file] || new_lines
-        @lines_by_file[test_file] = new_lines
-
-        worker_pid = fork do
-          # capture test output in log file because tests are run in parallel
-          # which makes it difficult to understand interleaved output thereof
-          $stdout.reopen log_file, 'w'
-          $stdout.sync = true
-          $stderr.reopen $stdout
-
-          # determine which test blocks have changed inside the test file
-          test_names = Diff::LCS.diff(old_lines, new_lines).flatten.map \
-          do |change|
-            catch :found do
-              # search backwards from the line that changed up to
-              # the first line in the file for test definitions
-              change.position.downto(0) do |i|
-                if test_name = Config.test_name_parser.call(new_lines[i])
-                  throw :found, test_name
-                end
-              end; nil # prevent unsuccessful search from returning an integer
-            end
-          end.compact.uniq
-
-          # tell the testing framework to run only the changed test blocks
-          Config.before_each_test.call test_file, log_file, test_names
-
-          # after loading the user's test file, the at_exit() hook of the
-          # user's testing framework will take care of running the tests and
-          # reflecting any failures in the worker process' exit status
-          load $0 = test_file # set $0 because Test::Unit outputs it
-        end
+      notify 'Ready for testing!'
+      loop do
+        # figure out what test files need to be run
+        test_files = test_file_matchers.map do |source_glob, test_matcher|
+          Dir[source_glob].select {|file| File.mtime(file) > @last_ran_at }.
+          map {|path| Dir[test_matcher.call path] }
+        end.flatten.uniq
 
-        # monitor and report on the worker's progress
-        Thread.new do
-          report = lambda do |state|
-            notify [state, worker_pid, test_file].join("\t")
-          end
-          report.call :RUN
+        test_files = @running_files_lock.
+          synchronize { test_files - @running_files }
+
+        # fork worker processes to run the test files in parallel
+        @last_ran_at = Time.now
+        test_files.each {|file| run_test_file file }
 
-          # wait for worker to finish
-          begin
-            Process.waitpid worker_pid
-          rescue Errno::ECHILD
-            # worker finished and the OS has forgotten about it already
+        # reabsorb test execution overhead as necessary
+        reload_master_process if Dir[*reabsorb_file_globs].
+          any? {|file| File.mtime(file) > @started_at }
+
+        pause_momentarily
+      end
+    end
+
+    def run_test_file test_file
+      @running_files_lock.synchronize { @running_files.push test_file }
+      log_file = test_file + '.log'
+
+      # cache the contents of the test file for diffing below
+      new_lines = File.readlines(test_file)
+      old_lines = @lines_by_file[test_file] || new_lines
+      @lines_by_file[test_file] = new_lines
+
+      worker_pid = fork do
+        # capture test output in log file because tests are run in parallel
+        # which makes it difficult to understand interleaved output thereof
+        $stdout.reopen log_file, 'w'
+        $stdout.sync = true
+        $stderr.reopen $stdout
+
+        # determine which test blocks have changed inside the test file
+        test_names = Diff::LCS.diff(old_lines, new_lines).flatten.map do |change|
+          catch :found do
+            # search backwards from the line that changed up to
+            # the first line in the file for test definitions
+            change.position.downto(0) do |i|
+              if test_name = test_name_parser.call(new_lines[i])
+                throw :found, test_name
+              end
+            end; nil # prevent unsuccessful search from returning an integer
           end
-          elapsed_time = Time.now - @last_ran_at
+        end.compact.uniq
 
-          report.call $?.success? && :PASS || :FAIL
+        # tell the testing framework to run only the changed test blocks
+        before_each_test.call test_file, log_file, test_names
 
-          Config.after_each_test.call \
-            test_file, log_file, $?, @last_ran_at, elapsed_time
+        # after loading the user's test file, the at_exit() hook of the
+        # user's testing framework will take care of running the tests and
+        # reflecting any failures in the worker process' exit status
+        load $0 = test_file # set $0 because Test::Unit outputs it
+      end
 
-          @running_files_lock.synchronize { @running_files.delete test_file }
+      # monitor and report on the worker's progress
+      Thread.new do
+        report = lambda do |state|
+          notify [state, worker_pid, test_file].join("\t")
         end
+        report.call :RUN
+
+        # wait for worker to finish
+        begin
+          Process.waitpid worker_pid
+        rescue Errno::ECHILD
+          # worker finished and the OS has forgotten about it already
+        end
+        elapsed_time = Time.now - @last_ran_at
+
+        report.call $?.success? && :PASS || :FAIL
+        after_each_test.call test_file, log_file, $?, @last_ran_at, elapsed_time
+        @running_files_lock.synchronize { @running_files.delete test_file }
       end
     end
   end
 end
 
-Test::Loop.run
+Test::Loop.run if $0 == __FILE__

metadata

@@ -3,10 +3,10 @@ name: test-loop
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
-  - 7
+  - 8
   - 0
-  - 1
-  version: 7.0.1
+  - 0
+  version: 8.0.0
 platform: ruby
 authors: 
 - Suraj N. Kurapati
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-10 00:00:00 -08:00
+date: 2011-02-12 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency