From d903d14da5cc8937176df448b731d12a0518f36f Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Wed, 20 Sep 2023 13:58:15 +0200
Subject: [PATCH] docs: moar integration docs

---
 docs/abra/hack.md | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/docs/abra/hack.md b/docs/abra/hack.md
index 8ae197f..82ac15a 100644
--- a/docs/abra/hack.md
+++ b/docs/abra/hack.md
@@ -22,6 +22,8 @@ Please use the [conventional commit format](https://www.conventionalcommits.org/
 
 ## Integration tests
 
+### Install dependencies
+
 We use [`bats`](https://bats-core.readthedocs.io/en/stable/), you can install
 the required dependencies with the following. You also need a working
 installation of Docker and Go (not covered in this section).
@@ -32,7 +34,7 @@ apt install bats-file bats-assert bats-support jq make git
 
 Unfortunately, the latest `bats` version in Debian stable does not have the
 "filter tests by tags" feature, which is very handy for running a subset of the
-tests. For this, we need to install `bats` from source. It's easy:
+tests. For this, we need to install `bats` from source. It's easy.
 
 ```
 apt purge -y bats
@@ -41,32 +43,49 @@ cd bats-core
 sudo ./install.sh /usr/local
 ```
 
-Then you can run the integration test suite with the following:
+### Run tests
+
+Then you can run the integration test suite with the following.
 
 ```
 export ABRA_TEST_DOMAIN="test.example.com"
 export ABRA_DIR="$HOME/.abra_test"
-bats tests/integration
+bats -Tp tests/integration
 ```
 
 `ABRA_TEST_DOMAIN` should also have a DNS A record for `*.test.example.com`
 which points to the same server so that the test suite can deploy apps freely.
 It's advised that you re-use the same server and therefore the same Traefik
-deployment for running your integration tests. Then you'll have more stable
-results.
+deployment for running your integration tests. The test suite does not deploy
+Traefik for you. Then you'll have more stable results.
+
+### Filter tests
 
 You can filter on test names to run specific kinds of tests.
 
 ```
-bats tests/integration --filter "validate app argument"
+bats -Tp tests/integration --filter "validate app argument"
 ```
 
-You can filter on tags also.
+You can filter on tags.
 
 ```
-bats tests/integration --filter-tags fast
+bats -Tp tests/integration --filter-tags "\!slow" # only fast tests
+bats -Tp tests/integration --filter-tags "slow"   # only slow tests
 ```
 
+You can also only run the previously failed tests.
+
+```
+bats -TP tests/integration --filter-status failed
+```
+
+### Debug tests
+
+If you're running into issues and want to debug stuff, you can pass `-x` to
+`bats` to trace all commands run in the test. You can add `echo '...' >&3`
+debug statements to your test to output stuff also.
+
 ## Using the `abra` public API
 
 Warning, there is currently no stability promise for the `abra` public API! Most of the internals are exposed in order to allow a free hand for developers to try build stuff. If people start to build things then we can start the discussion on what is useful to have open/closed and keep stable etc. Please let us know if you depend on the APIs!