test-loop 9.3.0 → 9.4.0

data/README.md

@@ -59,7 +59,7 @@ If installed as a Git clone:
 
 You can monitor your test processes in another terminal:
 
-    watch "ps xf | egrep 'test-loop|(test|spec)/.+\.rb' | sed '1,3d'"
+    watch 'ps xf | grep test-loop | sed 1,3d'
 
 ------------------------------------------------------------------------------
 Operation
@@ -81,119 +81,140 @@ test-loop looks for a configuration file named `.test-loop` in the current
 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.overhead_file_globs
 
-* `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.
+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.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.
+### Test::Loop.reabsorb_file_globs
 
-  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:
+An array of file globbing patterns that describe a set of files which cause
+the overhead to be reabsorbed whenever they change.
 
-  * `lib/hello.rb` => `test/hello_olleh.rb`
-  * `app/world.rb` => `spec/world_ldrow.rb`
+### Test::Loop.test_file_matchers
 
-  Then you would add the following to your configuration file:
+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.
 
-      Test::Loop.test_file_matchers['{lib,app}/**/*.rb'] = lambda do |path|
-        extn = File.extname(path)
-        name = File.basename(path, extn)
-        "{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.
+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:
 
-* `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.
+* `lib/hello.rb` => `test/hello_olleh.rb`
+* `app/world.rb` => `spec/world_ldrow.rb`
 
-  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!
+Then you would add the following to your configuration file:
 
-  If you wish to add extend the default implementation, store and recall it:
+    Test::Loop.test_file_matchers['{lib,app}/**/*.rb'] = lambda do |path|
+      extn = File.extname(path)
+      name = File.basename(path, extn)
+      "{test,spec}/**/#{name}_#{name.reverse}#{extn}"
+    end
 
-      default_implementation = Test::Loop.before_each_test
+In addition, these lambda functions can return `nil` if they do not wish for a
+particular source file to be tested.  For example, to ignore tests for all
+source files except those within a `models/` directory, you would write:
 
-      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 ...
+    Test::Loop.test_file_matchers['{lib,app}/**/*.rb'] = lambda do |path|
+      if path.include? '/models/'
+        "{test,spec}/**/#{File.basename(path)}"
       end
+    end
 
-  Or if you want to completely replace the default implementation:
+For source files not satisfying the above constraint, this lambda function
+will return `nil`, thereby excluding those source files from being tested.
 
-      Test::Loop.before_each_test = lambda do |test_file, log_file, test_names|
-        # your replacement here ...
-      end
+### Test::Loop.test_name_parser
 
