Document bats_require_minimum_version

docs/CHANGELOG.md

@@ -16,6 +16,7 @@ The format is based on [Keep a Changelog][kac] and this project adheres to
 
 * update gotcha about negated statements: Recommend using `run !` on Bats
   versions >=1.5.0 (#593)
+* add documentation for `bats_require_minimum_version` (#595)
 
 ## [1.7.0] - 2022-05-14
 

docs/source/writing-tests.md

@@ -268,6 +268,28 @@ teardown_suite # from setup_suite.bash
 </details>
 <!-- markdownlint-enable MD033 -->
 
+## `bats_require_minimum_version <Bats version number>`
+
+Added in [v1.7.0](https://github.com/bats-core/bats-core/releases/tag/v1.7.0)
+
+Code for newer versions of Bats can be incompatible with older versions.
+In the best case this will lead to an error message and a failed test suite.
+In the worst case, the tests will pass erronously, potentially masking a failure.
+
+Use `bats_require_minimum_version <Bats version number>` to avoid this.
+It communicates in a concise manner, that you intend the following code to be run
+under the given Bats version or higher.
+
+Additionally, this function will communicate the current Bats version floor to
+subsequent code, allowing e.g. Bats' internal warning to give more informed warnings.
+
+__Note__: By default, calling `bats_require_minimum_version` with versions before
+Bats 1.7.0 will fail regardless of the required version as the function is not
+available. However, you can use the
+[bats-backports plugin](https://github.com/bats-core/bats-backports) to make
+your code usable with older versions, e.g. during migration while your CI system
+is not yet upgraded.
+
 ## Code outside of test cases
 
 You can include code in your test file outside of `@test` functions.  For

man/bats.7

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "BATS" "7" "November 2021" "bats-core" "Bash Automated Testing System"
+.TH "BATS" "7" "May 2022" "bats-core" "Bash Automated Testing System"
 .
 .SH "NAME"
 \fBbats\fR \- Bats test file format
@@ -115,6 +115,66 @@ load test_helper
 .P
 will source the script \fBtest/test_helper\.bash\fR in your test file\. This can be useful for sharing functions to set up your environment or load fixtures\.
 .
+.SH "THE BATS_LOAD_LIBRARY COMMAND"
+Some libraries are installed on the system, e\.g\. by \fBnpm\fR or \fBbrew\fR\. These should not be \fBload\fRed, as their path depends on the installation method\. Instead, one should use \fBbats_load_library\fR together with setting \fBBATS_LIB_PATH\fR, a \fBPATH\fR\-like colon\-delimited variable\.
+.
+.P
+\fBbats_load_library\fR has two modes of resolving requests:
+.
+.IP "1." 4
+by relative path from the \fBBATS_LIB_PATH\fR to a file in the library
+.
+.IP "2." 4
+by library name, expecting libraries to have a \fBload\.bash\fR entrypoint
+.
+.IP "" 0
+.
+.P
+For example if your \fBBATS_LIB_PATH\fR is set to \fB~/\.bats/libs:/usr/lib/bats\fR, then \fBbats_load_library test_helper\fR would look for existing files with the following paths:
+.
+.IP "\(bu" 4
+\fB~/\.bats/libs/test_helper\fR
+.
+.IP "\(bu" 4
+\fB~/\.bats/libs/test_helper/load\.bash\fR
+.
+.IP "\(bu" 4
+\fB/usr/lib/bats/test_helper\fR
+.
+.IP "\(bu" 4
+\fB/usr/lib/bats/test_helper/load\.bash\fR
+.
+.IP "" 0
+.
+.P
+The first existing file in this list will be sourced\.
+.
+.P
+If you want to load only part of a library or the entry point is not named \fBload\.bash\fR, you have to include it in the argument: \fBbats_load_library library_name/file_to_load\fR will try
+.
+.IP "\(bu" 4
+\fB~/\.bats/libs/library_name/file_to_load\fR
+.
+.IP "\(bu" 4
+\fB~/\.bats/libs/library_name/file_to_load/load\.bash\fR
+.
+.IP "\(bu" 4
+\fB/usr/lib/bats/library_name/file_to_load\fR
+.
+.IP "\(bu" 4
+\fB/usr/lib/bats/library_name/file_to_load/load\.bash\fR
+.
+.IP "" 0
+.
+.P
+Apart from the changed lookup rules, \fBbats_load_library\fR behaves like \fBload\fR\.
+.
+.P
+\fBNote\fR: As seen above \fBload\.bash\fR is the entry point for libraries and meant to load more files from its directory or other libraries\.
+.
+.P
+\fBNote\fR: Obviously, the actual \fBBATS_LIB_PATH\fR is highly dependant on the environment\. To maintain a uniform location across systems, (distribution) package maintainers are encouraged to use \fB/usr/lib/bats/\fR as the install path for libraries where possible\. However, if the package manager has another preferred location, like \fBnpm\fR or \fBbrew\fR, you should use this instead\.
+.
 .SH "THE SKIP COMMAND"
 Tests can be skipped by using the \fBskip\fR command at the point in a test you wish to skip\.
 .
@@ -166,6 +226,18 @@ Or you can skip conditionally:
 .
 .IP "" 0
 .
+.SH "THE BATS_REQUIRE_MINIMUM_VERSION COMMAND"
+Code for newer versions of Bats can be incompatible with older versions\. In the best case this will lead to an error message and a failed test suite\. In the worst case, the tests will pass erronously, potentially masking a failure\.
+.
+.P
+Use \fBbats_require_minimum_version <Bats version number>\fR to avoid this\. It communicates in a concise manner, that you intend the following code to be run under the given Bats version or higher\.
+.
+.P
+Additionally, this function will communicate the current Bats version floor to subsequent code, allowing e\.g\. Bats\' internal warning to give more informed warnings\.
+.
+.P
+\fBNote\fR: By default, calling \fBbats_require_minimum_version\fR with versions before Bats 1\.7\.0 will fail regardless of the required version as the function is not available\. However, you can use the bats\-backports plugin (https://github\.com/bats\-core/bats\-backports) to make your code usable with older versions, e\.g\. during migration while your CI system is not yet upgraded\.
+.
 .SH "SETUP AND TEARDOWN FUNCTIONS"
 You can define special \fBsetup\fR and \fBteardown\fR functions which run before and after each test case, respectively\. Use these to load fixtures, set up your environment, and clean up when you\'re done\.
 .
@@ -188,6 +260,9 @@ There are several global variables you can use to introspect on Bats tests:
 \fB$BATS_TEST_NAME\fR is the name of the function containing the current test case\.
 .
 .IP "\(bu" 4
+\fBBATS_TEST_NAME_PREFIX\fR will be prepended to the description of each test on stdout and in reports\.
+.
+.IP "\(bu" 4
 \fB$BATS_TEST_DESCRIPTION\fR is the description of the current test case\.
 .
 .IP "\(bu" 4

man/bats.7.ronn

@@ -105,6 +105,49 @@ will source the script `test/test_helper.bash` in your test file. This
 can be useful for sharing functions to set up your environment or load
 fixtures.
 
+THE BATS_LOAD_LIBRARY COMMAND
+-----------------------------
+
+Some libraries are installed on the system, e.g. by `npm` or `brew`.
+These should not be `load`ed, as their path depends on the installation method.
+Instead, one should use `bats_load_library` together with setting
+`BATS_LIB_PATH`, a `PATH`-like colon-delimited variable.
+
+`bats_load_library` has two modes of resolving requests:
+
+1. by relative path from the `BATS_LIB_PATH` to a file in the library
+2. by library name, expecting libraries to have a `load.bash` entrypoint
+
+For example if your `BATS_LIB_PATH` is set to
+`~/.bats/libs:/usr/lib/bats`, then `bats_load_library test_helper`
+would look for existing files with the following paths:
+
+- `~/.bats/libs/test_helper`
+- `~/.bats/libs/test_helper/load.bash`
+- `/usr/lib/bats/test_helper`
+- `/usr/lib/bats/test_helper/load.bash`
+
+The first existing file in this list will be sourced.
+
+If you want to load only part of a library or the entry point is not named `load.bash`,
+you have to include it in the argument:
+`bats_load_library library_name/file_to_load` will try
+
+- `~/.bats/libs/library_name/file_to_load`
+- `~/.bats/libs/library_name/file_to_load/load.bash`
+- `/usr/lib/bats/library_name/file_to_load`
+- `/usr/lib/bats/library_name/file_to_load/load.bash`
+
+Apart from the changed lookup rules, `bats_load_library` behaves like `load`.
+
+**Note**: As seen above `load.bash` is the entry point for libraries and
+meant to load more files from its directory or other libraries.
+
+**Note**: Obviously, the actual `BATS_LIB_PATH` is highly dependant on the environment.
+To maintain a uniform location across systems, (distribution) package maintainers
+are encouraged to use `/usr/lib/bats/` as the install path for libraries where possible.
+However, if the package manager has another preferred location, like `npm` or `brew`,
+you should use this instead.
 
 THE SKIP COMMAND
 ----------------
@@ -135,6 +178,27 @@ Or you can skip conditionally:
     }
 
 
+THE BATS_REQUIRE_MINIMUM_VERSION COMMAND
+----------------------------------------
+
+Code for newer versions of Bats can be incompatible with older versions.
+In the best case this will lead to an error message and a failed test suite.
+In the worst case, the tests will pass erronously, potentially masking a failure.
+
+Use `bats_require_minimum_version <Bats version number>` to avoid this.
+It communicates in a concise manner, that you intend the following code to be run
+under the given Bats version or higher.
+
+Additionally, this function will communicate the current Bats version floor to
+subsequent code, allowing e.g. Bats' internal warning to give more informed warnings.
+
+**Note**: By default, calling `bats_require_minimum_version` with versions before
+Bats 1.7.0 will fail regardless of the required version as the function is not
+available. However, you can use the
+bats-backports plugin (https://github.com/bats-core/bats-backports) to make
+your code usable with older versions, e.g. during migration while your CI system
+is not yet upgraded.
+
 SETUP AND TEARDOWN FUNCTIONS
 ----------------------------