tork 18.2.4 → 19.0.0

data/bin/tork-herald

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# TORK-HERALD 1 2012-10-10 18.2.4
+# TORK-HERALD 1 2012-10-17 19.0.0
 
 ## NAME
 
@@ -13,9 +13,9 @@ tork-herald - reports modified files
 
 ## DESCRIPTION
 
-This program monitors the current working directory and prints relative paths
-of modified files in batches of single-line JSON arrays to the standard output
-stream.
+This program monitors the current working directory and all those below it
+recursively.  When any files therein are modified, it prints their relative
+paths in a single-line JSON array to stdout.
 
 ## OPTIONS
 
@@ -24,7 +24,7 @@ stream.
 
 ## SEE ALSO
 
-tork(1), tork-herald(1), tork-driver(1), tork-engine(1), tork-master(1)
+tork(1), tork-driver(1)
 
 =end =========================================================================
 

data/bin/tork-master

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# TORK-MASTER 1 2012-10-10 18.2.4
+# TORK-MASTER 1 2012-10-17 19.0.0
 
 ## NAME
 
@@ -13,39 +13,47 @@ tork-master - absorbs overhead and runs tests
 
 ## DESCRIPTION
 
-This program absorbs the test execution overhead and forks to run your tests.
-It reads the following single-line commands (JSON arrays) from its standard
-input stream and performs the respective actions as described below.
+This program absorbs your Ruby application's test execution overhead once and
+simply fork(3)s worker processses to run your tests thereafter.  As a result,
+your tests run faster because they no longer spend any time absorbing the test
+execution overhead: worker processes simply inherit the overhead when forked.
 
-`["load",` *paths*`,` *files*`]`
-  Adds the given array of *paths* to Ruby's $LOAD_PATH, loads the given array
-  of *files* after removing their ".rb" file extension if present, and prints
-  the given command line to the standard output stream.
+This program can be controlled remotely by multiple tork-remote(1) instances.
+
+### Input
+
+This program reads the following commands, which are single-line JSON arrays,
+from stdin and performs the actions described respectively.
 
 `["test",` *test_file*`,` *line_numbers*`]`
-  Runs the given *test_file* in a forked child process while instructing your
-  chosen unit testing framework (loaded by your test execution overhead) to
-  only run those tests that are defined on the given array of *line_numbers*.
+  Forks a worker process to run tests that correspond to the given
+  *line_numbers* in the given *test_file*.  If *line_numbers* is empty, then
+  the entire *test_file* will be run.
+
+`["stop",` *signal*`]`
+  Stops all tests that are currently running by sending the given *signal*
+  (optional; defaults to "SIGTERM") to their respective worker processes.
+
+`["quit"]`
+  Stops all tests that are currently running and exits.
 
-  Prints the following status messages to the standard output stream.  The
-  standard output and error streams of the forked child process are captured
-  in the *log_file* specified in these status messages.
+### Output
 
-  * Test is running:
-    `["test",` *test_file*`,` *line_numbers*`,` *log_file*`,` *worker_number*`]`
+This program prints the following messages, which are single-line JSON arrays,
+to stdout.
 
-  * Test has passed:
-    `["pass",` *test_file*`,` *line_numbers*`,` *log_file*`,` *worker_number*`,` *exit_code*`,` *exit_info*`]`
+`["absorb"]`
+  Test execution overhead has been absorbed.  We are ready for testing!
 
-  * Test has failed:
-    `["fail",` *test_file*`,` *line_numbers*`,` *log_file*`,` *worker_number*`,` *exit_code*`,` *exit_info*`]`
+`["test",` *test_file*`,` *line_numbers*`,` *log_file*`,` *worker_number*`]`
+  Test has begun running.  Its output (both stdout and stderr) is being
+  captured into *log_file* in real time, so you can watch it with `tail -f`.
 
-`["stop"]`
-  Stops all tests that are currently running and prints the given command line
-  to the standard output stream.
+`["pass",` *test_file*`,` *line_numbers*`,` *log_file*`,` *worker_number*`,` *exit_code*`,` *exit_info*`]`
+  Test has passed.
 
-`["quit"]`
-  Stops all tests that are currently running and exits.
+`["fail",` *test_file*`,` *line_numbers*`,` *log_file*`,` *worker_number*`,` *exit_code*`,` *exit_info*`]`
+  Test has failed.
 
 ## OPTIONS
 
@@ -54,19 +62,58 @@ input stream and performs the respective actions as described below.
 
 ## FILES
 
