From cbe2986210da7dc3ceaf33aee96093acf3bcbcdd Mon Sep 17 00:00:00 2001
From: Nils Winkler <nils@nilswinkler.com>
Date: Wed, 22 Apr 2020 11:19:18 +0200
Subject: [PATCH] Updated test readme

---
 test/README.md | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/test/README.md b/test/README.md
index d227e3c1..0b19fc0f 100644
--- a/test/README.md
+++ b/test/README.md
@@ -1,4 +1,13 @@
-## Testing with [Bats](https://github.com/sstephenson/bats#installing-bats-from-source)
+# Testing with Bats
+
+## Overview
+
+The Bash-it unit tests leverage the [Bats unit test framework for Bash](https://github.com/bats-core/bats-core).
+There is no need to install Bats explicitly, the test run script will automatically download and install Bats and its dependencies.
+
+When making changes to Bash-it, the tests are automatically executed in a test build environment on [Travis CI](https://travis-ci.com).
+
+## Test Execution
 
 To execute the unit tests, please run the `run` script:
 
@@ -10,4 +19,22 @@ To execute the unit tests, please run the `run` script:
 test/run
 ```
 
-The `run` script will automatically install [Bats](https://github.com/sstephenson/bats#installing-bats-from-source) if it is not already present, and will then run all tests found under the `test` directory, including subdirectories.
+The `run` script will automatically install if it is not already present, and will then run all tests found under the `test` directory, including subdirectories.
+
+To run only a subset of the tests, you can provide the name of the test subdirectory that you want to run, e.g. like this for the tests in the `test/themes` directory:
+
+```bash
+# If you are in the root `.bash_it` directory:
+test/run test/themes
+```
+
+By default, the tests run in single-threaded mode.
+If you want to speed up the test execution, you can install the [GNU `parallel` tool](https://www.gnu.org/software/parallel/), which is supported by Bats.
+When using `parallel`, the `test/run` script will use a number of threads in parallel, depending on the available CPU cores of your system.
+This can speed up test execution significantly.
+
+## Writing Tests
+
+When adding or modifying tests, please stick to the format and conventions of the existing test cases.
+The `test_helper.bash` script provides a couple of reusable helper functions that you should use when writing a test case,
+for example for setting up an isolated test environment.