1 files changed, 80 insertions, 0 deletions
diff --git a/doc/testing.md b/doc/testing.md
new file mode 100644
index 0000000..99db290
--- /dev/null
+++ b/doc/testing.md
@@ -0,0 +1,80 @@
+# Automated testing
+
+## Introduction
+
+The bash-completion package contains an automated test suite. Running the
+tests should help verifying that bash-completion works as expected. The tests
+are also very helpful in uncovering software regressions at an early stage.
+
+The test suite is written in Python, using [pytest](https://pytest.org/)
+and [pexpect](https://pexpect.readthedocs.io/).
+
+## Coding style
+
+For the Python part, all of it is checked and formatted using
+[Ruff](https://docs.astral.sh/ruff/).
+
+## Installing dependencies
+
+Installing dependencies should be easy using your local package manager or
+`pip`. Python 3.6 or newer is required, and the rest of the Python package
+dependencies are specified in the `test/requirements.txt` file. If using `pip`,
+this file can be fed directly to it, e.g. like:
+
+```shell
+python3 -m pip install -r test/requirements.txt
+```
+
+### Debian/Ubuntu
+
+On Debian/Ubuntu you can use `apt-get`:
+
+```shell
+sudo apt-get install python3-pytest python3-pexpect
+```
+
+This should also install the necessary dependencies. Only Debian testing
+(buster) and Ubuntu 18.10 (cosmic) and later have an appropriate version
+of pytest in the repositories.
+
+### Fedora/RHEL/CentOS
+
+On Fedora and RHEL/CentOS (with EPEL) you can try `yum` or `dnf`:
+
+```shell
+sudo yum install python3-pytest python3-pexpect
+```
+
+This should also install the necessary dependencies. At time of writing, only
+Fedora 29 comes with recent enough pytest.
+
+## Structure
+
+Tests are in the `t/` subdirectory, with `t/test_*.py` being completion
+tests, and `t/unit/test_unit_*.py` unit tests.
+
+## Running the tests
+
+Tests are run by calling `pytest` on the desired test directories or
+individual files, for example in the project root directory:
+
+```shell
+pytest test/t
+```
+
+See `test/docker/entrypoint.sh` for how and what we run and test in CI.
+
+### Specifying bash binary
+
+The test suite standard uses `bash` as found in `$PATH`. Export the
+`bashcomp_bash` environment variable with a path to another bash executable if
+you want to test against something else.
+
+## Maintenance
+
+### Adding a completion test
+
+You can run `cd test && ./generate cmd` to add a test for the `cmd`
+command. Additional arguments will be passed to the first generated test case.
+This will add the `test/t/test_cmd.py` file with a very basic test, and add it
+to `test/t/Makefile.am`. Add additional tests to the generated file.