Add documentation for #2288

SC2314.md

@@ -0,0 +1,49 @@
+## bats: ! \<command> will never fail the test
+
+### Problematic code:
+
+```sh
+#!/usr/bin/env bats
+
+@test "test" {
+    # ... code
+    ! test_file_exists
+    # ... more code
+}
+```
+
+### Correct code:
+
+```sh
+#!/usr/bin/env bats
+
+@test "test" {
+    # ... code
+    run ! test_file_exists
+    # ... more code
+}
+```
+
+### Rationale:
+
+Bats uses `set -e` and `trap ERR` to catch test failures as early as possible.
+Although the return code of a `!` negated command is inverted, they will never trigger `errexit`, due to a bash design decision (see [Related Resources](#related-resources)).
+This means that tests which use `!` can never fail.
+
+Starting with bats 1.5.0 you can use `!` inside `run`.
+If you are still using an older bats version, you can rewrite `! <command>` to `<command> && exit 1`.
+
+### Exceptions:
+
+The return code of the last command in the test will be the exit code of the test function.
+This means that you can use `! <command>` on the last line of the test and it will still fail appropriately.
+However, you are encouraged to still use `run !` in this case for consistency.
+
+Shellcheck won't emit this error when using `! <command>` as last command in a test to avoid confusing users whose tests work as intended.
+
+### Related resources:
+
+* [SC2251: This ! is not on a condition and skips errexit](SC2251.md)
+* [Stackoverflow: Why do I need parenthesis In bash `set -e` and negated return code](https://stackoverflow.com/a/39582012/760746)
+* [bash manpage](https://linux.die.net/man/1/bash) (look at `trap [-lp] [[arg] sigspec ...]`):  
+   > The ERR trap is not executed [...] if the command's return value is being inverted via !