tork 18.2.4 → 19.0.0

data/bin/tork

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# TORK 1 2012-10-10 18.2.4
+# TORK 1 2012-10-17 19.0.0
 
 ## NAME
 
@@ -13,20 +13,108 @@ tork - Continuous testing tool for Ruby
 
 ## DESCRIPTION
 
-This program is a simple command-line user interface for tork-driver(1).  It
-loads the given *CONFIG* files (which are either paths to actual files or
-names of helper libraries in the tork/config/ namespace of Ruby's load path)
-and then waits for you to supply interactive commands on its stdin.  You may
+This program is a simple command-line user interface for tork-driver(1).
+
+First, it applies the given *CONFIG* values, which are either (1) paths to
+directories that contain configuration files or (2) names of configuration
+helpers listed in the description of the `TORK_CONFIGS` environment variable.
+
+Next, it waits for you to supply interactive commands either (1) directly on
+its stdin or (2) remotely through tork-remote(1).  From then onward, you may
 press the ENTER key (supplying no command) to see a menu of accepted commands.
 
+Some interactive commands accept additional arguments, described as follows.
+
+`t` *test_file* [*line_number*]...
+  Runs the given *test_file* while only running those tests that are defined
+  on the given list of *line_number*s.  If no *line_number*s are given, then
+  only those tests that have changed since the last run of the *test_file*
+  will now be run.
+
+`s` [*signal*]
+  Stops test files that are currently running by sending the given *signal*
+  (optional; defaults to `SIGTERM`) to their respective worker processes.
+
+This program can be controlled remotely by multiple tork-remote(1) instances.
+
 ## OPTIONS
 
 `-h`, `--help`
   Show this help manual.
 
+## FILES
+
+*.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.
+
+## ENVIRONMENT
+
+`TORK_CONFIGS`
+  Colon-separated (:) list of either paths to directories that contain
+  configuration files or names of the following configuration helpers.
+  If this variable is not set, then its value is assumed to be "default".
+
+  > `default`
+  >   Loads the following configuration helpers (as appropriate) if your
+  >   current working directory appears to utilize what they configure.
+  >   See below for complete descriptions of these configuration helpers.
+  >
+  >   * rails
+  >   * test
+  >   * spec
+  >   * cucumber
+  >   * factory_girl
+  >
+  > `dotlog`
+  >   Hides log files by prefixing their names with a period (dot).
+  >
+  > `logdir`
+  >   Keeps log files away from your tests, in the `log/` directory.
+  >
+  > `coverage`
+  >   Measures C0 code coverage under Ruby 1.9 and dumps a hash in YAML
+  >   format at the end of your log file containing every Ruby script that
+  >   was loaded from the current working directory or any of its descendant
+  >   directories (the key) mapped to the following information (the value):
+  >
+  > > `:grade`
+  > >   Percentage of source lines that were C0 covered.
+  > >
+  > > `:nsloc`
+  > >   Total number of source lines of code in the file.
+  > >
+  > > `:holes`
+  > >   Line numbers of source lines that were not covered.
+  >
+  > `test`
+  >   Supports the Test::Unit standard library.
+  >
+  > `spec`
+  >   Supports the [RSpec] testing framework.
+  >
+  > `cucumber`
+  >   Supports the [Cucumber] testing framework.
+  >
+  > `rails`
+  >   Supports the [Ruby on Rails] web framework.
+  >
+  > `factory_girl`
+  >   Supports the [factory_girl] testing library.
+  >
+  > `parallel_tests`
+  >   Supports the [parallel_tests] testing library.
+
 ## SEE ALSO
 
-tork(1), tork-driver(1), tork-master(1), tork-herald(1)
+tork(1), tork-driver(1), tork-master(1)
+
+[factory_girl]: https://github.com/thoughtbot/factory_girl
+[memory_test_fix]: https://github.com/stepahn/memory_test_fix
+[parallel_tests]: https://github.com/grosser/parallel_tests
+[Ruby on Rails]: http://rubyonrails.org
+[Cucumber]: https://cukes.info
+[RSpec]: http://rspec.info
 
 =end =========================================================================
 
@@ -35,59 +123,8 @@ $0 = File.basename(__FILE__) # for easier identification in ps(1) output
 require 'binman'
 BinMan.help
 
-require 'json'
-ENV['TORK_CONFIGS'] = JSON.dump(ARGV)
-
-#-----------------------------------------------------------------------------
-# backend
-#-----------------------------------------------------------------------------
-
-require 'tork/client'
-
-warn "#{$0}: Absorbing test execution overhead..."
-@driver = Tork::Client::Transceiver.new('tork-driver') do |event, *details|
-  case event_sym = event.to_sym
-  when :load then warn "#{$0}: Overhead absorbed. Ready for testing!"
-  when :over then warn "#{$0}: Reabsorbing changed overhead files..."
-  else
-    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
-
-    puts message
-  end
-end
-
-#-----------------------------------------------------------------------------
-# frontend
-#-----------------------------------------------------------------------------
-
-COMMANDS = {
-  't' => :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,
-}
-
-while key = STDIN.gets
-  if command = COMMANDS[key.strip]
-    warn "#{$0}: Sending #{command.to_s.inspect} command..."
-    @driver.send [command]
-    break if command == :quit
-  else # invalid command
-    COMMANDS.each do |key, cmd|
-      warn "#{$0}: Type #{key} then ENTER to #{cmd.to_s.tr('_', ' ')}."
-    end
-  end
-end
-
-Process.waitall
+ENV['TORK_CONFIGS'] = [ENV['TORK_CONFIGS'], *ARGV].join(':') if ARGV.any?
+require 'tork/config'
+
+require 'tork/cliapp'
+Tork::CLIApp.new.loop

data/bin/tork-driver

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# TORK-DRIVER 1 2012-10-10 18.2.4
+# TORK-DRIVER 1 2012-10-17 19.0.0
 
 ## NAME
 
@@ -13,31 +13,32 @@ tork-driver - drives tork-engine(1) when files change
 
 ## DESCRIPTION
 
-This program drives tork-engine(1) according to tork-herald(1)'s observations.
-It 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 tork-engine(1) into its own.
+This program drives tork-engine(1) when tork-herald(1) reports files changes.
+
+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.
 
 `["run_all_test_files"]`
   Runs all test files found within and beneath the current working directory.
 
-`["reabsorb_overhead_files"]`
-  Stops any test files that are currently running, reabsorbs the test
-  execution overhead, and resumes running those interrupted test files.
-
 *...*
-  This program accepts tork-engine(1) commands and delegates them accordingly.
+  Commands for tork-engine(1) are also accepted here.
+
+### Output
 
-When tork-herald(1) reports that a file belonging to the test execution
-overhead has been modified, this program replaces tork-master(1) with a new
-instance, which then absorbs the modified test execution overhead into itself.
+This program prints the following messages, which are single-line JSON arrays,
+to stdout.
 
-This program emits the following single-line status messages (JSON arrays) on
-its standard output stream to provide notifications about its activity:
+`["reabsorb",` *overhead_file*`]`
+  Test execution overhead is being reabsorbed because *overhead_file* has
+  changed.
 
-`["over",` *overhead_file*`]`
-  The test execution overhead is currently being reabsorbed, by replacing
-  tork-master(1) with a new instance, because *overhead_file* has changed.
+*...*
+  Messages from tork-engine(1) and tork-master(1) are also reproduced here.
 
 ## OPTIONS
 
@@ -46,19 +47,117 @@ its standard output stream to provide notifications about its activity:
 
 ## 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/driver.rb`
+  Optional Ruby script that is loaded inside the driver process on startup.
+  It can read and change the following variables.
+
+  > `Tork::Driver::REABSORB_FILE_GREPS`
+  >   Array of strings or regular expressions that match the paths of overhead
+  >   files.  If any of these equal or match the path of a changed file
+  >   reported by tork-herald(1), then the test execution overhead will be
+  >   reabsorbed in tork-master(1).
+  >
+  > `Tork::Driver::ALL_TEST_FILE_GLOBS`
+  >   Array of file globbing patterns that describe the set of all test files
+  >   in your Ruby application.
+  >
+  > `Tork::Driver::TEST_FILE_GLOBBERS`
+  >   Hash that maps (1) a regular expression describing a set of file paths
+  >   to (2) a lambda function that accepts a `MatchData` object containing
+  >   the results of the regular expression matching against the path of a
+  >   changed file, and yields one or more file globbing patterns (a single
+  >   string, or an array of strings) that describe a set of test files that
+  >   need to be run.
+  >
+  >   The results of these functions are recursively expanded (fed back into
+  >   them) to construct an entire dependency tree of test files that need to
+  >   be run.  For instance, if one function returns a glob that yields files
+  >   matched by another function, then that second function will be called to
+  >   glob more test files.  This process repeats until all dependent test
+  >   files have been accounted for.
+  >
+  > > ***Single glob expansion***
+  > >
+  > > 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:
+  > >
+  > >     Tork::Driver::TEST_FILE_GLOBBERS.update(
+  > >       %r{^(lib|app)/.*?([^/]+?)\.rb$} => lambda do |matches|
+  > >         name = matches[2]
+  > >         "{test,spec}/**/#{name}_#{name.reverse}.rb"
+  > >       end
+  > >     )
+  > >
+  > > ***Multi-glob expansion***
+  > >
+  > > For example, if test files could optionally have "test" or "spec"
+  > > prefixed or appended to their already peculiar names, like so:
+  > >
+  > >   * lib/hello.rb => test/hello\_olleh\_test.rb
+  > >   * lib/hello.rb => test/test\_hello\_olleh.rb
+  > >   * app/world.rb => spec/world\_ldrow\_spec.rb
+  > >   * app/world.rb => spec/spec\_world\_ldrow.rb
+  > >
+  > > Then you would add the following to your configuration file:
+  > >
+  > >     Tork::Driver::TEST_FILE_GLOBBERS.update(
+  > >       %r{^(lib|app)/.*?([^/]+?)\.rb$} => lambda do |matches|
+  > >         name = matches[2]
+  > >         ["{test,spec}/**/#{name}_#{name.reverse}.rb",
+  > >          "{test,spec}/**/#{name}_#{name.reverse}_{test,spec}.rb",
+  > >          "{test,spec}/**/{test,spec}_#{name}_#{name.reverse}.rb"]
+  > >       end
+  > >     )
+  > >
+  > > ***Recursive expansion***
+  > >
+  > > For example, if you wanted to run test files associated with
+  > > `lib/hello.rb` whenever the `app/world.rb` file changed, then you would
+  > > write:
+  > >
+  > >     Tork::Driver::TEST_FILE_GLOBBERS.update(
+  > >       %r{^app/world\.rb$} => lambda do |matches|
+  > >         'lib/hello.rb'
+  > >       end
+  > >     )
+  > >
+  > > This effectively aliases one file onto another, but not in both
+  > > directions.
+  > >
+  > > ***Suppressing expansion***
+  > >
+  > > 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:
+  > >
+  > >     Tork::Driver::TEST_FILE_GLOBBERS.update(
+  > >       %r{^(lib|app)(/.*?)([^/]+?)\.rb$} => lambda do |matches|
+  > >         if matches[2].include? '/models/'
+  > >           ["{test,spec}/**/#{matches[3]}_{test,spec}.rb",
+  > >            "{test,spec}/**/{test,spec}_#{matches[3]}.rb"]
+  > >         #else     # implied by the Ruby language
+  > >           #nil    # implied by the Ruby language
+  > >         end
+  > >       end
+  > >     )
 
 ## 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), tork-herald(1), tork-engine(1), tork-master(1)
 
 =end =========================================================================
 

data/bin/tork-engine

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 =begin =======================================================================
 
-# TORK-ENGINE 1 2012-10-10 18.2.4
+# TORK-ENGINE 1 2012-10-17 19.0.0
 
 ## NAME
 
@@ -13,24 +13,31 @@ tork-engine - wraps tork-master(1) with bookkeeping
 
 ## DESCRIPTION
 
-This program tells tork-master(1) to run your tests and keeps track of test
-results.  It 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 tork-master(1) into its own.
+This program uses tork-master(1) to run tests and keeps track of the results.
 
-`["reabsorb_overhead",` *paths*`,` *files*`]`
-  Stops any test files that are currently running, reabsorbs the given test
-  execution overhead, and resumes running those interrupted test files.  See
-  the "load" command in tork-master(1) for more information.
+This program can be controlled remotely by multiple tork-remote(1) instances.
 
-`["run_test_file"`, *test_file*`,` *line_numbers*`]`
-  Runs tests that correspond to the given *line_numbers* array in the given
-  *test_file*.  If *line_numbers* is `null`, then only those lines that have
-  changed since the last time the *test_file* was run will be substituted.  If
-  *line_numbers* is an empty array, then the entire *test_file* will be run.
+### Input
 
-`["stop_running_test_files"]`
-  Stops any test files that are currently running.
+This program reads the following commands, which are single-line JSON arrays,
+from stdin and performs the actions described respectively.
+
+`["reabsorb_overhead"]`
+  Stops any test files that are currently running, reabsorbs the test
+  execution overhead, and then re-runs those stopped test files.
+
+`["run_test_file"`, *test_file*`,` *line_numbers*...`]`
+  Runs tests that correspond to the given sequence of *line_numbers* in the
+  given *test_file*.  If no *line_numbers* are given, then only those lines
+  that have changed since the last run of *test_file* will be substituted.
+  If any *line_numbers* are zero, then the entire *test_file* will be run.
+
+`["run_test_files"`, *test_files_with_optional_line_numbers*`]`
+  Calls the `run_test_file` command once for each item in the given array.
+
+`["stop_running_test_files"`, *signal*`]`
+  Stops test files that are currently running by sending the given *signal*
+  (optional; defaults to "SIGTERM") to their respective worker processes.
 
 `["rerun_passed_test_files"]`
   Runs all test files that have passed during their most recent run.
@@ -41,6 +48,20 @@ It also funnels the standard output stream of tork-master(1) into its own.
 `["quit"]`
   Stops all tests that are currently running and exits.
 
+### Output
+
+This program prints the following messages, which are single-line JSON arrays,
+to stdout.
+
+`["pass_now_fail",` *test_file*`,` *message*`]`
+  A previously passing *test_file* has now failed.  See *message* for details.
+
+`["fail_now_pass",` *test_file*`,` *message*`]`
+  A previously failing *test_file* has now passed.  See *message* for details.
+
+*...*
+  Messages from tork-master(1) are also reproduced here.
+
 ## OPTIONS
 
 `-h`, `--help`
@@ -48,19 +69,20 @@ It also funnels the standard output stream of tork-master(1) into its own.
 
 ## 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/engine.rb*
+  Optional Ruby script that is loaded inside the master process on startup.
 
 ## 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), tork-master(1)
 
 =end =========================================================================