tests

tests/bats/bats-core/docs/source/warnings/BW01.rst

@@ -0,0 +1,17 @@
+BW01: `run`'s command `<command>` exited with code 127, indicating 'Command not found'. Use run's return code checks, e.g. `run -127`, to fix this message.
+===========================================================================================================================================================
+
+Due to `run`'s default behavior of always succeeding, errors in the command string can remain hidden from the user, e.g.[here](https://github.com/bats-core/bats-core/issues/578).
+As a proxy for this problem, the return code is checked for value 127 ("Command not found").
+
+How to fix
+----------
+
+If your command should actually return code 127, then you can simply use `run -127 <your command>` to state your intent and the message will go away.
+
+If your command should not return 127, you should fix the problem with the command.
+Take a careful look at the command string in the warning message, to see if it contains code that you did not intend to run.
+
+If your command should sometimes return 127, but never 0, you can use `run ! <your command>`.
+
+If your command can sometimes return 127 and sometimes 0, the please submit an issue.

tests/bats/bats-core/docs/source/warnings/BW02.rst

@@ -0,0 +1,46 @@
+BW02: <feature> requires at least BATS_VERSION=<version>. Use `bats_require_minimum_version <version>` to fix this message.
+===========================================================================================================================
+
+Using a feature that is only available starting with a certain version can be a problem when your tests also run on older versions of Bats.
+In most cases, running this code in older versions will generate an error due to a missing command.
+However, in cases like `run`'s where old version simply take all parameters as command to execute, the failure can be silent.
+
+How to fix BW02
+---------------
+
+When you encounter this warning, you can simply guard your code with `bats_require_minimum_version <version>` as the message says.
+For example, consider the following code:
+
+.. code-block:: bash
+
+    @test test {
+        bats_require_minimum_version 1.5.0
+        # pre 1.5.0 the flag --separate-stderr would be interpreted as command to run
+        run --separate-stderr some-command 
+        [ $output = "blablabla" ]
+    }
+
+
+The call to `bats_require_minimum_version` can be put anywhere before the warning generating command, even in `setup`, `setup_file`, or even outside any function.
+This can be used to give fine control over the version dependencies:
+
+.. code-block:: bash
+
+    @test test {
+        bats_require_minimum_version 1.5.0
+        # pre 1.5.0 the flag --separate-stderr would be interpreted as command to run
+        run --separate-stderr some-command 
+        [ $output = "blablabla" ]
+    }
+
+    @test test2 {
+        run some-other-command # no problem executing on earlier version
+    }
+
+
+If the above code is executed on a system with a `BATS_VERSION` pre 1.5.0, the first test will fail on `bats_require_minimum_version 1.5.0`.
+
+Instances:
+----------
+
+- run's non command parameters like `--keep-empty-lines` are only available since 1.5.0

tests/bats/bats-core/docs/source/warnings/BW03.rst

@@ -0,0 +1,15 @@
+BW03: `setup_suite` is visible to test file '<path>', but was not executed. It belongs into 'setup_suite.bash' to be picked up automatically.
+=============================================================================================================================================
+
+In contrast to the other setup functions, `setup_suite` must not be defined in `*.bats` files but in `setup_suite.bash`.
+When a file is executed and sees `setup_suite` defined but not run before the tests, this warning will be printed.
+
+How to fix BW03
+---------------
+
+The fix depends on your actual intention. There are basically two cases:
+
+1. You want a setup before all tests and accidentally put `setup_suite` into a test file instead of `setup_suite.bash`.
+   Simply move `setup_suite` (and `teardown_suite`!) into `setup_suite.bash`.
+2. You did not mean to run a setup before any test but need to defined a function named `setup_suite` in your test file.
+   In this case, you can silence this warning by assigning `BATS_SETUP_SUITE_COMPLETED='suppress BW03'`.

tests/bats/bats-core/docs/source/warnings/index.rst

@@ -0,0 +1,28 @@
+Warnings
+========
+
+Starting with version 1.7.0 Bats shows warnings about issues it found during the test run.
+They are printed on stderr after all other output:
+
+.. code-block:: bash
+
+     BW01.bats
+     ✓ Trigger BW01
+    
+     1 test, 0 failures
+    
+    
+     The following warnings were encountered during tests:
+     BW01: `run`'s command `=0 actually-intended-command with some args` exited with code 127, indicating 'Command not found'. Use run's return code checks, e.g. `run -127`, to fix this message.
+           (from function `run' in file lib/bats-core/test_functions.bash, line 299,
+            in test file test/fixtures/warnings/BW01.bats, line 3)
+
+A warning will not make a successful run fail but should be investigated and taken seriously, since it hints at a possible error.
+
+Currently, Bats emits the following warnings:
+
+.. toctree::
+
+    BW01
+    BW02
+    BW03