tork 17.1.0 → 18.0.0

data/LICENSE

@@ -12,6 +12,7 @@ Thanks to 2012 Jesse Cooke <jesse@jc00ke.com>
 Thanks to 2012 Benjamin Quorning <benjamin@quorning.net>
 Thanks to 2012 Nicolas Fouché <nicolas.fouche@gmail.com>
 Thanks to 2012 Mark Hayes <mark@deployfx.com>
+Thanks to 2012 Gumaro Melendez <cloudernew@gmail.com>
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

data/README.markdown

@@ -5,21 +5,17 @@
       \__/\____/_/ /_/|_\
                  >>>------>
 
-_Test with fork_
-==============================================================================
+# _Test with fork_
 
-Tork is a continuous testing tool for Ruby that automatically detects and
-tests changes in your Ruby application or test suite in an efficient manner:
+Tork runs your tests as they change, in parallel:
 
-  1. Absorbs your test execution overhead into a master process.
+  1. Absorbs test execution overhead into a master process.
 
-  2. Forks to run your test files in parallel; overhead inherited.
+  2. Forks to inherit overhead and run test files in parallel.
 
   3. Avoids running unchanged tests inside changed test files.
 
-------------------------------------------------------------------------------
-Features
-------------------------------------------------------------------------------
+## Features
 
   * No configuration needed: run `tork` for Ruby, `tork rails` for Rails.
 
@@ -39,16 +35,18 @@ Features
 
   * You can override the modular `tork*` programs with your own in $PATH.
 
-  * Its core is written in about 370 lines (SLOC) of pure Ruby code! :-)
+  * Its core is written in about 410 lines (SLOC) of pure Ruby code! :-)
 
 ### Architecture
 
-Following UNIX philosophy, Tork is composed of simple text-based programs: so
-you can build your own custom Tork user interface by wrapping `tork-driver`!
+Following UNIX philosophy, Tork is composed of simple text-based programs that
+*do one thing well*.  As a result, you could even create your own Tork user
+interface by wrapping `tork-driver` appropriately!
 
-  * `tork` is an interactive command-line user interface (CLI) for driver
+  * `tork` is an interactive command-line user interface for `tork-driver`
   * `tork-herald` monitors current directory tree and reports changed files
-  * `tork-driver` tells master to run tests and keeps track of test results
+  * `tork-driver` drives the engine according to the herald's observations
+  * `tork-engine` tells master to run tests and keeps track of test results
   * `tork-master` absorbs test execution overhead and forks to run your tests
 
 When the herald observes that files in or beneath the current directory have
@@ -61,9 +59,7 @@ figure out which tests inside your newly saved test file have changed (using
 diff and regexps) and then attempts to run just those.  To make it run *all*
 tests in your saved file, simply save the file *again* without changing it.
 
-------------------------------------------------------------------------------
-Installation
-------------------------------------------------------------------------------
+## Installation
 
     gem install tork
 
@@ -91,9 +87,7 @@ Installation
     bundle_bin/tork --help  # run it directly
     bundle exec rake -T     # packaging tasks
 
-------------------------------------------------------------------------------
-Usage
-------------------------------------------------------------------------------
+## Usage
 
 ### At the command line
 
@@ -103,6 +97,14 @@ You can monitor your test processes from another terminal:
 
     watch 'ps xuw | sed -n "1p; /tor[k]/p" | fgrep -v sed'
 
+### With RSpec
+
+RSpec 2.8.0 and older contain [a bug](
+https://github.com/sunaku/tork/issues/31 ) where a nonzero exit status (caused
+by an uncaught exception) is overridden by RSpec's `Kernel#at_exit` handler to
+be zero, thereby falsely indicating that a spec had passed.  [This patch](
+https://github.com/rspec/rspec-core/pull/569/files ) fixes the problem.
+
 ### With [Ruby on Rails]
 
 For Rails 3 or newer, use the `tork/config/rails` configuration helper.
@@ -117,17 +119,16 @@ adapter][memory_test_fix].  Otherwise, you *might* face these errors:
 
 > cannot start a transaction within a transaction
 
-------------------------------------------------------------------------------
-Configuration
-------------------------------------------------------------------------------
+## Configuration
 
 Tork looks for a configuration file named `.tork.rb` in its current working
 directory.  The configuration file is a normal Ruby script, inside which you
-can query and modify the `Tork::Config` object: an instance of OpenStruct.
+can query and modify the `Tork::Config` object, which is a kind of `Struct`.
+
+Note that Tork *does not* automatically reload changes in your configuration
+file.  So you must restart Tork accordingly if your configuration changes.
 