-*.tork.rb*
-  Optional Ruby script for configuring tork(1).
+*.tork/config.rb*
+  Optional Ruby script that is loaded inside the driver process on startup.
+  It can read and change the `ENV['TORK_CONFIGS']` environment variable.
+
+*.tork/master.rb*
+  Optional Ruby script that is loaded inside the master process on startup.
+  It can read and change the following variables.
+
+  > `Tork::Master::MAX_CONCURRENT_WORKERS`
+  >   Maximum number of worker processes that are allowed to be running
+  >   simultaneously at any given time.  The default value is either the
+  >   number of processors detected on your system or 1 if detection failed.
+
+*.tork/onfork.rb*
+  Optional Ruby script that is loaded inside the master process just before a
+  worker process is forked.  It can read and change the following variables.
+
+  > `$tork_test_file`
+  >   Path of the test file that will be run by the worker process.
+  >
+  > `$tork_line_numbers`
+  >   Array of line numbers in the test file that were requested to be run.
+  >
+  > `$tork_log_file`
+  >   Path of the log file that will hold the output of the worker process.
+  >
+  > `$tork_worker_number`
+  >   Sequence number of the worker process that will be forked shortly.
+
+*.tork/worker.rb*
+  Optional Ruby script that is loaded inside a worker process just after
+  it is forked.  It can read and change the following variables.
+
+  > `$tork_test_file`
+  >   Path of the test file that will be run by this worker process.
+  >
+  > `$tork_line_numbers`
+  >   Array of line numbers in the test file that were requested to be run.
+  >
+  > `$tork_log_file`
+  >   Path of the log file that will hold the output of this worker process.
+  >
+  > `$tork_worker_number`
+  >   Sequence number of this worker process.
 
 ## ENVIRONMENT
 
-`TORK_CONFIGS`
-  A single-line JSON array containing paths to actual files or names of
-  helper libraries in the tork/config/ namespace of Ruby's load path.
-  These configuration files are loaded just before *.tork.rb* is loaded.
+See tork(1).
 
 ## SEE ALSO
 
-tork(1), tork-herald(1), tork-driver(1), tork-engine(1), tork-master(1)
+tork(1), tork-remote(1)
 
 =end =========================================================================
 

