Skip to content

Commit

Permalink
Improve docs on how to run tests (#873)
Browse files Browse the repository at this point in the history
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).
  • Loading branch information
JelteF committed Jun 15, 2023
1 parent 8ec53d2 commit 1f70d25
Show file tree
Hide file tree
Showing 3 changed files with 77 additions and 46 deletions.
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -29,4 +29,6 @@
*.exe
*.gz
*.swp
env
venv
.venv
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------------------

Expand Down
114 changes: 68 additions & 46 deletions test/README.md
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit 1f70d25

Please sign in to comment.