-------------------------------------------------------------------------------
-Configuration helpers
-------------------------------------------------------------------------------
+## Configuration helpers
 
 In case you did not read the `tork --help` manual page, please note that you
 can pass *multiple* configuration helpers to tork(1) at the command line!
@@ -192,7 +193,7 @@ Or in your configuration file:
 
     require 'tork/config/logdir'
 
-### Receive notifications via libnotify, growl, or xmessage(1)
+### Receive notifications via libnotify, growl, or xmessage
 
 At the command line:
 
@@ -202,9 +203,17 @@ Or in your configuration file:
 
     require 'tork/config/notify'
 
-------------------------------------------------------------------------------
-Configuration options
------------------------------------------------------------------------------
+## Configuration options
+
+This table shows which configuration options affect which Tork components:
+
+| Affects `tork-driver` | Affects `tork-engine` | Affects `tork-master` |
+| --------------------- | --------------------- | --------------------- |
+| overhead_load_paths   | test_event_hooks      | max_forked_workers    |
+| overhead_file_globs   |                       | before_fork_hooks     |
+| reabsorb_file_greps   |                       | after_fork_hooks      |
+| all_test_file_globs   |                       |                       |
+| test_file_globbers    |                       |                       |
 
 ### Tork::Config.max_forked_workers
 
@@ -234,29 +243,36 @@ your Ruby application.
 ### Tork::Config.test_file_globbers
 
 Hash that maps (1) a regular expression describing a set of file paths to (2)
-a lambda function that accepts the path to a changed file and a `MatchData`
-object containing the results of the regular expression matching, and yields
+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.
 
-In other words, whenever the source files (the regular expression) change,
-their associated test files (result of calling the lambda function) are 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.
 
-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:
+#### 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::Config.test_file_globbers[%r<^(lib|app)/.+\.rb$>] = lambda do |path, matches|
-      name = File.basename(path, '.rb')
+    Tork::Config.test_file_globbers[%r<^(lib|app)/.*?([^/]+?)\.rb$>] = lambda do |matches|
+      name = matches[2]
       "{test,spec}/**/#{name}_#{name.reverse}.rb"
     end
 
-Going further, if you suppose that test files could optionally have "test" or
-"spec" prefixed or appended to their already peculiar names, like so:
+#### 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`
@@ -265,20 +281,34 @@ Going further, if you suppose that test files could optionally have "test" or
 
 Then you would add the following to your configuration file:
 
-    Tork::Config.test_file_globbers[%r<^(lib|app)/.+\.rb$>] = lambda do |path, matches|
-      name = File.basename(path, '.rb')
+    Tork::Config.test_file_globbers[%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
 
-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:
+#### Recursive expansion
 
-    Tork::Config.test_file_globbers[%r<^(lib|app)/.+\.rb$>] = lambda do |path, matches|
-      if path.include? '/models/'
-        "{test,spec}/**/#{File.basename(path)}"
+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::Config.test_file_globbers[%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::Config.test_file_globbers[%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
@@ -289,14 +319,14 @@ source files except those within a `models/` directory, you would write:
 Array of lambda functions that are invoked inside `tork-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.
+1. The path of the test file that will be run by the worker process.
 
-2. The path of the log file containing the live output of the worker process.
+2. An array of line numbers in the test file to run.  If this array is empty,
+   then the entire test file will be run.
 
-3. The path of the test file that will be run by the worker process.
+3. The path of the log file containing the live output of the worker process.
 
-4. An array of line numbers in the test file to run.  If this array is empty,
-   then the entire test file will be run.
+4. The sequence number of the worker process that will be forked shortly.
 
 For example, to see some real values:
 
@@ -316,14 +346,14 @@ For example, to see some real values:
 Array of lambda functions that are invoked inside a worker process forked
 by `tork-master`.  These functions are given:
 
-1. The sequence number of the worker process.
+1. The path of the test file that will be run by the worker process.
 
-2. The path of the log file containing the live output of the worker process.
+2. An array of line numbers in the test file to run.  If this array is empty,
+   then the entire test file will be run.
 
-3. The path of the test file that will be run by the worker process.
+3. The path of the log file containing the live output of the worker process.
 
-4. An array of line numbers in the test file to run.  If this array is empty,
-   then the entire test file will be run.
+4. The sequence number of the worker process.
 
 For example, to see some real values, including the worker process' PID:
 
@@ -345,7 +375,7 @@ test-driven development cycle by only running tests you are currently editing.
 
 ### Tork::Config.test_event_hooks
 
-Array of lambda functions that are invoked inside `tork-driver` whenever it
+Array of lambda functions that are invoked inside `tork-engine` whenever it
 receives a status message (passed into those functions) from `tork-master`.
 Run `tork-master --help` for more information about these status messages.
 
@@ -355,9 +385,7 @@ For example, to see some real values:
       p :test_event_hooks => message_from_tork_master
     }
 
-------------------------------------------------------------------------------
-License
-------------------------------------------------------------------------------
+## License
 
 Released under the ISC license.  See the LICENSE file for details.
 

data/bin/tork

@@ -1,21 +1,17 @@
 #!/usr/bin/env ruby
-=begin
+=begin =======================================================================
 
-TORK 1 2012-01-30 17.1.0
-==============================================================================
+# TORK 1 2012-02-06 18.0.0
 
-NAME
-------------------------------------------------------------------------------
+## NAME
 
 tork - Continuous testing tool for Ruby
 
-SYNOPSIS
-------------------------------------------------------------------------------
+## SYNOPSIS
 
 `tork` [*OPTION*]... [*CONFIG*]...
 
-DESCRIPTION
-------------------------------------------------------------------------------
+## 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
@@ -23,14 +19,12 @@ 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
 press the ENTER key (supplying no command) to see a menu of accepted commands.
 
-OPTIONS
-------------------------------------------------------------------------------
+## OPTIONS
 
 `-h`, `--help`
-  Display this help manual using man(1).
+  Show this help manual.
 
-SEE ALSO
-------------------------------------------------------------------------------
+## SEE ALSO
 
 tork(1), tork-driver(1), tork-master(1), tork-herald(1)
 

data/bin/tork-driver

@@ -1,41 +1,32 @@
 #!/usr/bin/env ruby
-=begin
+=begin =======================================================================
 
-TORK-DRIVER 1 2012-01-30 17.1.0
-==============================================================================
+# TORK-DRIVER 1 2012-02-06 18.0.0
 
-NAME
-------------------------------------------------------------------------------
+## NAME
 
-tork-driver - drives tork-master(1) and does bookkeeping
+tork-driver - drives tork-engine(1) when files change
 
-SYNOPSIS
-------------------------------------------------------------------------------
+## SYNOPSIS
 
 `tork-driver` [*OPTION*]...
 
-DESCRIPTION
-------------------------------------------------------------------------------
+## 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 tork-master(1) into its own.
+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.
 
 `["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.
+*...*
+  This program accepts tork-engine(1) commands and delegates them accordingly.
 
 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
@@ -48,30 +39,26 @@ its standard output stream to provide notifications about its activity:
   The test execution overhead is currently being reabsorbed, by replacing
   tork-master(1) with a new instance, because *overhead_file* has changed.
 
-OPTIONS
-------------------------------------------------------------------------------
+## OPTIONS
 
 `-h`, `--help`
-  Display this help manual using man(1).
+  Show this help manual.
 
-FILES
-------------------------------------------------------------------------------
+## FILES
 
 *.tork.rb*
   Optional Ruby script for configuring tork(1).
 
-ENVIRONMENT
-------------------------------------------------------------------------------
+## 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 ALSO
-------------------------------------------------------------------------------
+## SEE ALSO
 
-tork(1), tork-driver(1), tork-master(1), tork-herald(1)
+tork(1), tork-herald(1), tork-driver(1), tork-engine(1), tork-master(1)
 
 =end =========================================================================
 
@@ -81,6 +68,4 @@ require 'binman'
 BinMan.help
 
 require 'tork/driver'
-Tork::Driver.loop
-
-Process.waitall
+Tork::Driver.new.loop

data/bin/tork-engine

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+=begin =======================================================================
+
+# TORK-ENGINE 1 2012-02-06 18.0.0
+
+## NAME
+
+tork-engine - wraps tork-master(1) with bookkeeping
+
+## SYNOPSIS
+
+`tork-engine` [*OPTION*]...
+
+## 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.
+
+`["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.
+
+`["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.
+
+`["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.
+
+`["rerun_failed_test_files"]`
+  Runs all test files that have failed during their most recent run.
+
+`["quit"]`
+  Stops all tests that are currently running and exits.
+
+## OPTIONS
+
+`-h`, `--help`
+  Show this help manual.
+
+## FILES
+
+*.tork.rb*
+  Optional Ruby script for configuring tork(1).
+
+## 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 ALSO
+
+tork(1), tork-herald(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 'tork/engine'
+Tork::Engine.new.loop