From 30c5581ce44eb000742480f28b912567fed44568 Mon Sep 17 00:00:00 2001
From: Jim Ramsay <i.am@jimramsay.com>
Date: Sat, 4 Mar 2023 21:24:17 -0500
Subject: [PATCH] Updated documentation for integration tests

Signed-off-by: Jim Ramsay <i.am@jimramsay.com>
---
 CONTRIBUTING.md            | 33 +++++++++++++++++++++++++++++++-
 README.md                  |  3 +--
 test/integration/README.md | 39 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 72 insertions(+), 3 deletions(-)
 create mode 100644 test/integration/README.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 564461b..6fed462 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -140,7 +140,9 @@ static int do_something(int number, const char* text)
 	char e = just_text[1];
 ```
 
-## Unit Tests
+## Testing
+
+### Unit Tests
 
 wayvnc has a small but growing set of unit tests, which are run on every GitHub
 PR. To run them locally, do the following:
@@ -148,6 +150,35 @@ PR. To run them locally, do the following:
 meson test -C build
 ```
 
+### Integration Tests
+
+There are also a handful of integration tests which also run on every PR.  Read
+the [integration tests documentation](test/integration/README.md) for more
+details, but to run them locally:
+```
+./test/integration/integration.sh
+```
+
+### Valgrind
+
+There is a helper script in [util/valgrind.sh](util/valgrind.sh) to aid in
+memory profiling of wayvnc and wayvncctl. This can help find and eliminate
+memory leaks.
+
+### Automated Tests
+
+We run a set of tests on every PR, in three different environments.
+
+Each run ensures that the proposed code change:
+1. Builds successfully
+2. Passes all unit tests
+3. Passes all integration tests
+
+And does so in 3 different environments:
+- Ubuntu as a [github action](.github/workflows/build.yml)
+- Arch Linux as a [sourcehut build](.builds/archlinux.yml)
+- FreeBSD as a [sourcehut build](.builds/freebsd.yaml)
+
 ## No Brown M&Ms
 
 All pull requests must contain the following sentence in the description:
diff --git a/README.md b/README.md
index f0ea925..fa068c2 100644
--- a/README.md
+++ b/README.md
@@ -114,11 +114,10 @@ To run the unit tests:
 meson test -C build
 ```
 
-To run the integration tests:
+To run the [integration tests](test/integration/README.md):
 ```
 ./test/integration/integration.sh
 ```
-The integration tests currently require that sway, lsof, jq, and bash are installed.
 
 ## Running
 Wayvnc can be run from the build directory like so:
diff --git a/test/integration/README.md b/test/integration/README.md
new file mode 100644
index 0000000..5d8c78e
--- /dev/null
+++ b/test/integration/README.md
@@ -0,0 +1,39 @@
+# Integration Testing
+
+## Prerequisites
+
+The integration tests currently require that the following tools are installed:
+- sway (1.8 or later)
+- lsof
+- jq
+- bash
+- vncdotool
+
+Most of these are available in your normal distro package manager, except 
+vncdotool which is a python tool and installable via pip:
+
+```
+pip install vncdotool
+```
+
+## Running
+
+```
+./test/integration/integration.sh
+```
+
+Two test suites are defined:
+
+### Smoke test
+
+Tests basic functionality such as:
+- Can wayvnc start and connect to wayland?
+- Does the wayvncctl IPC mechanism work (both control and events)?
+- Can a VNC client connect and send a keystroke through to sway?
+
+### Multi-output test
+
+Tests wayvnc with a multi-output sway, including:
+- Do we detect additions and removals of outputs?
+- Do the wayvncctl commands to cycle and switch outputs work?
+