Improve docs on how to run tests (#873)

Multiple new contributors had problems running tests locally. I guess
I'm used to Python its objectively bad dependency story, so it wasn't
much of a problem for me. This structures the testing docs a bit better
and also starts linking to them from the README.

It also adds an explanation on how to set up a virtual environment
(which would have solved one problem a contributor had).

.gitignore

@@ -29,4 +29,6 @@
 *.exe
 *.gz
 *.swp
+env
+venv
 .venv

README.md

@@ -100,6 +100,13 @@ you can run `configure`:
 
 Additional packages required: autoconf, automake, libtool, pandoc
 
+Testing
+-------
+
+See the [`README.md` file in the test directory][1] on how to run the tests.
+
+[1]: https://github.com/pgbouncer/pgbouncer/blob/master/test/README.md
+
 Building on Windows
 -------------------
 

test/README.md

@@ -1,70 +1,92 @@
 Tests
 =====
 
-Various ways to test PgBouncer:
+## Setting up Python dependencies for testing
 
-- `test_xxx.py`
+To be able to run most of the tests you need to install a few python tools.  To
+do so, you should run the following from of the root of the repository:
 
-    General test of basic functionality and different configuration
-    parameters including timeouts, pool size, online restart,
-    pause/resume, etc.
+```bash
+pip3 install --user -r requirements.txt
+```
 
-    To be able to run these tests you need to install a few python test
-    libraries.  To do so, you should run the following from of the root of the
-    repository:
+This will install the packages globally on your system, if you don't want to do
+that (or if tests are still not working after the above command) you can use a
+[virtual environment][1] instead:
+```bash
+# create a virtual environment (only needed once)
+python3 -m venv env
 
-    pip3 install --user -r requirements.txt
+# activate the environment. You will need to activate this environment in
+# your shell every time you want to run the tests. (so needed once per
+# shell).
+source env/bin/activate
 
-    To run the tests after doing that, just run `pytest -n auto` from the root
-    of the repository.  This needs PostgreSQL server programs (`initdb`,
-    `pg_ctl`) in the path, so if you are on a system that doesn't have those in
-    the normal path (e.g., Debian, Ubuntu), set `PATH` beforehand.
+# Install the dependencies (only needed once, or whenever extra dependencies
+# get added to requirements.txt)
+pip install -r requirements.txt
+```
 
-    Optionally, this test suite can use `iptables`/`pfctl` to simulate
-    various network conditions.  To include these tests, set the
-    environment variable USE_SUDO to a nonempty value, for example
-    `make check USE_SUDO=1`.  This will ask for sudo access, so it
-    might convenient to run `sudo -v` before the test, or set up
-    `/etc/sudoers` appropriately at your peril.  Check the source if
-    there are any doubts.
+[1]: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
 
-    This test is run by `make check`.
 
-    You can review the pytest docs on how to run tests with pytest, but the most
-    common commands that you'll want to use are:
+## Various ways to test PgBouncer
 
-    ```bash
-    # Run all tests in parallel
-    pytest -n auto
+### `test_xxx.py`
 
-    # Run all tests sequentially
-    pytest
+These are general tests of basic functionality and different configuration
+parameters including timeouts, pool size, online restart, pause/resume, etc.
 
-    # Run a specific test
-    pytest test/test_limits.py::test_max_user_connections
+You can run these tests using `pytest -n auto` from the root of the repository
+(after installing the python dependencies as explained above). This needs
+PostgreSQL server programs (`initdb`, `pg_ctl`) in the path, so if you are on a
+system that doesn't have those in the normal path (e.g., Debian, Ubuntu), set
+`PATH` beforehand.
 
-    # Run a specific test file in parallel
-    pytest -n auto test/test_limits.py
+Optionally, this test suite can use `iptables`/`pfctl` to simulate various
+network conditions.  To include these tests, set the environment variable
+USE_SUDO to a nonempty value, for example `make check USE_SUDO=1`.  This will
+ask for sudo access, so it might convenient to run `sudo -v` before the test, or
+set up `/etc/sudoers` appropriately at your peril.  Check the source if there
+are any doubts.
 
-    # Run any test that contains a certain string in the name
-    pytest -k ssl
-    ```
+This test is run by `make check`.
 
+You can review the pytest docs on how to run tests with pytest, but the most
+common commands that you'll want to use are:
 
-- `hba_test`
+```bash
+# Run all tests in parallel
+pytest -n auto
 
-    Tests hba parsing.  Run `make all` to build and `./hba_test` to execute.
+# Run all tests sequentially
+pytest
 
-    This test is run by `make check`.
+# Run a specific test
+pytest test/test_limits.py::test_max_user_connections
 
-- `run-conntest.sh`
+# Run a specific test file in parallel
+pytest -n auto test/test_limits.py
 
-    This is a more complex setup that continuously runs queries
-    through PgBouncer while messing around with the network, checking
-    whether PgBouncer correctly reconnects and all the queries get
-    processed.  First, run `make asynctest` to build, then see
-    `run-conntest.sh` how to run the different pieces.
+# Run any test that contains a certain string in the name
+pytest -k ssl
+```
 
-- `stress.py`
 
-    Stress test, see source for details.  Requires Python and `psycopg2` module.
+### `hba_test`
+
+Tests hba parsing.  Run `make all` to build and `./hba_test` to execute.
+
+This test is run by `make check`.
+
+
+### `run-conntest.sh`
+
+This is a more complex setup that continuously runs queries through PgBouncer
+while messing around with the network, checking whether PgBouncer correctly
+reconnects and all the queries get processed.  First, run `make asynctest`
+to build, then see `run-conntest.sh` how to run the different pieces.
+
+### `stress.py`
+
+Stress test, see source for details.  Requires Python and `psycopg2` module.