1 files changed, 69 insertions, 0 deletions
diff --git a/tests/pytests/README.rst b/tests/pytests/README.rst
new file mode 100644
index 0000000..63db3ef
--- /dev/null
+++ b/tests/pytests/README.rst
@@ -0,0 +1,69 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+Python client tests for kresd
+=============================
+
+The tests run `/usr/bin/env kresd` (can be modified with `$PATH`) with custom config
+and execute client-side testing, such as TCP / TLS connection management.
+
+Requirements
+------------
+
+- pip3 install -r requirements.txt
+
+Executing tests
+---------------
+
+Tests can be executed with the pytest framework.
+
+.. code-block:: bash
+
+   $ pytest-3  # sequential, all tests (with exception of few special tests)
+   $ pytest-3 test_conn_mgmt.py::test_ignore_garbage   # specific test only
+   $ pytest-3 --html pytests.html --self-contained-html  # html report
+
+It's highly recommended to run these tests in parallel, since lot of them
+wait for kresd timeout. This can be done with `python-xdist`:
+
+.. code-block:: bash
+
+   $ pytest-3 -n 24  # parallel with 24 jobs
+
+Each test spawns an independent kresd instance, so test failures shouldn't affect
+each other.
+
+Some tests are omitted from automatic test collection by default, due to their
+resource constraints. These typically have to be executed separately by providing
+the path to test file directly.
+
+.. code-block:: bash
+
+   $ pytest-3 conn_flood.py
+
+Note: some tests may fail without an internet connection.
+
+Additional usage notes
+----------------------
+
+- Not everything is logged into pytest's standard output. To inspect the logs of
+  `kresd` itself, see `/tmp/pytest-of-<username>/pytest-current`.
+- The `rr` and `valgrind` parameters of the `Kresd` constructor may be used to
+  gain further information on failing tests. Simply set them to `True` in the
+  test cases temporarily if you need them.
+    - `rr=True` will record the execution of `kresd`, which can then be replayed
+      with the usual `rr replay` command.
+    - `valgrind=True` will run `kresd` under `valgrind`, the results of which
+      can be inspected in `kresd`'s logs (see above).
+
+Developer notes
+---------------
+
+Typically, each test requires a setup of kresd, and a connected socket to run tests on.
+The framework provides a few useful pytest fixtures to simplify this process:
+
+- `kresd_sock` provides a connected socket to a test-specific, running kresd instance.
+  It expands to 4 values (tests) - IPv4 TCP, IPv6 TCP, IPv4 TLS, IPv6 TLS sockets
+- `make_kresd_sock` is similar to `kresd_sock`, except it's a factory function that
+  produces a new connected socket (of the same type) on each call
+- `kresd`, `kresd_tt` are all Kresd instances, already running
+  and initialized with config (with no / valid TLS certificates)