test stubs

alternatives

@@ -1,2 +0,0 @@
-Totally different syntax and similar features, plus TAP output
-https://github.com/sstephenson/bats

readme.md

@@ -4,9 +4,9 @@
     / /_/ / /  / /__/ / / / / / / /
     \__,_/_/   \___/_/ /_/_/_/ /_/ 
 
-Urchin is a file-based test harness, normally used for testing shell programs.
-It is written in portable shell and should thus work on GNU/Linux, BSD
-(including Mac OS X), and other Unix-like platforms.
+Urchin is a test framework for shell. It is implemented in
+portable /bin/sh and should work on GNU/Linux, Mac OS X, and
+other Unix platforms.
 
 ## Try it out
 Urchin's tests are written in Urchin, so you can run them to see what Urchin
@@ -27,15 +27,14 @@ run this:
     cd urchin
     ./cross-shell-tests
 
-## Install
-Urchin is contained in a single file, so you can install it by copying it to a
-directory in your `PATH`. For example, you can run the following as root.
+## Globally
+Download Urchin like so (as root) (or use npm, below):
 
     cd /usr/local/bin
     wget https://raw.github.com/tlevine/urchin/master/urchin
     chmod +x urchin
 
-Urchin can be installed with npm too.
+Can be installed with npm too:
 
     npm install -g urchin
 
@@ -87,14 +86,15 @@ Files are only run if they are executable, and files beginning with `.` are
 ignored. Thus, fixtures and libraries can be included sloppily within the test
 directory tree. The test passes if the file exits 0; otherwise, it fails.
 
-Tests files and subdirectories are run in ASCIIbetical order within each
-directory; that is,
+In case you care about the order in which your tests execute, consider that
 urchin looks for files within a directory in the following manner.
 
     for file in *; do
       do_something_with_test_file $file
     done
 
+Tests within a directory are executed in whatever order `*` returns.
+
 ### Writing cross-shell compatibility tests for testing shell code
 
 While you could write your test scripts to explicitly invoke the functionality
@@ -106,20 +106,24 @@ The specific approach depends on your test scenario:
 * (b) Your scripts _source_ scripts containing portable shell code.
 
 #### (a) Cross-shell tests with test scripts that _invoke_ shell scripts
-Urchin sets the `TEST_SHELL` environment variable so that you may change the
-shell with which your tests call other shell programs. To run your test
-scripts in multiple shells you must call `$TEST_SHELL` in your tests and then
-run urchin with the appropriate option.
 
+First, consider using [shall](https://github.com/mklement0/shall).
+
+    #!/usr/bin/env shall
+    echo This is a test file.
+
+Alternatively, you can use urchin's built-in recognition of the
+`TEST_SHELL` environment variable.
 In your test scripts, invoke the shell scripts to test via the shell
 specified in environment variable `TEST_SHELL` rather than directly;
 e.g.: `$TEST_SHELL ../foo bar` (rather than just `../foo bar`).  
+Note that if you alsow want your test scripts to work when run directly,
+outside of Urchin, be sure to target scripts that happen to be in the 
+current directory with prefix `./`; e.g., `$TEST_SHELL ./baz`
+(rather than `$TEST_SHELL baz`).
 
-On invocation of Urchin, prepend a definition of environment variable
-`TEST_SHELL` specifying the shell to test with, e.g.,
-
-    TEST_SHELL=zsh urchin ./tests
-
+Then, on invocation of Urchin, prepend a definition of environment variable
+`TEST_SHELL` specifying the shell to test with, e.g.: `TEST_SHELL=zsh urchin ./tests`.  
 To test with multiple shells in sequence, use something like:
 
     for shell in sh bash ksh zsh; do
@@ -127,20 +131,14 @@ To test with multiple shells in sequence, use something like:
     done
 
 If `TEST_SHELL` has no value, Urchin defines it as `/bin/sh`, so the test
-scripts can rely on `$TEST_SHELL` always containing a value when Urchin runs
-them.
-
-That said, we still recommand that you account for the possibility that
-`$TEST_SHELL` does not contain a value so that you may run your test scripts
-without Urchin. Supporting this case is very simple; when you invoke scripts
-that happen to be in the current directory, be sure to use the prefix `./`,
-e.g., `$TEST_SHELL ./baz` rather than `$TEST_SHELL baz`.
+scripts can rely on `$TEST_SHELL` always containing a value.
 
 #### (b) Cross-shell tests with test scripts that _source_ shell scripts
+
 If you _source_ shell code in your test scripts, it is the test scripts
 themselves that must be run with the shell specified.
 
-Urchin supports the `-s <shell>` option, which instructs
+To that end, Urchin supports the `-s <shell>` option, which instructs
 Urchin to invoke the test scripts with the specified shell; e.g., `-s bash`.  
 (In addition, Urchin sets environment variable `TEST_SHELL` to the specified
 shell.)
@@ -156,18 +154,21 @@ To test with multiple shells in sequence, use something like:
       urchin -s $shell ./tests
     done
 
-Also consider using [shall](https://github.com/mklement0/shall).
-It does something similar, but the interface may be more intuitive.
+<!--
+#### (c) Cross shell tests with `urchin -x` (experimental)
+If you run urchin with the `-x` flag, it will be as if you ran
+`$TEST_SHELL`. Unless `$TEST_SHELL` isn't set, in which case it'll
+be as if you ran `/bin/sh`. Putting this in she shebang line might
+eventually work out to be a cleaner way of doing cross-shell testing.
 
-    #!/usr/bin/env shall
-    echo This is a test file.
+    #!/usr/bin/env urchin -x
+    test a = a
 
+It might make sense if you do this.
+
+    export TEST_SHELL=zsh && urchin -x
+    export TEST_SHELL=bash && urchin -x
+-->
 ## Alternatives to Urchin
 Alternatives to Urchin are discussed in
 [this blog post](https://blog.scraperwiki.com/2012/12/how-to-test-shell-scripts/).
-
-## Ideas for new features
-
-* Support [Nagios plugins](https://nagios-plugins.org/doc/guidelines.html)
-* Stop running if a test fails so one can use Urchin as a
-    [setup framework](https://github.com/tlevine/urchin/issues/16).