TEST_SHELL

HISTORY

@@ -1,11 +1,6 @@
 HISTORY
 -------
 
-Version 0.0.5
----------------------
-* urchin now unsets `CDPATH`.
-* The documentation for `urchin -x` was removed because it was confusing.
-
 Version 0.0.4
 ---------------------
 * Switch urchin -x to urchin -sh and fix some problems with it

alternatives

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

package.json

@@ -1,6 +1,6 @@
 {
   "name": "urchin",
-  "version": "0.0.5",
+  "version": "0.0.4",
   "description": "Test framework for shell",
   "main": "urchin",
   "directories": {
@@ -24,9 +24,10 @@
     {"name": "Thomas Levine", "email": "_@thomaslevine.com"},
     {"name": "David Jones", "email": "drj@pobox.com"},
     {"name": "Francis Irving", "email": "francis@flourish.org"},
-    {"name": "Zarino Zappia", "email": "mail@zarino.co.uk"},
-    {"name": "Tom Mortimer-Jones", "email": "tom@morty.co.uk"},
+    {"name": "Zarino Zappia", "email": "mail@zarino.co.uk"}
+    {"name": "Tom Mortimer-Jones", "email": "tom@morty.co.uk"}
     {"name": "Michael Klement", "email": "mklement0@gmail.com"}
   ],
-  "license": "BSD"
+  "license": "BSD",
+  "readmeFilename": "readme.md"
 }

readme.md

@@ -4,22 +4,22 @@
     / /_/ / /  / /__/ / / / / / / /
     \__,_/_/   \___/_/ /_/_/_/ /_/ 
 
-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
 is like. Clone the repository
 
-    git clone git://github.com/tlevine/urchin.git
+    git clone git://github.com/scraperwiki/urchin.git
 
 Run the tests
 
     cd urchin
     ./urchin tests
 
-The above command will run the tests in your system's default
+The above command will run the tests in your systems default
 shell, /bin/sh (on recent Ubuntu this is dash, but it could be
 ksh or bash on other systems); to test urchin's cross-shell compatibility,
 run this:
@@ -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
+    wget https://raw.github.com/scraperwiki/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,6 @@ 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,
-urchin looks for files within a directory in the following manner.
-
-    for file in *; do
-      do_something_with_test_file $file
-    done
-
 ### Writing cross-shell compatibility tests for testing shell code
 
 While you could write your test scripts to explicitly invoke the functionality
@@ -106,20 +97,17 @@ 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.
 
 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 +115,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 +138,20 @@ 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).

tests/A nonempty CDPATH should not break urchin.

@@ -1,6 +0,0 @@
-#!/bin/sh
-
-cd ..
-export CDPATH=$PWD
-./urchin -f 'tests/urchin exit code' >/dev/null
-

tests/Cross-shell test support/.test-urchin-x/This should run as $TEST_SHELL

@@ -0,0 +1,4 @@
+#! ../../../urchin -x
+running=$(ps -o comm= -p $$ && :)
+echo "Running shell: $running"
+[ "$running" = bash ]

tests/Cross-shell test support/urchin -x should pass the $TEST_SHELL

@@ -0,0 +1,3 @@
+#!/bin/sh
+export TEST_SHELL=/bin/zsh
+echo '[ "$TEST_SHELL" = /bin/zsh ] ; exit $?' | ../../urchin -x

tests/Cross-shell test support/urchin -x should start a shell.

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+test c = $(../../urchin -x .print-arg-3 a 'b b b b' c d e)

tests/Cross-shell test support/urchin -x should start the $TEST_SHELL

@@ -0,0 +1,3 @@
+#!/bin/sh
+export TEST_SHELL=/bin/zsh
+echo 'test -n "$ZSH_VERSION"; exit $?' | ../../urchin -x

tests/Cross-shell test support/urchin should pass the $TEST_SHELL variable to urchin -x

@@ -0,0 +1,3 @@
+#!/bin/sh
+export TEST_SHELL=/bin/bash
+../../urchin .test-urchin-x

tests/urchin -x should start the $TEST_SHELL.

@@ -1,3 +0,0 @@
-#!/bin/sh
-
-test c = $(../urchin -x .print-arg-3 a 'b b b b' c d e)

urchin

@@ -1,9 +1,5 @@
 #!/bin/sh
 
-# Make sure that CDPATH isn't set, as it causes `cd` to behave unpredictably - notably, it can produce output,
-# which breaks fullpath().
-unset CDPATH
-
 fullpath() {
   (
     cd -- "$1"
@@ -99,23 +95,19 @@ has_sh_or_no_shebang_line() {
 USAGE="usage: $0 [<options>] <test directory>"
 
 urchin_help() {
-  cat <<EOF
-
-$USAGE
-
--s <shell>  Invoke test scripts that either have no shebang line at all or
-            have shebang line "#!/bin/sh" with the specified shell.
--f          Force running even if the test directory's name does not
-            contain the word "test".
--h          This help.
-
-Go to https://github.com/tlevine/urchin for documentation on writing tests.
-
-EOF
-  # [Experimental -x option left undocumented for now.]
-  # -x          [Experimental; not meant for direct invocation, but for use in
-  #             the shebang line of test scripts]
-  #             Run with "\$TEST_SHELL", falling back on /bin/sh.
+  echo
+  echo "$USAGE"
+  echo
+  echo '-s <shell>  Invoke test scripts that either have no shebang line or'
+  echo '            shebang line "#!/bin/sh" with the specified shell.'
+  echo '-f          Force running even if the test directory'\''s name does not'
+  echo '            contain the word "test".'
+  echo '-x          Run "$TEST_SHELL", falling back on /bin/sh. This might be'
+  echo '            useful in the shebang line (experimental).'
+  echo '-h          This help.'
+  echo
+  echo 'Go to https://github.com/tlevine/urchin for documentation on writing tests.'
+  echo
 }
 
 plural () {
@@ -183,10 +175,12 @@ do
           shell_for_sh_tests=$1
           which "$shell_for_sh_tests" >/dev/null || { echo "Cannot find specified shell: '$shell_for_sh_tests'" >&2; urchin_help >&2; exit 2; }
           ;;
-        -x) # [EXPERIMENTAL; UNDOCUMENTED FOR NOW] `urchin -x <test-script>` in a test script's shebang line is equivalent to invoking that script with `"$TEST_SHELL" <test-script>`
+        -x) # `urchin -sh` is equivalent to "$TEST_SHELL"
           shift
-          urchinsh=${TEST_SHELL:-/bin/sh}
-          "$urchinsh" "$@"
+         #current_shell=$(ps -o comm= -p $$ && :)
+         #urchinsh=${TEST_SHELL:-$current_shell}
+          export TEST_SHELL=${TEST_SHELL:-/bin/sh}
+          "$TEST_SHELL" "$@"
           exit $?;;
         -h|--help) urchin_help
           exit 0;;