diff --git a/HISTORY b/HISTORY index 40e0a42..2a92a7a 100644 --- a/HISTORY +++ b/HISTORY @@ -156,6 +156,36 @@ to matter quite little in the case of Urchin. the code (also because it's in shell). Thus, I think a GPL license on Urchin wouldn't infect the code being tested. +### Specification of the shell to run tests in +Urchin previously had separate methods for setting the TEST_SHELL environment +variable and for setting the shell that would run the tests; the former was +set as an environment variable, and the latter was set with the -s flag.. + +Urchin now uses the -s flag for both of these settings, and it mostly ignores +the exported TEST_SHELL variable. + +Urchin also inspects the shebang line differently. Previously, Urchin would +vary the shells with which a test is run if the shebang line either was absent +or was #!/bin/sh. Now it varies the shell only if the shebang line is absent. + +If you pass -n/--disable-cycling, Urchin will invoke tests ordinarily and will +only set the TEST_SHELL variable if it does not exist. If the TEST_SHELL +variable is absent, it will be set to /bin/sh. + +Here is how you should write your tests for cross-shell testing, depending on +their structure. + +* If you want a test file to run in the same shell every time and to have + access to the TEST_SHELL variable, usually for invoking the program that + you are testing, then set the file's shebang line. +* If you want a test file to be run in a different shell every time, do not + set the shebang line. TEST_SHELL variable will be set to correspond with the + shell that is presently invoking the test file, though you probably won't + need this variable. +* If you want a test file to have access to a TEST_SHELL variable that you + set yourself, pass -n/--disable-cycling to urchin. Urchin will ignore the + shebang lines in this case. + ### Source setup and teardown setup, teardown, setup_dir, and teardown_dir are now sourced instead of executed; they are referenced a bit like this. diff --git a/TODO b/TODO index 1e489c4..7f2391f 100644 --- a/TODO +++ b/TODO @@ -1,16 +1,6 @@ Things I want ============= -Environment variables -------------- -Do something to make it easier to debug environment variables, because that is -often confusing. -https://github.com/creationix/nvm/issues/719 -https://github.com/creationix/nvm/issues/589 - -Documenting that people should run "env" when their tests fail might be good -enough. - Packaging ------------ Package for package managers. @@ -33,3 +23,9 @@ Try running Urchin in Windows somehow. Interpreters include * Git for Windows (https://git-scm.com/download/win) * win-bash (http://win-bash.sourceforge.net/) +shall +---------- +Add shall to my NYC*BUG talk. + + #!/usr/bin/env shall + echo This runs in several shells. diff --git a/readme.md b/readme.md index 1cd0e49..eeaabb2 100644 --- a/readme.md +++ b/readme.md @@ -23,14 +23,6 @@ Run the tests cd urchin ./urchin tests -The above command will run the tests in your system's 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: - - 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. @@ -81,11 +73,13 @@ and directories have special meanings. teardown Directories are processed in a depth-first order. When a particular directory -is processed, `setup_dir` is run before everything else in the directory, including -subdirectories. `teardown_dir` is run after everything else in the directory. +is processed, `setup_dir` is sourced before everything else in the directory, +including subdirectories. `teardown_dir` is sourced after everything else in +the directory. -A directory's `setup` file, if it exists, is run right before each test file -within the particular directory, and the `teardown` file is run right after. +A directory's `setup` file, if it exists, is sourced right before each test +file within the particular directory is run, and the `teardown` file is +sourced right after. 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 @@ -119,16 +113,17 @@ 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`). -On invocation of Urchin, prepend a definition of environment variable -`TEST_SHELL` specifying the shell to test with, e.g., +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. - TEST_SHELL=zsh urchin ./tests + ./urchin ./tests -To test with multiple shells in sequence, use something like: +You can override the default list of shells with the `-s` flag. - for shell in sh bash ksh zsh; do - TEST_SHELL=$shell urchin ./tests - done + 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 @@ -159,13 +154,3 @@ To test with multiple shells in sequence, use something like: for shell in sh bash ksh zsh; do 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. - - #!/usr/bin/env shall - echo This is a test file. - -## Alternatives to Urchin -Alternatives to Urchin are discussed in -[this blog post](https://blog.scraperwiki.com/2012/12/how-to-test-shell-scripts/).