data/bin/tork-notify

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+=begin =======================================================================
+
+# TORK-NOTIFY 1 2012-10-17 19.0.0
+
+## NAME
+
+tork-notify - notifies you of test status changes
+
+## SYNOPSIS
+
+`tork-notify` [*OPTION*]...
+
+## DESCRIPTION
+
+This program serves as an example of how to receive and process messages sent
+by the various programs in the tork(1) suite.  It notifies you when previously
+passing tests fail (or vice versa) through libnotify, xmessage, or growl.  If
+none are available on your system, then the notification is printed to stdout.
+
+## OPTIONS
+
+`-h`, `--help`
+  Show this help manual.
+
+## EXIT STATUS
+
+See tork-remote(1).
+
+## SEE ALSO
+
+tork-remote(1), tork-engine(1)
+
+=end =========================================================================
+
+$0 = File.basename(__FILE__) # for easier identification in ps(1) output
+
+require 'binman'
+BinMan.help
+
+require 'json'
+IO.popen('tork-remote tork-engine', 'r+') do |remote|
+  while message = remote.gets
+    event, test_file, *details = JSON.load(message)
+
+    # make notifications edge-triggered: pass => fail or vice versa.
+    # we do not care about pass => pass or fail => fail transitions.
+    icon = case event.to_sym
+           when :fail_now_pass then 'dialog-information'
+           when :pass_now_fail then 'dialog-error'
+           end
+
+    if icon
+      _, _, line_numbers, log_file = details.first
+
+      title = [event.upcase, test_file].join(' ')
+
+      statistics = File.readlines(log_file).grep(/^\d+ \w+,/).join.
+        gsub(/\e\[\d+(;\d+)?m/, '') # strip ANSI SGR escape codes
+
+      Thread.new do # run in background
+        system 'notify-send', '-i', icon, title, statistics or
+        system 'growlnotify', '-a', 'Xcode', '-m', statistics, title or
+        system 'xmessage', '-timeout', '5', '-title', title, statistics or
+        puts title, statistics, nil
+      end
+    end
+  end
+end
+exit $?.exitstatus

data/bin/tork-remote

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+=begin =======================================================================
+
+# TORK-REMOTE 1 2012-09-26 18.2.3
+
+## NAME
+
+tork-remote - controls tork(1) programs
+
+## SYNOPSIS
+
+`tork-remote` [*OPTION*]... *PROGRAM*
+
+## DESCRIPTION
+
+This program sends single-line JSON messages read from its stdin to the given
+*PROGRAM* which is already running in the same working directory as this one.
+
+If lines read from stdin are not single-line JSON messages, then they are
+split into an array of words, using the same word-splitting algorithm as
+sh(1), before being sent to the *PROGRAM* as a single-line JSON message.
+
+If the *PROGRAM* sends any messages in response, then they are printed to
+stdout if they are valid single-line JSON messages or to stderr otherwise.
+
+## OPTIONS
+
+`-h`, `--help`
+  Show this help manual.
+
+## EXIT STATUS
+
+1
+  Could not connect to the *PROGRAM*.
+
+2
+  Lost connection to the *PROGRAM*.
+
+## SEE ALSO
+
+tork(1), tork-driver(1), tork-engine(1), tork-master(1)
+
+=end =========================================================================
+
+$0 = File.basename(__FILE__) # for easier identification in ps(1) output
+
+require 'binman'
+BinMan.help
+
+require 'socket'
+require 'shellwords'
+require 'tork/server'
+
+program = ARGV.shift or raise ArgumentError, 'PROGRAM not given'
+address = Tork::Server.address(program)
+
+begin
+  UNIXSocket.open(address) do |socket|
+    # messages to remote from server
+    Thread.new do
+      while input = socket.gets
+        stream = input =~ Tork::Server::JSON_REGEXP ? STDOUT : STDERR
+        stream.puts input
+        stream.flush
+      end
+      warn "#{$0}: lost connection to #{program}"
+      exit 2
+    end
+
+    # messages from remote to server
+    while output = STDIN.gets
+      socket.puts output
+    end
+  end
+# ECONNREFUSED is for abstract namespace UNIXSocket
+rescue Errno::ENOENT, Errno::ECONNREFUSED => error
+  warn "#{$0}: could not connect to #{program}"
+  warn "#{error}#{address.inspect}"
+  exit 1
+end

data/lib/tork/cliapp.rb

@@ -0,0 +1,73 @@
+require 'tork/server'
+
+module Tork
+class CLIApp < Server
+
+  COMMANDS = {
+    't' => :run_test_file,
+    'a' => :run_all_test_files,
+    's' => :stop_running_test_files,
+    'k' => [:stop_running_test_files, :SIGKILL],
+    'p' => :rerun_passed_test_files,
+    'f' => :rerun_failed_test_files,
+    'o' => :reabsorb_overhead,
+    'q' => :quit,
+  }
+
+  def loop
+    tell @clients, 'Absorbing test execution overhead...', false
+    @driver = popen('tork-driver')
+    super
+  ensure
+    pclose @driver
+  end
+
+protected
+
+  def recv client, message
+    case client
+    when @driver
+      event, *details = message
+
+      case event_sym = event.to_sym
+      when :absorb
+        tell @clients, 'Overhead absorbed. Ready for testing!', false
+
+      when :reabsorb
+        tell @clients, 'Reabsorbing changed overhead files...', false
+
+      when :test, :pass, :fail
+        test_file, line_numbers, log_file, worker_number, exit_status = details
+        message = [event.upcase, [test_file, *line_numbers].join(':'),
+                   exit_status].compact.join(' ')
+
+        color = case event_sym
+                when :pass then "\e[34m%s\e[0m" # blue
+                when :fail then "\e[31m%s\e[0m" # red
+                end
+        message = color % message if color and STDOUT.tty?
+        message = [message, File.read(log_file), message] if event_sym == :fail
+
+        tell @clients, message, false
+      end
+    else
+      key, *args = message
+      key &&= key.lstrip[0,1].downcase
+
+      if cmd = COMMANDS[key]
+        quit if cmd == :quit
+        call = Array(cmd) + args
+        tell @clients, "Sending #{call.inspect} command...", false
+        send @driver, call
+      else
+        # user typed an invalid command so help them along
+        COMMANDS.each do |key, cmd|
+          desc = Array(cmd).join(' with ').to_s.tr('_', ' ')
+          tell @client, "Type #{key} then ENTER to #{desc}.", false
+        end
+      end
+    end
+  end
+
+end
+end

data/lib/tork/config.rb

@@ -1,100 +1,17 @@
 module Tork
-
-  Config = Struct.new(:max_forked_workers, :overhead_load_paths,
-                      :overhead_file_globs, :reabsorb_file_greps,
-                      :all_test_file_globs, :test_file_globbers,
-                      :before_fork_hooks, :after_fork_hooks,
-                      :test_event_hooks).new
-
-  #---------------------------------------------------------------------------
-  # defaults
-  #---------------------------------------------------------------------------
-
-  Config.max_forked_workers = [
-    # http://stackoverflow.com/questions/891537#6420817
-    'fgrep -c processor /proc/cpuinfo', # Linux
-    'sysctl -n hw.ncpu',                # BSD
-    'hwprefs cpu_count',                # Darwin 9
-    'hwprefs thread_count',             # Darwin 10
-  ].map {|cmd| `#{cmd} 2>/dev/null`.to_i }.push(1).max
-
-  Config.overhead_load_paths = ['lib', 'test', 'spec']
-
-  Config.overhead_file_globs = ['{test,spec}/{test,spec}_helper.rb']
-
-  Config.reabsorb_file_greps = [%r<^(test|spec)/\1_helper\.rb$>]
-
-  Config.all_test_file_globs = ['{test,spec}/**/*_{test,spec}.rb',
-                                '{test,spec}/**/{test,spec}_*.rb']
-
-  Config.test_file_globbers = {
-    # source files that correspond to test files
-    %r<^lib/.*?([^/]+)\.rb$> => lambda do |matches|
-      name = matches[1]
-      ["{test,spec}/**/#{name}_{test,spec}.rb",
-       "{test,spec}/**/{test,spec}_#{name}.rb"]
-    end,
-
-    # the actual test files themselves
-    %r<^(test|spec)/.*?(\1_[^/]+|[^/]+_\1)\.rb$> => lambda {|m| m[0] }
-  }
-
-  Config.before_fork_hooks = []
-
-  Config.after_fork_hooks = [
-    # instruct the testing framework to only run those
-    # tests that are defined on the given line numbers
-    lambda do |test_file, line_numbers, log_file, worker_number|
-      case File.basename(test_file)
-      when /(\b|_)spec(\b|_).*\.rb$/ # RSpec
-        line_numbers.each {|line| ARGV.push '--line_number', line.to_s }
-
-      when /(\b|_)test(\b|_).*\.rb$/ # Test::Unit
-        # find which tests have changed inside the test file
-        test_file_lines = File.readlines(test_file)
-        test_names = line_numbers.map do |line|
-          catch :found do
-            # search backwards from the line that changed up to
-            # the first line in the file for test definitions
-            line.downto(0) do |i|
-              test_name =
-                case test_file_lines[i]
-                when /^\s*def\s+test_(\w+)/ then $1
-                when /^\s*(test|context|should|describe|it)\b.+?(['"])(.*?)\2/
-                  # elide string interpolation and invalid method name characters
-                  $3.gsub(/\#\{.*?\}/, ' ').strip.gsub(/\W+/, '.*')
-                end \
-              and throw :found, test_name
-            end; nil # prevent unsuccessful search from returning an integer
-          end
-        end.compact.uniq
-
-        unless test_names.empty?
-          ARGV.push '--name', "/(?i:#{test_names.join('|')})/"
-        end
-      end
-    end
-  ]
-
-  Config.test_event_hooks = []
-
-  #---------------------------------------------------------------------------
-  # overrides
-  #---------------------------------------------------------------------------
-
-  if File.exist? user_config_file = '.tork.rb'
-    load user_config_file
-  end
-
-  if ENV.key? 'TORK_CONFIGS'
-    require 'json'
-    JSON.load(ENV['TORK_CONFIGS']).each do |config|
-      if File.file? config
-        load File.expand_path(config)
-      else
-        require "tork/config/#{config}"
-      end
-    end
+  # Loads all Ruby scripts found having the given name in (1) the directories
+  # specified in the TORK_CONFIGS environment variable, (2) the subdirectories
+  # of lib/tork/config/, and (3) the user's .tork/ directory; in that order.
+  #
+  # @return [Array] paths of Ruby scripts that were loaded
+  #
+  def self.config name
+    dirs = ENV['TORK_CONFIGS'].strip.split(/:+/).reject(&:empty?).uniq.
+           map {|dir| [dir, __FILE__.sub(/\.rb$/, "/#{dir}")] }.flatten
+
+    Dir["{#{dirs.join(',')},.tork}/#{name}.rb"].each {|script| load script }
   end
-
 end
+
+ENV['TORK_CONFIGS'] ||= 'default'.freeze # ENV values come frozen by default
+Tork.config :config