-* `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.
+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.
 
-  For example, to delete log files for successful tests, add the following to
-  your configuration file:
+### Test::Loop.before_each_test
 
-      Test::Loop.after_each_test = lambda do |test_file, log_file, run_status, started_at, elapsed_time|
-        File.delete(log_file) if run_status.success?
-      end
+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.
 
-  For example, to see on-screen-display notifications only about test
-  failures, add the following to your configuration 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!
 
-      Test::Loop.after_each_test = lambda do |test_file, log_file, run_status, started_at, elapsed_time|
-        unless run_status.success?
-          title = 'FAIL at %s in %0.1fs' % [started_at.strftime('%r'), elapsed_time]
+If you wish to add extend the default implementation, store and recall it:
 
-          message = test_file
+    default_implementation = Test::Loop.before_each_test
 
-          Thread.new do # run in background
-            system 'notify-send', '-i', 'dialog-error', title, message or
-            system 'growlnotify', '-a', 'Xcode', '-m', message, title or
-            system 'xmessage', '-timeout', '5', '-title', title, message
-          end
-        end
-      end
+    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
 
-  Note that the above functionality is available as a configuration preset:
+Or if you want to completely replace the default implementation:
 
-      require 'test/loop/notify'
+    Test::Loop.before_each_test = lambda do |test_file, log_file, test_names|
+      # your replacement here ...
+    end
+
+### Test::Loop.after_each_test
+
+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 see on-screen-display notifications about completed test
-  runs, regardless of whether they passed or failed, add the following to your
-  configuration file:
+For example, to delete log files for successful tests, add the following to
+your configuration file:
 
-      Test::Loop.after_each_test = lambda do |test_file, log_file, run_status, started_at, elapsed_time|
-        success = run_status.success?
+    Test::Loop.after_each_test = lambda do |test_file, log_file, run_status, started_at, elapsed_time|
+      File.delete(log_file) if run_status.success?
+    end
 
-        title = '%s at %s in %0.1fs' %
-          [success ? 'PASS' : 'FAIL', started_at.strftime('%X'), elapsed_time]
+For example, to see on-screen-display notifications only about test failures,
+add the following to your configuration file:
+
+    Test::Loop.after_each_test = lambda do |test_file, log_file, run_status, started_at, elapsed_time|
+      unless run_status.success?
+        title = 'FAIL at %s in %0.1fs' % [started_at.strftime('%r'), elapsed_time]
 
         message = test_file
 
         Thread.new do # run in background
-          system 'notify-send', '-i', "dialog-#{success ? 'information' : 'error'}", title, message or
+          system 'notify-send', '-i', 'dialog-error', title, message or
           system 'growlnotify', '-a', 'Xcode', '-m', message, title or
           system 'xmessage', '-timeout', '5', '-title', title, message
         end
       end
+    end
+
+Note that the above functionality is available as a configuration preset:
+
+    require 'test/loop/notify'
+
+For example, to see on-screen-display notifications about completed test runs,
+regardless of whether they passed or failed, add the following to your
+configuration file:
+
+    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' %
+        [success ? 'PASS' : 'FAIL', started_at.strftime('%X'), elapsed_time]
+
+      message = test_file
+
+      Thread.new do # run in background
+        system 'notify-send', '-i', "dialog-#{success ? 'information' : 'error'}", title, message or
+        system 'growlnotify', '-a', 'Xcode', '-m', message, title or
+        system 'xmessage', '-timeout', '5', '-title', title, message
+      end
+    end
 
 ------------------------------------------------------------------------------
 Configuration Presets

data/bin/test-loop

@@ -1,3 +1,4 @@
 #!/usr/bin/env ruby
 require 'test/loop'
 Test::Loop.run
+exit! true # skip at_exit() handlers registered in the master process

data/lib/test/loop.rb

@@ -48,14 +48,21 @@ module Test
 
   class << Loop
     def run
-      init_test_loop
-      register_signals
-      load_user_config
-      absorb_overhead
-      run_test_loop
-    rescue SystemExit
-      # allow exit() to terminate the test loop
+      @running_files = []
+      @running_files_lock = Mutex.new
+      @lines_by_file = {} # path => readlines
+      @last_ran_at = @started_at = Time.now
+
+      catch self do
+        register_signals
+        load_user_config
+        absorb_overhead
+        run_test_loop
+      end
+
+      kill_workers
       notify 'Goodbye!'
+
     rescue Exception => error
       STDERR.puts error.inspect, error.backtrace
       pause_momentarily
@@ -76,22 +83,16 @@ module Test
       print "test-loop: #{message}\n"
     end
 
-    def init_test_loop
-      @running_files = []
-      @running_files_lock = Mutex.new
-      @lines_by_file = {} # path => readlines
-      @last_ran_at = @started_at = Time.now
-    end
-
     def register_signals
+      # this signal is ignored in master and honored in workers, so all
+      # workers can be killed by sending it to the entire process group
+      trap :TERM, :IGNORE
+
       # clear line to shield normal output from control-key interference:
       # some shells like BASH emit text when control-key combos are pressed
-      trap(:INT)  { print ANSI_CLEAR_LINE; kill_workers; exit }
+      trap(:INT)  { print ANSI_CLEAR_LINE; throw self }
       trap(:QUIT) { print ANSI_CLEAR_LINE; reload_master_process }
       trap(:TSTP) { print ANSI_CLEAR_LINE; forcibly_run_all_tests }
-
-      master_pid = $$
-      trap(:TERM) { exit unless $$ == master_pid }
     end
 
     def kill_workers
@@ -139,7 +140,7 @@ module Test
         # find test files that have been modified since the last 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] }
+          map {|path| Dir[test_matcher.call(path).to_s] }
         end.flatten.uniq
 
         # resume test files stopped by the previous incarnation of test-loop
@@ -181,6 +182,9 @@ module Test
       @lines_by_file[test_file] = new_lines
 
       worker_pid = fork do
+        # unregister custom signal handlers meant for master process
+        [:TERM, :INT, :QUIT, :TSTP].each {|sig| trap sig, :DEFAULT }
+
         # 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'
@@ -203,10 +207,13 @@ module Test
         # tell the testing framework to run only the changed test blocks
         before_each_test.call test_file, log_file, test_names
 
+        # make the process title Test::Unit friendly and ps(1) searchable
+        $0 = "test-loop #{test_file}"
+
         # 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
+        load test_file
       end
 
       # monitor and report on the worker's progress

metadata

@@ -2,7 +2,7 @@
 name: test-loop
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 9.3.0
+  version: 9.4.0
 platform: ruby
 authors: 
 - Suraj N. Kurapati
@@ -11,7 +11,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-01 00:00:00 -07:00
+date: 2011-04-06 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency