tork 18.2.4 → 19.0.0

data/man/man1/tork-engine.1

@@ -1,4 +1,4 @@
-.TH TORK\-ENGINE 1 2012\-10\-10 18.2.4
+.TH TORK\-ENGINE 1 2012\-10\-17 19.0.0
 .SH NAME
 .PP
 tork\-engine \- wraps 
@@ -9,30 +9,34 @@ with bookkeeping
 \fB\fCtork-engine\fR [\fIOPTION\fP]...
 .SH DESCRIPTION
 .PP
-This program tells 
+This program uses 
 .BR 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 
-.BR tork-master (1) 
-into its own.
+to run tests and keeps track of the results.
+.PP
+This program can be controlled remotely by multiple 
+.BR tork-remote (1) 
+instances.
+.SS Input
+.PP
+This program reads the following commands, which are single\-line JSON arrays,
+from stdin and performs the actions described respectively.
 .TP
-\fB\fC["reabsorb_overhead",\fR \fIpaths\fP\fB\fC,\fR \fIfiles\fP\fB\fC]\fR
-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 
-.BR tork-master (1) 
-for more information.
+\fB\fC["reabsorb_overhead"]\fR
+Stops any test files that are currently running, reabsorbs the test
+execution overhead, and then re\-runs those stopped test files.
 .TP
-\fB\fC["run_test_file"\fR, \fItest_file\fP\fB\fC,\fR \fIline_numbers\fP\fB\fC]\fR
-Runs tests that correspond to the given \fIline_numbers\fP array in the given
-\fItest_file\fP.  If \fIline_numbers\fP is \fB\fCnull\fR, then only those lines that have
-changed since the last time the \fItest_file\fP was run will be substituted.  If
-\fIline_numbers\fP is an empty array, then the entire \fItest_file\fP will be run.
+\fB\fC["run_test_file"\fR, \fItest_file\fP\fB\fC,\fR \fIline_numbers\fP...\fB\fC]\fR
+Runs tests that correspond to the given sequence of \fIline_numbers\fP in the
+given \fItest_file\fP.  If no \fIline_numbers\fP are given, then only those lines
+that have changed since the last run of \fItest_file\fP will be substituted.
+If any \fIline_numbers\fP are zero, then the entire \fItest_file\fP will be run.
 .TP
-\fB\fC["stop_running_test_files"]\fR
-Stops any test files that are currently running.
+\fB\fC["run_test_files"\fR, \fItest\fIfiles\fPwith\fIoptional\fPline_numbers\fP\fB\fC]\fR
+Calls the \fB\fCrun_test_file\fR command once for each item in the given array.
+.TP
+\fB\fC["stop_running_test_files"\fR, \fIsignal\fP\fB\fC]\fR
+Stops test files that are currently running by sending the given \fIsignal\fP
+(optional; defaults to "SIGTERM") to their respective worker processes.
 .TP
 \fB\fC["rerun_passed_test_files"]\fR
 Runs all test files that have passed during their most recent run.
@@ -42,25 +46,39 @@ Runs all test files that have failed during their most recent run.
 .TP
 \fB\fC["quit"]\fR
 Stops all tests that are currently running and exits.
+.SS Output
+.PP
+This program prints the following messages, which are single\-line JSON arrays,
+to stdout.
+.TP
+\fB\fC["pass_now_fail",\fR \fItest_file\fP\fB\fC,\fR \fImessage\fP\fB\fC]\fR
+A previously passing \fItest_file\fP has now failed.  See \fImessage\fP for details.
+.TP
+\fB\fC["fail_now_pass",\fR \fItest_file\fP\fB\fC,\fR \fImessage\fP\fB\fC]\fR
+A previously failing \fItest_file\fP has now passed.  See \fImessage\fP for details.
+.TP
+\fI...\fP
+Messages from 
+.BR tork-master (1) 
+are also reproduced here.
 .SH OPTIONS
 .TP
 \fB\fC-h\fR, \fB\fC--help\fR
 Show this help manual.
 .SH FILES
 .TP
-\fI.tork.rb\fP
-Optional Ruby script for configuring 
-.BR tork (1).
-.SH ENVIRONMENT
+\fI.tork/config.rb\fP
+Optional Ruby script that is loaded inside the driver process on startup.
+It can read and change the \fB\fCENV['TORK_CONFIGS']\fR environment variable.
 .TP
-\fB\fCTORK_CONFIGS\fR
-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 \fI.tork.rb\fP is loaded.
+\fI.tork/engine.rb\fP
+Optional Ruby script that is loaded inside the master process on startup.
+.SH ENVIRONMENT
+.PP
+See 
+.BR tork (1).
 .SH SEE ALSO
 .PP
 .BR tork (1), 
-.BR tork-herald (1), 
-.BR tork-driver (1), 
-.BR tork-engine (1), 
+.BR tork-remote (1), 
 .BR tork-master (1)

data/man/man1/tork-herald.1

@@ -1,4 +1,4 @@
-.TH TORK\-HERALD 1 2012\-10\-10 18.2.4
+.TH TORK\-HERALD 1 2012\-10\-17 19.0.0
 .SH NAME
 .PP
 tork\-herald \- reports modified files
@@ -7,9 +7,9 @@ tork\-herald \- reports modified files
 \fB\fCtork-herald\fR [\fIOPTION\fP]...
 .SH DESCRIPTION
 .PP
-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.
 .SH OPTIONS
 .TP
 \fB\fC-h\fR, \fB\fC--help\fR
@@ -17,7 +17,4 @@ Show this help manual.
 .SH SEE ALSO
 .PP
 .BR tork (1), 
-.BR tork-herald (1), 
-.BR tork-driver (1), 
-.BR tork-engine (1), 
-.BR tork-master (1)
+.BR tork-driver (1)

data/man/man1/tork-master.1

@@ -1,4 +1,4 @@
-.TH TORK\-MASTER 1 2012\-10\-10 18.2.4
+.TH TORK\-MASTER 1 2012\-10\-17 19.0.0
 .SH NAME
 .PP
 tork\-master \- absorbs overhead and runs tests
@@ -7,60 +7,113 @@ tork\-master \- absorbs overhead and runs tests
 \fB\fCtork-master\fR [\fIOPTION\fP]...
 .SH DESCRIPTION
 .PP
-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.
-.TP
-\fB\fC["load",\fR \fIpaths\fP\fB\fC,\fR \fIfiles\fP\fB\fC]\fR
-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.
+This program absorbs your Ruby application's test execution overhead once and
+simply 
+.BR 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.
+.PP
+This program can be controlled remotely by multiple 
+.BR tork-remote (1) 
+instances.
+.SS Input
+.PP
+This program reads the following commands, which are single\-line JSON arrays,
+from stdin and performs the actions described respectively.
 .TP
 \fB\fC["test",\fR \fItest_file\fP\fB\fC,\fR \fIline_numbers\fP\fB\fC]\fR
