testr 14.0.3 → 14.1.0

data/HISTORY.markdown

@@ -1,15 +1,44 @@
 ------------------------------------------------------------------------------
-Version 14.0.3 (2011-10-11)
+Version 14.1.0 (2011-11-03)
 ------------------------------------------------------------------------------
 
+New features:
+
+* Make servers responsive to quit request (SIGTERM) from upstream.
+
+  This change lets the user quit testr-master(1) while it is loading
+  test execution overhead (which can be a lengthy, blocking operation).
+
+  By sending a signal to the server, we don't have to wait for it to
+  finish processing its current command before seeing our :quit command.
+
+* Add embedded BinMan manual pages to bin scripts.  All TestR scripts now
+  have a `--help` option which displays their UNIX manual page.  Try it!
+
+  The single-line JSON message protocol used by these scripts is now
+  documented in their manual pages, so you should have everything you
+  need to create *your own custom user interface to TestR* if you wish! :-)
+
 Bug fixes:
 
-* Forgot to migrate the `testr/config/rails` configuration helper to use the
-  new TestR configuration parameter names.
+* SIGCHLD does not awaken main thread in Ruby 1.9.3p0.
 
 Housekeeping:
 
-* README: add Gemfile howto for guard FS monitoring.
+* Simplify watch(1) ps(1) process title monitoring.
+
+* Testr: tell user to press ENTER after command key.
+
+* README: add tip on loading factory_girl factories.
+
+------------------------------------------------------------------------------
+Version 14.0.3 (2011-10-11)
+------------------------------------------------------------------------------
+
+Bug fixes:
+
+* Forgot to migrate the `testr/config/rails` configuration helper to use the
+  new TestR configuration parameter names.
 
 ------------------------------------------------------------------------------
 Version 14.0.2 (2011-10-11)

data/README.markdown

@@ -64,13 +64,6 @@ As a Ruby gem:
 
     gem install testr
 
-In a Gemfile:
-
-    gem 'testr', :require => false
-    gem 'rb-inotify', :require => false if RUBY_PLATFORM =~ /linux/i
-    gem 'rb-fsevent', :require => false if RUBY_PLATFORM =~ /darwin/i
-    gem 'rb-fchange', :require => false if RUBY_PLATFORM =~ /mingw/i
-
 As a Git clone:
 
     git clone git://github.com/sunaku/testr
