From c62219df15f483b4d844da583179e1dc94ad31a5 Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Sun, 10 Jul 2022 11:56:32 -0400 Subject: [PATCH 1/2] overriding skips instructions on web docs as well as HELP.md file --- docs/TESTS.md | 43 +++++++++++++++++++++++++++++---- exercises/shared/.docs/tests.md | 13 ++++++++++ 2 files changed, 51 insertions(+), 5 deletions(-) diff --git a/docs/TESTS.md b/docs/TESTS.md index 9698cfc5..434cc2dd 100644 --- a/docs/TESTS.md +++ b/docs/TESTS.md @@ -28,8 +28,7 @@ Shell scripts are executed in a child process and cannot effect the environment ## 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 @@ -37,13 +36,12 @@ 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 @@ -69,7 +67,7 @@ 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 @@ -87,6 +85,7 @@ Usage: bats [-cr] [-f ] [-j ] [-p | -t] ... ``` ### For Windows (MINGW64/Cygwin) + ``` $ git clone https://github.com/bats-core/bats-core.git $ cd bats @@ -99,6 +98,40 @@ There are reports that [newer bats versions don't behave well on MinGW bash][min $ 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..24e27b8a 100644 --- a/exercises/shared/.docs/tests.md +++ b/exercises/shared/.docs/tests.md @@ -27,7 +27,20 @@ Once it passes, you can enable the next test by commenting out or removing the 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 +``` From a8722a507a267aca88da62b74e3355823ce6dd2c Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Sun, 10 Jul 2022 12:39:33 -0400 Subject: [PATCH 2/2] review suggestions: whitespace around code fences, markdown style: one line = one sentence; link style --- docs/TESTS.md | 15 ++++++++++++++- exercises/shared/.docs/tests.md | 29 ++++++++++++++++++----------- 2 files changed, 32 insertions(+), 12 deletions(-) diff --git a/docs/TESTS.md b/docs/TESTS.md index 434cc2dd..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,6 +24,7 @@ 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. @@ -31,6 +33,7 @@ Shell scripts are executed in a child process and cannot effect the environment 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 @@ -43,6 +46,7 @@ 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 @@ -70,13 +74,16 @@ sudo dnf install bats 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] ... @@ -91,9 +98,11 @@ $ 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 ``` @@ -117,17 +126,21 @@ annotations prepending other tests. 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 ``` diff --git a/exercises/shared/.docs/tests.md b/exercises/shared/.docs/tests.md index 24e27b8a..36c1fd47 100644 --- a/exercises/shared/.docs/tests.md +++ b/exercises/shared/.docs/tests.md @@ -2,45 +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. -## Skipped tests +[bats-assert]: https://github.com/bats-core/bats-assert -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 +## Skipped tests - [[ $BATS_RUN_SKIPPED == true ]] || skip +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: -annotations prepending other tests. +```bash +[[ $BATS_RUN_SKIPPED == true ]] || skip +``` ## 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 ```