testr 14.0.0

data/LICENSE

@@ -0,0 +1,19 @@
+(the ISC license)
+
+Copyright 2010 Suraj N. Kurapati <sunaku@gmail.com>
+Copyright 2011 Brian D. Burns <burns180@gmail.com>
+Copyright 2011 Daniel Pittman <daniel@rimspace.net>
+Copyright 2011 Jacob Helwig <jacob@technosorcery.net>
+Copyright 2011 Corné Verbruggen <corne@g-majeur.nl>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,269 @@
+TestR - Continuous testing tool for Ruby
+==============================================================================
+
+TestR is a continuous testing tool for Ruby that automatically detects and
+tests changes in your Ruby application or test suite in an efficient manner:
+
+  1. Absorbs test execution overhead into the master Ruby process.
+
+  2. Forks to run your test files in parallel and without overhead.
+
+  3. Avoids running unchanged tests inside changed test files.
+
+------------------------------------------------------------------------------
+Features
+------------------------------------------------------------------------------
+
+  * Executes test files in parallel, making full use of multi-core CPUs.
+
+  * Tests *changes* in your Ruby application: avoids running (1) unchanged
+    test files and (2) unchanged tests inside changed test files.
+
+  * Supports MiniTest, Test::Unit, RSpec, and any testing framework that (1)
+    reflects failures in the process' exit status and (2) is loaded by your
+    application's `test/test_helper.rb` or `spec/spec_helper.rb` file.
+
+  * Logs the output from your tests into separate files: one log per test.
+    The path of a log file is simply the path of its test file plus ".log".
+
+  * Configurable through a Ruby script in your current working directory.
+
+  * Implemented in less than 360 lines (SLOC) of pure Ruby code! :-)
+
+------------------------------------------------------------------------------
+Architecture
+------------------------------------------------------------------------------
+
+Following UNIX philosophy, TestR is made of simple text-based programs:
+
+* `testr` is an interactive command-line user interface (CLI) for driver
+* `testr-herald` monitors current directory tree and reports changed files
+* `testr-driver` tells master to run tests and keeps track of test results
+* `testr-master` absorbs test execution overhead and forks to run your tests
+
+You can build your own custom TestR user interface by wrapping `testr-driver`!
+
+------------------------------------------------------------------------------
+Prerequisites
+------------------------------------------------------------------------------
+
+  * Ruby 1.8.7 or 1.9.2 or newer.
+
+  * Operating system that supports POSIX signals and the `fork()` system call.
+
+    To check if your system qualifies, launch `irb` and enter the following:
+
+        Process.respond_to? :fork  # must be true
+        Signal.list.key? 'TERM'    # must be true
+        Signal.list.key? 'KILL'    # must be true
+
+------------------------------------------------------------------------------
+Installation
+------------------------------------------------------------------------------
+
+As a Ruby gem:
+
+    gem install testr
+
+As a Git clone:
+
+    git clone git://github.com/sunaku/testr
+    cd testr
+    bundle install
+
+------------------------------------------------------------------------------
+Invocation
+------------------------------------------------------------------------------
+
+If installed as a Ruby gem:
+
+    testr
+
+If installed as a Git clone:
+
+    bundle exec ruby -Ilib bin/testr
+
+You can monitor your test processes in another terminal:
+
+    watch 'ps xuw | sed -n "1p; /test[r]/p" | fgrep -v sed'
+
+You can forcefully terminate TestR from another terminal:
+
+    pkill -f testr
+
+------------------------------------------------------------------------------
+Configuration
+------------------------------------------------------------------------------
+
+TestR looks for a configuration file named `.testr.rb` in its current working
+directory.  The configuration file is a normal Ruby script.  Inside it, you
+can query and modify the `TestR::Config` object (OpenStruct) according to the
+configuration options listed below.
+
+------------------------------------------------------------------------------
+Configuration options
+------------------------------------------------------------------------------
+
+### TestR::Config.max_forked_workers
+
+Maximum number of worker processes at any given time.  The default value is
+the number of processors detected on your system, or 1 if detection fails.
+
+### TestR::Config.overhead_load_paths
+
+Array of paths that are prepended to Ruby's `$LOAD_PATH` before the
+test execution overhead is loaded into `testr-master`.
+
+### TestR::Config.overhead_file_globs
+
+Array of file globbing patterns that describe a set of Ruby scripts that are
+loaded into `testr-master` as test execution overhead.
+
+### TestR::Config.reabsorb_file_greps
+
+Array of regular expressions that describe a set of file paths that cause the
+test execution overhead to be reabsorbed in `testr-master` when they change.
+
+### TestR::Config.all_test_file_globs
+
+Array of file globbing patterns that describe the set of all test files in
+your Ruby application.
+
+### TestR::Config.test_file_globbers
+
+Hash that maps (1) a regular expression describing a set of file paths to (2)
+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 followed
+by an underscore and the file name in reverse like this:
+
+  * `lib/hello.rb` => `test/hello_olleh.rb`
+  * `app/world.rb` => `spec/world_ldrow.rb`
+
+Then you would add the following to your configuration file:
+
+    TestR::Config.test_file_globbers[%r<^(lib|app)/.+\.rb$>] = lambda do |path|
+      name = File.basename(path, '.rb')
+      "{test,spec}/**/#{name}_#{name.reverse}.rb"
+    end
+
+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:
+
+    TestR::Config.test_file_globbers[%r<^(lib|app)/.+\.rb$>] = lambda do |path|
+      if path.include? '/models/'
+        "{test,spec}/**/#{File.basename(path)}"
+      end
+    end
+
+### TestR::Config.test_name_extractor
+
+Lambda function that is given a line of source code to determine whether it
+can be considered as a test definition.  In which case, the function must
+extract and return the name of the test being defined.
+
+### TestR::Config.before_fork_hooks
+
+Array of lambda functions that are executed inside `testr-master` before a
+worker process is forked to run a test file.  These functions are given:
+
+1. The sequence number of the worker process that will be forked shortly.
+
+2. The path of the log file containing the live output of the worker process.
+
+3. The path of the test file that will be run by the worker process.
+
+4. An array of names of tests inside the test file that will be run.  If this
+   array is empty, then all tests in the test file will be run.
+
+For example, to see some real values:
+
+    TestR::Config.before_fork_hooks << lambda {
+      |worker_number, log_file, test_file, test_names|
+
+      p :before_fork_hooks => {
+        :worker_number => worker_number,
+        :log_file      => log_file,
+        :test_file     => test_file,
+        :test_names    => test_names,
+      }
+    }
+
+### TestR::Config.after_fork_hooks
+
+Array of lambda functions that are executed inside a worker process forked
+by `testr-master`.  These functions are given:
+
+1. The sequence number of the worker process.
+
+2. The path of the log file containing the live output of the worker process.
+
+3. The path of the test file that will be run by the worker process.
+
+4. An array of names of tests inside the test file that will be run.  If this
+   array is empty, then all tests in the test file will be run.
+
+For example, to see some real values, including the worker process' PID:
+
+    TestR::Config.after_fork_hooks << lambda {
+      |worker_number, log_file, test_file, test_names|
+
+      p :after_fork_hooks => {
+        :worker_pid    => $$,
+        :worker_number => worker_number,
+        :log_file      => log_file,
+        :test_file     => test_file,
+        :test_names    => test_names,
+      }
+    }
+
+The first function in this array instructs Test::Unit and RSpec to only run
+those tests that correspond to the given `test_names` values.  This
+accelerates your test-driven development cycle and improves productivity!
+
+------------------------------------------------------------------------------
+Configuration helpers
+------------------------------------------------------------------------------
+
+The following libraries assist you with configuring TestR.  To use them,
+simply add the require() lines shown below to your configuration file.
+
+### require 'testr/config/rails'
+
+Support for the [Ruby on Rails](http://rubyonrails.org) web framework.
+
+### require 'testr/config/parallel_tests'
+
+Support for the [parallel_tests](https://github.com/grosser/parallel_tests)
+library.
+
+------------------------------------------------------------------------------
+Known issues
+------------------------------------------------------------------------------
+
+### Ruby on Rails
+
+  * Ensure that your `config/environments/test.rb` file disables class caching
+    as follows (**NOTE:** if you are using Rails 3, the `testr/config/rails`
+    configuration helper can do this for you automatically):
+
+        config.cache_classes = false
+
+    Otherwise, TestR will appear to ignore source-code changes in your
+    models, controllers, helpers, and other Ruby source files.
+
+  * SQLite3 [raises `SQLite3::BusyException: database is locked` errors](
+    https://github.com/sunaku/test-loop/issues/2 ) because TestR runs your
+    test files in parallel.  You can work around this by using an [in-memory
+    adapter for SQLite3]( https://github.com/mvz/memory_test_fix ) or by using
+    different database software (such as MySQL) for your test environment.
+
+------------------------------------------------------------------------------
+License
+------------------------------------------------------------------------------
+
+Released under the ISC license.  See the LICENSE file for details.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/testr

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+require 'json'
+require 'testr/client'
+
+@driver = TestR::Client::Transceiver.new('testr-driver') do |line|
+  event, *details = JSON.load(line)
+
+  case event = event.to_sym
+  when :load then warn 'testr: Overhead absorbed; Ready for testing!'
+  when :over then warn 'testr: Reabsorbing changed overhead files...'
+  else
+    test_file, test_names, *details = details
+    message = [event.upcase, test_file, test_names.inspect, details].join(' ')
+
+    color = case event
+            when :pass then "\e[32m%s\e[0m" # green
+            when :fail then "\e[31m%s\e[0m" # red
+            end
+    message = color % message if color and STDOUT.tty?
+    message = [message, File.read(test_file + '.log'), message] if event == :fail
+
+    puts message
+  end
+end
+
+COMMANDS = {
+  'r' => :run_all_test_files,
+  's' => :stop_running_test_files,
+  'p' => :rerun_passed_test_files,
+  'f' => :rerun_failed_test_files,
+  'o' => :reabsorb_overhead_files,
+  'q' => :quit,
+}
+
+def COMMANDS.show
+  each {|key, cmd| warn "testr: Type #{key} to #{cmd.to_s.tr('_', ' ')}." }
+end
+
+COMMANDS.show # instruct newbies
+
+while key = STDIN.gets.chomp
+  if command = COMMANDS[key]
+    if command == :quit
+      @driver.quit
+      break
+    else
+      @driver.send [command]
+    end
+  else
+    COMMANDS.show
+  end
+end
+
+Process.waitall

data/bin/testr-driver

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require 'testr/driver'
+TestR::Driver.loop
+Process.waitall

data/bin/testr-herald

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+STDOUT.sync = true
+
+require 'guard'
+require 'guard/listener'
+
+listener = Guard::Listener.select_and_init
+listener.on_change {|files| puts files }
+listener.start

data/bin/testr-master

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require 'testr/master'
+TestR::Master.loop
+raise SystemExit # prevent empty test suite from running in the master process

data/lib/testr/client.rb

@@ -0,0 +1,39 @@
+module TestR
+module Client
+
+  class Receiver < Thread
+    def initialize *popen_args
+      (@io = IO.popen(*popen_args)).sync = true
+      super() { loop { yield @io.gets } }
+    end
+
+    def quit
+      kill # stop the receive loop
+      Process.kill :SIGTERM, @io.pid
+      Process.wait @io.pid # reap zombie
+      @io.close # prevent subsequent I/O
+    end
+  end
+
+  class Transceiver < Receiver
+    def initialize *popen_args
+      @io_write_lock = Mutex.new
+      popen_args[1] = 'w+'
+      super
+    end
+
+    def send command
+      @io_write_lock.synchronize do
+        warn "#{caller[2]} SEND #{command.inspect}" if $DEBUG
+        @io.puts JSON.dump(command)
+      end
+    end
+
+    def quit
+      send [:quit]
+      super
+    end
+  end
+
+end
+end

data/lib/testr/config.rb

@@ -0,0 +1,63 @@
+require 'ostruct'
+
+module TestR
+  _user_config_file = '.testr.rb'
+
+  Config = OpenStruct.new
+
+  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 = [/^#{Regexp.quote(_user_config_file)}$/,
+                                %r<(test|spec)/\1_helper\.rb>]
+
+  Config.all_test_file_globs = ['{test,spec}/**/*_{test,spec}.rb']
+
+  Config.test_file_globbers = {
+    # source files that correspond to test files
+    %r<^lib/.+\.rb$> => lambda do |path|
+      base = File.basename(path, '.rb')
+      "{test,spec}/**/#{base}_{test,spec}.rb"
+    end,
+
+    # the actual test files themselves
+    %r<^(test|spec)/.+_\1\.rb$> => lambda {|path| path }
+  }
+
+  Config.test_name_extractor = 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
+
+  Config.before_fork_hooks = []
+
+  Config.after_fork_hooks = [
+    # tell testing framework to only run the named tests inside the test file
+    lambda do |worker_number, log_file, test_file, test_names|
+      unless test_names.empty?
+        regexp = Regexp.union(test_names.map {|name|
+          # sanitize string interpolations and invalid method name characters
+          name.gsub(/\#\{.*?\}/, ' ').strip.gsub(/\W+/, '.*')
+        })
+
+        case File.basename(test_file)
+        when /(\b|_)test(\b|_)/ then ARGV.push '--name', regexp.inspect
+        when /(\b|_)spec(\b|_)/ then ARGV.push '--example', regexp.source
+        end
+      end
+    end
+  ]
+
+  load _user_config_file if File.exist? _user_config_file
+end