diff --git a/docs/TESTS.md b/docs/TESTS.md index 9698cfc5..66838739 100644 --- a/docs/TESTS.md +++ b/docs/TESTS.md @@ -13,6 +13,7 @@ See [the exercism cli documentation][exercism-cli]. One annoying aspect of the default exercism tool is that, after you download an exercise, you have to change directory manually. This wrapper function handles that for you; store this in your `~/.bashrc`. + ```bash exercism () { local out @@ -23,28 +24,29 @@ exercism () { fi } ``` + Note that cannot be a shell _script_, it must be a shell _function_. Shell scripts are executed in a child process and cannot effect the environment (like the current working directory) of your current shell. ## Testing locally -As there isn't much of a bash ecosystem, there also isn't really a defacto leader in the bash testing area. -For these examples we are using [bats][bats]. +For testing on the bash track, we are using [bats][bats]. Run the tests for the hypothetical "whatever" exercise like this: + ```bash cd /path/to/your/exercise_workspace/bash/whatever bats whatever.bats ``` -For help on the meaning of the various `assert*` commands in the tests, refer to the documentation for the [bats-assert][bats-assert] library. - ## Installing `bats-core` You should be able to install it from your favorite package manager: ### For Mac (brew) + On macOS with [Homebrew][homebrew] this would look something like this: + ``` $ brew install bats-core ==> Downloading https://github.com/bats-core/bats-core/archive/v1.1.0.tar.gz @@ -69,16 +71,19 @@ sudo dnf install bats #### Other Linux -For other Linux distributions the implementation of `bats` we use is not conveniently packaged. +For other Linux distributions the implementation of `bats` we use may not be conveniently packaged. The best way to install it is from source. If you want to install it under `/usr/local` then + ```bash git clone https://github.com/bats-core/bats-core cd bats-core/ sudo ./install.sh /usr/local ``` + Following that, assuming `/usr/local/bin` is in your $PATH, you can now do: -``` + +```bash $ bats Error: Must specify at least one Usage: bats [-cr] [-f ] [-j ] [-p | -t] ... @@ -87,18 +92,59 @@ Usage: bats [-cr] [-f ] [-j ] [-p | -t] ... ``` ### For Windows (MINGW64/Cygwin) + ``` $ git clone https://github.com/bats-core/bats-core.git $ cd bats $ ./install.sh $HOME ``` + Note: When you are using the outdated `https://github.com/sstephenson/bats.git` and you discover an error like `cp: cannot create symbolic link '${HOME}/bin/bats': No such file or directory`, you have to copy the `bin/bats/libexec/` folder content to `${HOME}/bin/` manually. There are reports that [newer bats versions don't behave well on MinGW bash][mingw-issues] -- before you run the install script, you might want to: + ``` $ git checkout v1.1.0 ``` +## bats-assert + +For help on the meaning of the various `assert*` commands in the tests, refer to the documentation for the [bats-assert][bats-assert] library. + +## Skipped tests + +Solving an exercise means making all its tests pass. +By default, only one test (the first one) is executed when you run the tests. +This is intentional, as it allows you to focus on just making that one test pass. +Once it passes, you can enable the next test by commenting out or removing the + + [[ $BATS_RUN_SKIPPED == true ]] || skip + +annotations prepending other tests. + +### Overriding skips + +To run all tests, including the ones with `skip` annotations, you can set an environment variable `BATS_RUN_SKIPPED` to the value `true`. +One way to set this just for the duration of running bats is: + +```bash +BATS_RUN_SKIPPED=true bats exercise_name.bats +``` + +It can be convenient to use a wrapper function to save on typing: + +```bash +bats() { + BATS_RUN_SKIPPED=true command bats *.bats +} +``` + +Then run tests with just: + +```bash +bats +``` + ## Legacy `bats` `bats-core` was forked from [the original `bats` implementation][sstephenson-bats]. diff --git a/exercises/shared/.docs/tests.md b/exercises/shared/.docs/tests.md index f3738163..36c1fd47 100644 --- a/exercises/shared/.docs/tests.md +++ b/exercises/shared/.docs/tests.md @@ -2,32 +2,52 @@ Each exercise contains a test file. Run the tests using the `bats` program. + ```bash bats hello_world.bats ``` `bats` will need to be installed. -See the [Testing on the Bash track](https://exercism.org/docs/tracks/bash/tests) page for -instructions to install `bats` for your system. +See the [Testing on the Bash track][tests] page for instructions to install `bats` for your system. + +[tests]: https://exercism.org/docs/tracks/bash/tests ## Help for assert functions -The tests use functions from the -[bats-assert](https://github.com/bats-core/bats-assert) library. +The tests use functions from the [bats-assert][bats-assert] library. Help for the various `assert*` functions can be found there. +[bats-assert]: https://github.com/bats-core/bats-assert + ## Skipped tests -Solving an exercise means making all its tests pass. By default, only one -test (the first one) is executed when you run the tests. This is -intentional, as it allows you to focus on just making that one test pass. -Once it passes, you can enable the next test by commenting out or removing the +Solving an exercise means making all its tests pass. +By default, only one test (the first one) is executed when you run the tests. +This is intentional, as it allows you to focus on just making that one test pass. +Once it passes, you can enable the next test by commenting out or removing the next annotation: - [[ $BATS_RUN_SKIPPED == true ]] || skip +```bash +[[ $BATS_RUN_SKIPPED == true ]] || skip +``` -annotations prepending other tests. +## Overriding skips To run all tests, including the ones with `skip` annotations, you can run: + ```bash BATS_RUN_SKIPPED=true bats exercise_name.bats ``` + +It can be convenient to use a wrapper function to save on typing: + +```bash +bats() { + BATS_RUN_SKIPPED=true command bats *.bats +} +``` + +Then run tests with just: + +```bash +bats +```