diff --git a/.gitignore b/.gitignore index 5d32766e0e47..c06e4aff703e 100644 --- a/.gitignore +++ b/.gitignore @@ -29,4 +29,6 @@ *.exe *.gz *.swp +env +venv .venv diff --git a/README.md b/README.md index 67a46abfe797..3db76d764ac4 100644 --- a/README.md +++ b/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 ------------------- diff --git a/test/README.md b/test/README.md index e783b40d17ed..15eb9f867225 100644 --- a/test/README.md +++ b/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.