@@ -247,6 +240,28 @@ Support for the [Ruby on Rails](http://rubyonrails.org) web framework.
 Support for the [parallel_tests](https://github.com/grosser/parallel_tests)
 library.
 
+------------------------------------------------------------------------------
+Usage tips
+------------------------------------------------------------------------------
+
+### [factory_girl](https://github.com/thoughtbot/factory_girl) factories
+
+Don't load your factories in master process (as part of your test execution
+overhead) because that would necessitate the reloading of said overhead
+whenever you change an existing factory definition or create a new one.
+
+Instead, use `at_exit()` to wait until (1) after the master process has forked
+a worker process and (2) just before that worker process runs its test suite
+(whose execution is started by your test framework's own `at_exit()` handler).
+
+This way, worker processes will pick up changes in your factories "for free"
+whenever they (re)run your test files.  Also, don't load your factories or do
+anything else in your `at_exit()` handler if Ruby is exiting because of a
+raised exception (denoted by the `$!` global variable in the snippet below).
+
+    require 'factory_girl'
+    at_exit { FactoryGirl.find_definitions unless $! }
+
 ------------------------------------------------------------------------------
 Known issues
 ------------------------------------------------------------------------------

data/Rakefile

@@ -1 +1,2 @@
 require "bundler/gem_tasks"
+require 'binman/rake_tasks'

data/bin/testr

@@ -1,4 +1,52 @@
 #!/usr/bin/env ruby
+=begin
+
+TESTR 1 "2011-11-03" "14.1.0" "TestR User Manuals"
+==================================================
+
+NAME
+----
+
+testr - Continuous testing tool for Ruby
+
+SYNOPSIS
+--------
+
+`testr` [*OPTION*]...
+
+DESCRIPTION
+-----------
+
+This program is a simple command-line user interface for testr-driver(1).  It
+demonstrates how the components of TestR work together and also serves as an
+example of how you can create your own TestR user interface.
+
+When run, it presents you with a menu of single-character commands that you
+can enter, loads the test execution overhead into testr-master(1), and
+finally notifies you when the master is ready to run test files.
+
+It also launches testr-herald(1) alongside testr-master(1).  When the herald
+reports a modified file that belongs to the test execution overhead, this
+program notifies you accordingly and then replaces the current master with a
+new one that will absorb the modified test execution overhead into itself.
+
+OPTIONS
+-------
+
+`-h`, `--help`
+  Display this help manual using man(1).
+
+SEE ALSO
+--------
+
+testr(1), testr-driver(1), testr-master(1), testr-herald(1)
+
+=end =========================================================================
+
+$0 = File.basename(__FILE__)
+
+require 'binman'
+BinMan.help
 
 require 'json'
 require 'testr/client'
@@ -34,7 +82,9 @@ COMMANDS = {
 }
 
 def COMMANDS.show
-  each {|key, cmd| warn "testr: Type #{key} to #{cmd.to_s.tr('_', ' ')}." }
+  each do |key, cmd|
+    warn "testr: Type #{key} then ENTER to #{cmd.to_s.tr('_', ' ')}."
+  end
 end
 
 COMMANDS.show # instruct newbies

data/bin/testr-driver

@@ -1,4 +1,67 @@
 #!/usr/bin/env ruby
+=begin
+
+TESTR-DRIVER 1 "2011-11-03" "14.1.0" "TestR User Manuals"
+=========================================================
+
+NAME
+----
+
+testr-driver - tells master to run tests and keeps track of test results
+
+SYNOPSIS
+--------
+
+`testr-driver` [*OPTION*]...
+
+DESCRIPTION
+-----------
+
+This program reads the following single-line commands (JSON arrays) from its
+standard input stream and performs the respective actions as described below.
+It also funnels the standard output stream of testr-master(1) into its own.
+
+`["run_all_test_files"]`
+  Runs all test files found within and beneath the current working directory.
+
+`["stop_running_test_files"]`
+  Stops any test files that are currently running.
+
+`["rerun_passed_test_files"]`
+  Runs all test files that have passed during their most recent run.
+
+`["reabsorb_overhead_files"]`
+  Stops any test files that are currently running, reabsorbs the test
+  execution overhead, and resumes running those interrupted test files.
+
+`["quit"]`
+  Stops all tests that are currently running and exits.
+
+OPTIONS
+-------
+
+`-h`, `--help`
+  Display this help manual using man(1).
+
+FILES
+-----
+
+`.testr.rb`
+  Ruby script in the directory where testr(1) is run.
+
+SEE ALSO
+--------
+
+testr(1), testr-driver(1), testr-master(1), testr-herald(1)
+
+=end =========================================================================
+
+$0 = File.basename(__FILE__)
+
+require 'binman'
+BinMan.help
+
 require 'testr/driver'
 TestR::Driver.loop
+
 Process.waitall

data/bin/testr-herald

@@ -1,9 +1,47 @@
 #!/usr/bin/env ruby
-STDOUT.sync = true
+=begin
+
+TESTR-HERALD 1 "2011-11-03" "14.1.0" "TestR User Manuals"
+=========================================================
+
+NAME
+----
+
+testr-herald - monitors current directory tree and reports modified files
+
+SYNOPSIS
+--------
+
+`testr-herald` [*OPTION*]...
+
+DESCRIPTION
+-----------
+
+This program monitors the current working directory and prints relative paths
+of modified files, one per line, to the standard output stream.
+
+OPTIONS
+-------
+
+`-h`, `--help`
+  Display this help manual using man(1).
+
+SEE ALSO
+--------
+
+testr(1), testr-driver(1), testr-master(1), testr-herald(1)
+
+=end =========================================================================
+
+$0 = File.basename(__FILE__)
+
+require 'binman'
+BinMan.help
 
 require 'guard'
 require 'guard/listener'
 
 listener = Guard::Listener.select_and_init
 listener.on_change {|files| puts files }
+STDOUT.sync = true # don't buffer puts()
 listener.start

data/bin/testr-master

@@ -1,5 +1,79 @@
 #!/usr/bin/env ruby
+=begin
+
+TESTR-MASTER 1 "2011-11-03" "14.1.0" "TestR User Manuals"
+=========================================================
+
+NAME
+----
+
+testr-master - absorbs test execution overhead and forks to run your tests
+
+SYNOPSIS
+--------
+
+`testr-master` [*OPTION*]...
+
+DESCRIPTION
+-----------
+
+This program reads the following single-line commands (JSON arrays) from its
+standard input stream and performs the respective actions as described below.
+
+`["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.
+
+`["test",` *test_file*`,` *test_names*`]`
+  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 named in the given array of *test_names*.
+
+  Prints the given command line to the standard output stream immediately
+  after forking the child process.
+
+  Prints the given command line, modified with `"pass"` (if the test passed)
+  or `"fail"` (if the test failed) in place of `"test"`, to the standard
+  output stream after the forked child process finishes.
+
+  The standard output and error streams of the forked child process are
+  redirected to a file whose path and name are the same as that of the test
+  file being run by the forked child process but with ".log" appended.
+
+`["stop"]`
+  Stops all tests that are currently running and prints the given command line
+  to the standard output stream.
+
+`["quit"]`
+  Stops all tests that are currently running and exits.
+
+OPTIONS
+-------
+
+`-h`, `--help`
+  Display this help manual using man(1).
+
+FILES
+-----
+
+`.testr.rb`
+  Ruby script in the directory where testr(1) is run.
+
+SEE ALSO
+--------
+
+testr(1), testr-driver(1), testr-master(1), testr-herald(1)
+
+=end =========================================================================
+
+$0 = File.basename(__FILE__)
+
+require 'binman'
+BinMan.help
+
 require 'testr/master'
 TestR::Master.loop
+
 Process.waitall
 raise SystemExit # prevent empty test suite from running in the master process

data/lib/testr/client.rb

@@ -28,11 +28,6 @@ module Client
         @io.puts JSON.dump(command)
       end
     end
-
-    def quit
-      send [:quit]
-      super
-    end
   end
 
 end

data/lib/testr/master.rb

@@ -22,8 +22,7 @@ module Master
 
   def test test_file, test_names
     # throttle forking rate to meet the maximum concurrent workers limit
-    # NOTE: the next SIGCHLD signal will wake us from this eternal sleep
-    sleep until @command_by_worker_pid.size < Config.max_forked_workers
+    sleep 1 until @command_by_worker_pid.size < Config.max_forked_workers
 
     log_file = test_file + '.log'
     worker_number = @worker_number_pool.shift

data/lib/testr/server.rb

@@ -28,5 +28,9 @@ module Server
     end
   end
 
+  def self.extended target
+    trap(:SIGTERM){ target.quit }
+  end
+
 end
 end

data/lib/testr/version.rb

@@ -1,3 +1,3 @@
 module TestR
-  VERSION = "14.0.3"
+  VERSION = "14.1.0"
 end

data/man/man1/testr-driver.1

@@ -0,0 +1,47 @@
+.TH TESTR-DRIVER 1 "2011-11-03" "14.1.0" "TestR User Manuals"
+.SH NAME
+.PP
+testr-driver \- tells master to run tests and keeps track of test results
+.SH SYNOPSIS
+.PP
+\fBtestr-driver\fP [\fIOPTION\fP]...
+.SH DESCRIPTION
+.PP
+This program reads the following single-line commands (JSON arrays) from its
+standard input stream and performs the respective actions as described below.
+It also funnels the standard output stream of 
+.BR testr-master (1) 
+into its own.
+.TP
+\fB["run_all_test_files"]\fP
+Runs all test files found within and beneath the current working directory.
+.TP
+\fB["stop_running_test_files"]\fP
+Stops any test files that are currently running.
+.TP
+\fB["rerun_passed_test_files"]\fP
+Runs all test files that have passed during their most recent run.
+.TP
+\fB["reabsorb_overhead_files"]\fP
+Stops any test files that are currently running, reabsorbs the test
+execution overhead, and resumes running those interrupted test files.
+.TP
+\fB["quit"]\fP
+Stops all tests that are currently running and exits.
+.SH OPTIONS
+.TP
+\fB-h\fP, \fB--help\fP
+Display this help manual using 
+.BR man (1).
+.SH FILES
+.TP
+\fB.testr.rb\fP
+Ruby script in the directory where 
+.BR testr (1) 
+is run.
+.SH SEE ALSO
+.PP
+.BR testr (1), 
+.BR testr-driver (1), 
+.BR testr-master (1), 
+.BR testr-herald (1)

data/man/man1/testr-herald.1

@@ -0,0 +1,22 @@
+.TH TESTR-HERALD 1 "2011-11-03" "14.1.0" "TestR User Manuals"
+.SH NAME
+.PP
+testr-herald \- monitors current directory tree and reports modified files
+.SH SYNOPSIS
+.PP
+\fBtestr-herald\fP [\fIOPTION\fP]...
+.SH DESCRIPTION
+.PP
+This program monitors the current working directory and prints relative paths
+of modified files, one per line, to the standard output stream.
+.SH OPTIONS
+.TP
+\fB-h\fP, \fB--help\fP
+Display this help manual using 
+.BR man (1).
+.SH SEE ALSO
+.PP
+.BR testr (1), 
+.BR testr-driver (1), 
+.BR testr-master (1), 
+.BR testr-herald (1)

data/man/man1/testr-master.1

@@ -0,0 +1,56 @@
+.TH TESTR-MASTER 1 "2011-11-03" "14.1.0" "TestR User Manuals"
+.SH NAME
+.PP
+testr-master \- absorbs test execution overhead and forks to run your tests
+.SH SYNOPSIS
+.PP
+\fBtestr-master\fP [\fIOPTION\fP]...
+.SH DESCRIPTION
+.PP
+This program reads the following single-line commands (JSON arrays) from its
+standard input stream and performs the respective actions as described below.
+.TP
+\fB["load",\fP \fIpaths\fP\fB,\fP \fIfiles\fP\fB]\fP
+Adds the given array of \fIpaths\fP to Ruby's $LOAD_PATH, loads the given array
+of \fIfiles\fP after removing their ".rb" file extension if present, and prints
+the given command line to the standard output stream.
+.TP
+\fB["test",\fP \fItest_file\fP\fB,\fP \fItest_names\fP\fB]\fP
+Runs the given \fItest_file\fP 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 named in the given array of \fItest_names\fP.
+.IP
+Prints the given command line to the standard output stream immediately
+after forking the child process.
+.IP
+Prints the given command line, modified with \fB"pass"\fP (if the test passed)
+or \fB"fail"\fP (if the test failed) in place of \fB"test"\fP, to the standard
+output stream after the forked child process finishes.
+.IP
+The standard output and error streams of the forked child process are
+redirected to a file whose path and name are the same as that of the test
+file being run by the forked child process but with ".log" appended.
+.TP
+\fB["stop"]\fP
+Stops all tests that are currently running and prints the given command line
+to the standard output stream.
+.TP
+\fB["quit"]\fP
+Stops all tests that are currently running and exits.
+.SH OPTIONS
+.TP
+\fB-h\fP, \fB--help\fP
+Display this help manual using 
+.BR man (1).
+.SH FILES
+.TP
+\fB.testr.rb\fP
+Ruby script in the directory where 
+.BR testr (1) 
+is run.
+.SH SEE ALSO
+.PP
+.BR testr (1), 
+.BR testr-driver (1), 
+.BR testr-master (1), 
+.BR testr-herald (1)

data/man/man1/testr.1

@@ -0,0 +1,40 @@
+.TH TESTR 1 "2011-11-03" "14.1.0" "TestR User Manuals"
+.SH NAME
+.PP
+testr \- Continuous testing tool for Ruby
+.SH SYNOPSIS
+.PP
+\fBtestr\fP [\fIOPTION\fP]...
+.SH DESCRIPTION
+.PP
+This program is a simple command-line user interface for 
+.BR testr-driver (1).  
+It
+demonstrates how the components of TestR work together and also serves as an
+example of how you can create your own TestR user interface.
+.PP
+When run, it presents you with a menu of single-character commands that you
+can enter, loads the test execution overhead into 
+.BR testr-master (1), 
+and
+finally notifies you when the master is ready to run test files.
+.PP
+It also launches 
+.BR testr-herald (1) 
+alongside 
+.BR testr-master (1).  
+When the herald
+reports a modified file that belongs to the test execution overhead, this
+program notifies you accordingly and then replaces the current master with a
+new one that will absorb the modified test execution overhead into itself.
+.SH OPTIONS
+.TP
+\fB-h\fP, \fB--help\fP
+Display this help manual using 
+.BR man (1).
+.SH SEE ALSO
+.PP
+.BR testr (1), 
+.BR testr-driver (1), 
+.BR testr-master (1), 
+.BR testr-herald (1)

data/testr.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |s|
   s.summary     = "Continuous testing tool for Ruby"
   s.description = nil
 
-  s.files         = `git ls-files`.split("\n")
+  s.files         = `git ls-files`.split("\n") + Dir['man/**/*']
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
@@ -22,4 +22,13 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency "json", ">= 1.6.1"
   s.add_runtime_dependency "guard", ">= 0.8.4"
   s.add_runtime_dependency "diff-lcs", ">= 1.1.2"
+
+  # add binman and all of its development dependencies
+  binman_gem = ['binman', '~> 1']
+  s.add_runtime_dependency(*binman_gem)
+  binman_vers = Gem::Dependency.new(*binman_gem)
+  binman_spec = Gem::SpecFetcher.fetcher.fetch(binman_vers).flatten.first
+  binman_spec.development_dependencies.unshift(binman_vers).each do |dep|
+    s.add_development_dependency dep.name, dep.requirements_list
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: testr
 version: !ruby/object:Gem::Version
-  version: 14.0.3
+  version: 14.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -13,11 +13,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-10-12 00:00:00.000000000 Z
+date: 2011-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &15214300 !ruby/object:Gem::Requirement
+  requirement: &23388540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -25,10 +25,10 @@ dependencies:
         version: 1.6.1
   type: :runtime
   prerelease: false
-  version_requirements: *15214300
+  version_requirements: *23388540
 - !ruby/object:Gem::Dependency
   name: guard
-  requirement: &15213320 !ruby/object:Gem::Requirement
+  requirement: &23387820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -36,10 +36,10 @@ dependencies:
         version: 0.8.4
   type: :runtime
   prerelease: false
-  version_requirements: *15213320
+  version_requirements: *23387820
 - !ruby/object:Gem::Dependency
   name: diff-lcs
-  requirement: &15212380 !ruby/object:Gem::Requirement
+  requirement: &23386940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -47,7 +47,40 @@ dependencies:
         version: 1.1.2
   type: :runtime
   prerelease: false
-  version_requirements: *15212380
+  version_requirements: *23386940
+- !ruby/object:Gem::Dependency
+  name: binman
+  requirement: &23386420 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: *23386420
+- !ruby/object:Gem::Dependency
+  name: binman
+  requirement: &25642060 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: *25642060
+- !ruby/object:Gem::Dependency
+  name: redcarpet-manpage
+  requirement: &25641520 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+  type: :development
+  prerelease: false
+  version_requirements: *25641520
 description: ''
 email:
 - sunaku@gmail.com
@@ -82,6 +115,10 @@ files:
 - lib/testr/server.rb
 - lib/testr/version.rb
 - testr.gemspec
+- man/man1/testr-driver.1
+- man/man1/testr-master.1
+- man/man1/testr-herald.1
+- man/man1/testr.1
 homepage: http://github.com/sunaku/testr
 licenses: []
 post_install_message: 
@@ -107,3 +144,4 @@ signing_key:
 specification_version: 3
 summary: Continuous testing tool for Ruby
 test_files: []
+has_rdoc: