Urchin  Urchin

                   __    _     
  __  ____________/ /_  (_)___ 
 / / / / ___/ ___/ __ \/ / __ \
/ /_/ / /  / /__/ / / / / / / /
\__,_/_/   \___/_/ /_/_/_/ /_/ 

Urchin is a portable shell program that runs a directory of Unix-style programs and produces pretty output. It is normally used for testing shell programs, where each test case corresponds to a single file in the directory that Urchin runs.

Urchin is called "Urchin" because sea urchins have shells called "tests".

Try it out

Urchin's tests are written in Urchin, so you can run them to see what Urchin is like. Download the stable version like so.

wget -o urchin.tar.gz http://tlevine.sdf.org/urchin/tarball/urchin.tar.gz?tag=v0.1.0
tar xzf urchin.tar.gz

Run the tests

cd urchin
./urchin tests

You can clone the unstable version from fossil.

fossil clone http://tlevine.sdf.org/urchin/ urchin.fossil

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.

cd /usr/local/bin
wget http://tlevine.sdf.org/urchin/doc/v0.1.0/urchin
chmod +x urchin

Now you can run it.

urchin <test directory>

Run urchin -h to get command-line help.

Writing tests

Make a root directory for your tests. Inside it, put executable files that exit 0 on success and something else on fail. Non-executable files and hidden files (dotfiles) are ignored, so you can store fixtures right next to your tests. Run urchin from inside the tests directory.

Urchin only cares about the exit status, so you can actually write your tests in any language, not just shell.

Writing cross-shell compatibility tests for testing shell code

While you could write your test scripts to explicitly invoke the functionality to test with various shells, Urchin facilitates a more flexible approach.

The specific approach depends on your test scenario:

  • (a) Your test scripts invoke scripts containing portable shell code.
  • (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).

Urchin runs tests in multiple different shells by default; Urchin has a list of default shells, and the following command will run your tests in all of those shells that Urchin detects.

./urchin ./tests

You can override the default list of shells with the -s flag.

urchin -s sh -s ksh ./tests

You can also

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 recommend 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.

(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 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.)

Note that only test scripts that either have no shebang line at all or have shebang line #!/bin/sh are invoked with the specified shell. This allows non-shell test scripts or test scripts for other languages or for specific shells to coexist with those whose invocation should be controlled by -s.

Further documentation

For documentation of the unstable trunk version, see the man page in the repository or the discussion at thomaslevine.com. For documentation on v0.1, see the v0.1 documentation.