-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 defined on the given array of \fIline_numbers\fP.
-.IP
-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 \fIlog_file\fP specified in these status messages.
-.RS
-.IP \(bu 2
-Test is running:
-\fB\fC["test",\fR \fItest_file\fP\fB\fC,\fR \fIline_numbers\fP\fB\fC,\fR \fIlog_file\fP\fB\fC,\fR \fIworker_number\fP\fB\fC]\fR
-.IP \(bu 2
-Test has passed:
-\fB\fC["pass",\fR \fItest_file\fP\fB\fC,\fR \fIline_numbers\fP\fB\fC,\fR \fIlog_file\fP\fB\fC,\fR \fIworker_number\fP\fB\fC,\fR \fIexit_code\fP\fB\fC,\fR \fIexit_info\fP\fB\fC]\fR
-.IP \(bu 2
-Test has failed:
-\fB\fC["fail",\fR \fItest_file\fP\fB\fC,\fR \fIline_numbers\fP\fB\fC,\fR \fIlog_file\fP\fB\fC,\fR \fIworker_number\fP\fB\fC,\fR \fIexit_code\fP\fB\fC,\fR \fIexit_info\fP\fB\fC]\fR
-.RE
+Forks a worker process to run tests that correspond to the given
+\fIline_numbers\fP in the given \fItest_file\fP.  If \fIline_numbers\fP is empty, then
+the entire \fItest_file\fP will be run.
 .TP
-\fB\fC["stop"]\fR
-Stops all tests that are currently running and prints the given command line
-to the standard output stream.
+\fB\fC["stop",\fR \fIsignal\fP\fB\fC]\fR
+Stops all tests that are currently running by sending the given \fIsignal\fP
+(optional; defaults to "SIGTERM") to their respective worker processes.
 .TP
 \fB\fC["quit"]\fR
 Stops all tests that are currently running and exits.
+.SS Output
+.PP
+This program prints the following messages, which are single\-line JSON arrays,
+to stdout.
+.TP
+\fB\fC["absorb"]\fR
+Test execution overhead has been absorbed.  We are ready for testing!
+.TP
+\fB\fC["test",\fR \fItest_file\fP\fB\fC,\fR \fIline_numbers\fP\fB\fC,\fR \fIlog_file\fP\fB\fC,\fR \fIworker_number\fP\fB\fC]\fR
+Test has begun running.  Its output (both stdout and stderr) is being
+captured into \fIlog_file\fP in real time, so you can watch it with \fB\fCtail -f\fR.
+.TP
+\fB\fC["pass",\fR \fItest_file\fP\fB\fC,\fR \fIline_numbers\fP\fB\fC,\fR \fIlog_file\fP\fB\fC,\fR \fIworker_number\fP\fB\fC,\fR \fIexit_code\fP\fB\fC,\fR \fIexit_info\fP\fB\fC]\fR
+Test has passed.
+.TP
+\fB\fC["fail",\fR \fItest_file\fP\fB\fC,\fR \fIline_numbers\fP\fB\fC,\fR \fIlog_file\fP\fB\fC,\fR \fIworker_number\fP\fB\fC,\fR \fIexit_code\fP\fB\fC,\fR \fIexit_info\fP\fB\fC]\fR
+Test has failed.
 .SH OPTIONS
 .TP
 \fB\fC-h\fR, \fB\fC--help\fR
 Show this help manual.
 .SH FILES
 .TP
-\fI.tork.rb\fP
-Optional Ruby script for configuring 
-.BR tork (1).
-.SH ENVIRONMENT
+\fI.tork/config.rb\fP
+Optional Ruby script that is loaded inside the driver process on startup.
+It can read and change the \fB\fCENV['TORK_CONFIGS']\fR environment variable.
+.TP
+\fI.tork/master.rb\fP
+Optional Ruby script that is loaded inside the master process on startup.
+It can read and change the following variables.
+.PP
+.RS
 .TP
-\fB\fCTORK_CONFIGS\fR
-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 \fI.tork.rb\fP is loaded.
+\fB\fCTork::Master::MAX_CONCURRENT_WORKERS\fR
+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.
+.RE
+.TP
+\fI.tork/onfork.rb\fP
+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.
+.PP
+.RS
+.TP
+\fB\fC$tork_test_file\fR
+Path of the test file that will be run by the worker process.
+.TP
+\fB\fC$tork_line_numbers\fR
+Array of line numbers in the test file that were requested to be run.
+.TP
+\fB\fC$tork_log_file\fR
+Path of the log file that will hold the output of the worker process.
+.TP
+\fB\fC$tork_worker_number\fR
+Sequence number of the worker process that will be forked shortly.
+.RE
+.TP
+\fI.tork/worker.rb\fP
+Optional Ruby script that is loaded inside a worker process just after
+it is forked.  It can read and change the following variables.
+.PP
+.RS
+.TP
+\fB\fC$tork_test_file\fR
+Path of the test file that will be run by this worker process.
+.TP
+\fB\fC$tork_line_numbers\fR
+Array of line numbers in the test file that were requested to be run.
+.TP
+\fB\fC$tork_log_file\fR
+Path of the log file that will hold the output of this worker process.
+.TP
+\fB\fC$tork_worker_number\fR
+Sequence number of this worker process.
+.RE
+.SH ENVIRONMENT
+.PP
+See 
+.BR tork (1).
 .SH SEE ALSO
 .PP
 .BR tork (1), 
-.BR tork-herald (1), 
-.BR tork-driver (1), 
-.BR tork-engine (1), 
-.BR tork-master (1)
+.BR tork-remote (1)

data/man/man1/tork-notify.1

@@ -0,0 +1,27 @@
+.TH TORK\-NOTIFY 1 2012\-10\-17 19.0.0
+.SH NAME
+.PP
+tork\-notify \- notifies you of test status changes
+.SH SYNOPSIS
+.PP
+\fB\fCtork-notify\fR [\fIOPTION\fP]...
+.SH DESCRIPTION
+.PP
+This program serves as an example of how to receive and process messages sent
+by the various programs in the 
+.BR 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.
+.SH OPTIONS
+.TP
+\fB\fC-h\fR, \fB\fC--help\fR
+Show this help manual.
+.SH EXIT STATUS
+.PP
+See 
+.BR tork-remote (1).
+.SH SEE ALSO
+.PP
+.BR tork-remote (1), 
+.BR tork-engine (1)

data/man/man1/tork-remote.1

@@ -0,0 +1,38 @@
+.TH TORK\-REMOTE 1 2012\-09\-26 18.2.3
+.SH NAME
+.PP
+tork\-remote \- controls 
+.BR tork (1) 
+programs
+.SH SYNOPSIS
+.PP
+\fB\fCtork-remote\fR [\fIOPTION\fP]... \fIPROGRAM\fP
+.SH DESCRIPTION
+.PP
+This program sends single\-line JSON messages read from its stdin to the given
+\fIPROGRAM\fP which is already running in the same working directory as this one.
+.PP
+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
+.BR sh (1), 
+before being sent to the \fIPROGRAM\fP as a single\-line JSON message.
+.PP
+If the \fIPROGRAM\fP sends any messages in response, then they are printed to
+stdout if they are valid single\-line JSON messages or to stderr otherwise.
+.SH OPTIONS
+.TP
+\fB\fC-h\fR, \fB\fC--help\fR
+Show this help manual.
+.SH EXIT STATUS
+.TP
+1
+Could not connect to the \fIPROGRAM\fP.
+.TP
+2
+Lost connection to the \fIPROGRAM\fP.
+.SH SEE ALSO
+.PP
+.BR tork (1), 
+.BR tork-driver (1), 
+.BR tork-engine (1), 
+.BR tork-master (1)

data/man/man1/tork.1

@@ -1,4 +1,4 @@
-.TH TORK 1 2012\-10\-10 18.2.4
+.TH TORK 1 2012\-10\-17 19.0.0
 .SH NAME
 .PP
 tork \- Continuous testing tool for Ruby
@@ -8,19 +8,127 @@ tork \- Continuous testing tool for Ruby
 .SH DESCRIPTION
 .PP
 This program is a simple command\-line user interface for 
-.BR tork-driver (1).  
-It
-loads the given \fICONFIG\fP 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
+.BR tork-driver (1).
+.PP
+First, it applies the given \fICONFIG\fP values, which are either (1) paths to
+directories that contain configuration files or (2) names of configuration
+helpers listed in the description of the \fB\fCTORK_CONFIGS\fR environment variable.
+.PP
+Next, it waits for you to supply interactive commands either (1) directly on
+its stdin or (2) remotely through 
+.BR tork-remote (1).  
+From then onward, you may
 press the ENTER key (supplying no command) to see a menu of accepted commands.
+.PP
+Some interactive commands accept additional arguments, described as follows.
+.TP
+\fB\fCt\fR \fItest_file\fP [\fIline_number\fP]...
+Runs the given \fItest_file\fP while only running those tests that are defined
+on the given list of \fIline_number\fPs.  If no \fIline_number\fPs are given, then
+only those tests that have changed since the last run of the \fItest_file\fP
+will now be run.
+.TP
+\fB\fCs\fR [\fIsignal\fP]
+Stops test files that are currently running by sending the given \fIsignal\fP
+(optional; defaults to \fB\fCSIGTERM\fR) to their respective worker processes.
+.PP
+This program can be controlled remotely by multiple 
+.BR tork-remote (1) 
+instances.
 .SH OPTIONS
 .TP
 \fB\fC-h\fR, \fB\fC--help\fR
 Show this help manual.
+.SH FILES
+.TP
+\fI.tork/config.rb\fP
+Optional Ruby script that is loaded inside the driver process on startup.
+It can read and change the \fB\fCENV['TORK_CONFIGS']\fR environment variable.
+.SH ENVIRONMENT
+.TP
+\fB\fCTORK_CONFIGS\fR
+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".
+.PP
+.RS
+.TP
+\fB\fCdefault\fR
+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.
+.RS
+.IP \(bu 2
+rails
+.IP \(bu 2
+test
+.IP \(bu 2
+spec
+.IP \(bu 2
+cucumber
+.IP \(bu 2
+factory_girl
+.RE
+.TP
+\fB\fCdotlog\fR
+Hides log files by prefixing their names with a period (dot).
+.TP
+\fB\fClogdir\fR
+Keeps log files away from your tests, in the \fB\fClog/\fR directory.
+.TP
+\fB\fCcoverage\fR
+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):
+.PP
+.RS
+.TP
+\fB\fC:grade\fR
+Percentage of source lines that were C0 covered.
+.TP
+\fB\fC:nsloc\fR
+Total number of source lines of code in the file.
+.TP
+\fB\fC:holes\fR
+Line numbers of source lines that were not covered.
+.RE
+.TP
+\fB\fCtest\fR
+Supports the Test::Unit standard library.
+.PP
+\fB\fCspec\fR
+  Supports the RSpec
+.UR http://rspec.info
+.UE
+testing framework.
+.PP
+\fB\fCcucumber\fR
+  Supports the Cucumber
+.UR https://cukes.info
+.UE
+testing framework.
+.PP
+\fB\fCrails\fR
+  Supports the Ruby on Rails
+.UR http://rubyonrails.org
+.UE
+web framework.
+.PP
+\fB\fCfactory_girl\fR
+  Supports the factory_girl
+.UR https://github.com/thoughtbot/factory_girl
+.UE
+testing library.
+.PP
+\fB\fCparallel_tests\fR
+  Supports the parallel_tests
+.UR https://github.com/grosser/parallel_tests
+.UE
+testing library.
+.RE
 .SH SEE ALSO
 .PP
 .BR tork (1), 
 .BR tork-driver (1), 
-.BR tork-master (1), 
-.BR tork-herald (1)
+.BR tork-master (1)