diff --git a/README.md b/README.md index 235bf1e..5c1f4ba 100644 --- a/README.md +++ b/README.md @@ -168,6 +168,73 @@ Or you can skip conditionally: } ``` +### Explicit test names + +In most cases, tests don't need to be assigned an explicit name, but some features, +like dependencies described below, reference tests by their names. In such cases, +the test(s) you reference must be assigned an explicit name. + +An explicit name is defined using an extension to the base +syntax: replace '@test' by '@test[]'. + +Example: + +```bash +@test[mytest1] "Test description..." { +... +``` + +Notes: + +* Every test may define an explicit name, even if it not referenced anywhere, +* In a given test file, each explicit name must be unique. You cannot assign the +same name to different tests, +* Explicit names must be composed from alphanumeric characters + underscore +('_') only. + +### Test dependencies + +Some tests may have one or more tests as pre-requisites, meaning that tests +are irrelevant if the pre-requisites fail. A common case is test A checking that a +given service is running, while test B and C use this service to retrieve more +information. If service is not running, we know for sure that test B and C will +fail. In order to avoid a bunch of errors when such dependency exists, you can +instruct bash to skip test B and C if A fails. + +In order to implement such a dependency, you will use the 'bats_test_succeeds()' +function. This function returns true (0) if all its argument every test names +succeeded, and false if any of them failed. + +Example: + +```bash +@test[testA] "A pre-requisite check" { + service foo status +} + +@test[testAbis] "Oh, I need this too!" { + service bar status +} + +# I don't want to run this if pre-requisites are unavailable + +@test "Let's check this more in depth..." { + bats_test_succeeds testA testAbis || skip "Pre-requisites are unavailable" + # In-depth check starts here + ... +} +``` + +Notes: + +* You cannot define cross-file dependencies. The test(s) you refer too must +be located in the same test file. +* As tests are executed in the order they appear in the file, you can only depend +on tests that appear in the test file BEFORE/ABOVE the current test. If this is +not the case, a warning message is issued on stderr and the parent test is +supposed to be successful (depending test will run). +* You need to set explicit names for the tests you want to create dependencies on. + ### `setup` and `teardown`: Pre- and post-test hooks You can define special `setup` and `teardown` functions, which run @@ -199,10 +266,12 @@ test case. case. * `$BATS_TEST_NUMBER` is the (1-based) index of the current test case in the test file. +* `BATS_TEST_RESULTS` is an array of results for tests that ran so far. +Only elements from 1 to $BATS_TEST_NUMBER (excluded) are set. Values are +0 if test succeeded, and different from 0 if test failed. * `$BATS_TMPDIR` is the location to a directory that may be used to store temporary files. - ## Installing Bats from source Check out a copy of the Bats repository. Then, either add the Bats diff --git a/libexec/bats-exec-test b/libexec/bats-exec-test index f2dab89..5f9e234 100755 --- a/libexec/bats-exec-test +++ b/libexec/bats-exec-test @@ -288,7 +288,7 @@ bats_test_succeeds() { else status=${BATS_TEST_RESULTS[$index]} if [ -z $status ] ; then - echo "Warning: $name: Cannot check status as test didn't run yet" + echo "Warning: $name: Cannot check status as test didn't run yet" >&2 else let ret+=$status fi