Doc/changelog entry for BATS_TEST_TIMEOUT (bats-core#491)

TApplencourt · Aug 5, 2022 · bf5d4eb · bf5d4eb
1 parent 947597f
commit bf5d4eb
Show file tree

Hide file tree

Showing 4 changed files with 10 additions and 1 deletion.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -20,6 +20,7 @@ The format is based on [Keep a Changelog][kac] and this project adheres to
 * Docker tags `latest-no-faccessat2` and `<bats-version\>-no-faccessat2` for
   avoiding `bash: bats: No such file or directory` on `docker<20.10` (or
   `runc<v1.0.0-rc93`) (#622)
+* `BATS_TEST_TIMEOUT` variable to force a timeout on test (including `setup()`) (#491)
 
 #### Documentation
 

diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -145,7 +145,8 @@ If you need the library inside `setup_file` or `teardown_file` you need to load
 How to set a test timeout in bats?
 ----------------------------------
 
-Unfortunately, this is not possible yet. Please contribute to issue `#396 <https://github.com/bats-core/bats-core/issues/396>`_ for further progress.
+Set the variable `$BATS_TEST_TIMEOUT` before `setup()` starts. This means you can set it either on the command line,
+in free code in the test file or in `setup_file()`.
 
 How can I lint/shell-format my bats tests?
 ------------------------------------------

diff --git a/docs/source/writing-tests.md b/docs/source/writing-tests.md
@@ -379,6 +379,10 @@ There are several global variables you can use to introspect on Bats tests:
 - `BATS_TEST_RETRIES` is the maximum number of additional attempts that will be
   made on a failed test before it is finally considered failed.
   The default of 0 means the test must pass on the first attempt.
+- `BATS_TEST_TIMEOUT` is the number of seconds after which a test (including setup)
+  will be aborted and marked as failed. Updates to this value in `setup()` or `@test`
+  cannot change the running timeout countdown, so the latest useful update location
+  is `setup_file()`.
 - `$BATS_TEST_NUMBER` is the (1-based) index of the current test case in the test file.
 - `$BATS_SUITE_TEST_NUMBER` is the (1-based) index of the current test case in the test suite (over all files).
 - `$BATS_TMPDIR` is the base temporary directory used by bats to create its

diff --git a/man/bats.7.ronn b/man/bats.7.ronn
@@ -238,6 +238,9 @@ case.
 * `BATS_TEST_RETRIES` is the maximum number of additional attempts that will be
   made on a failed test before it is finally considered failed.
   The default of 0 means the test must pass on the first attempt.
+* `BATS_TEST_TIMEOUT` is the number of seconds after which a test (including setup)
+  will be aborted and marked as failed. Updates to this value in `setup()` or `@test`
+  cannot change the running timeout countdown, so the latest useful update location is `setup_file()`.
 * `$BATS_TEST_NUMBER` is the (1-based) index of the current test case
 in the test file.
 * `$BATS_SUITE_TEST_NUMBER` is the (1-based) index of the current test