Document how to run the e2e tests with docker, locally

1 files changed, 60 insertions, 0 deletions

diff --git a/doc/developer.rst b/doc/developer.rst
index 49daa5c..9b6fb3d 100644
--- a/doc/developer.rst
+++ b/doc/developer.rst
@@ -27,6 +27,66 @@ A scenario is a list of functions that will be executed one by one, to
 verify the behaviour of one specific feature. Ideally, they should be
 short and test one specific aspect.
 
+Run the test suite locally
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since this requires a lot of dependencies (an IRC server with some TLS
+certificate, slixmpp, many libraries…), it might be cumbersome to get
+everything on your machine to be able to run them.
+
+The simplest solution (as long as you have docker installed and properly
+configured to be able to run as your developer user…) is to follow these
+instructions:
+
+.. code-block:: bash
+  :caption: Start a docker container with everything installed
+
+  docker run --name biboumi-e2e -v /home/louiz/biboumi/:/home/tester/biboumi \
+             --add-host="irc.localhost:127.0.0.1" \
+             --add-host="biboumi.localhost:127.0.0.1" \
+             --rm -it docker.louiz.org/louiz/biboumi/test-alpine \
+             /bin/bash
+
+This creates a container where every dependency is already installed. We
+mount your working directory inside the container: be sure to modify the
+first path `/home/louiz/biboumi` with your own. The hosts that we add are
+needed for the test suite to properly work.
+
+You can use the test-fedora or test-debian images instead of test-alpine
+if you want, but it should not change anything (even if your host machine
+uses debian or fedora), alpine is just the lighter one.
+
+.. note::
+
+  This container should stay alive as long as you want to run the test
+  suite. For example if you want to run it many times until your code is
+  fine and all tests pass, just leave that shell somewhere without
+  touching it.
+
+Then, from an other shell (do NOT run that inside the container we just
+created):
+
+.. code-block:: bash
+  :caption: Configure and build biboumi from inside the container
+
+  docker exec biboumi-e2e sh -c "cd biboumi && mkdir build && cmake .."
+
+This is needed (only once), because if you configure it from your host
+machine, then the paths generated by cmake will be all wrong when you try
+to compile from inside the container and nothing will work.
+
+.. code-block:: bash
+  :caption: Re-compile and run the test suite inside the container
+
+  docker exec biboumi-e2e sh -c "cd biboumi/build && make e2e"
+
+This should now build everything correctly, and run the test suite. If you
+want to re-run it again after you edited something in your source tree,
+just run this last command again. You don’t need to touch anything inside
+the container again.
+
+When you’re done, just close the shell we opened with the first command.
+
 Available functions
 ~~~~~~~~~~~~~~~~~~~