Testing

The majority of Pyrseas' capabilities are exercised and verified via unit tests written using pytest. The tests can be run from the command line by most users, e.g.,

pytest-3 tests/dbobject/test_table.py
pytest-3 tests/dbobject/test_trigger.py -k test_create_trigger
pytest-3 tests/functional

The first pytest-3 command above runs all tests related to tables, mapping, creating, dropping, etc. The second one executes a single test to generate SQL to create a trigger. The third runs all the functional tests. Please review the pytest documentation for further options.

Environment Variables

By default, the tests use a Postgres database named pyrseas_testdb which is created if it doesn't already exist. The tests are run as the logged in user, using the USER Unix/Linux environment variable (or USERNAME under Windows). They access Postgres on the local host using the default port number (5432).

The following four environment variables can be used to change the defaults described above:

  • PYRSEAS_TEST_DB
  • PYRSEAS_TEST_USER
  • PYRSEAS_TEST_HOST
  • PYRSEAS_TEST_PORT

Restrictions

Unless the test database exists and the user running the tests has access to it, the user role will need CREATEDB privilege.

Most tests do not require special privileges. However, certain tests may require Postgres SUPERUSER privilege. Such tests will normally be skipped if the user lacks the privilege.

Most tests do not require installation of supporting Postgres packages. However, a few tests rely on the availability of Postgres contrib modules such as the spi module or procedural languages such as plperl or plpython3u.

On Windows, it is necessary to install Perl in order to run some of the tests (most Linux or Unix variants already include it as part of their normal distribution). The last time we checked, a suitable choice appeared to be Strawberry Perl which can be downloaded from http://strawberryperl.com/releases.html. However, the default installation is placed in C:\strawberry and can hold a single Perl version. Furthermore, some Postgres versions may be linked with non-current Perl versions. It is recommended that the latest Perl version be installed as this will usually give the fewest test failures. See this blog post for more details.

The COLLATION tests require the fr_FR.utf8 locale (or French.France.1252 language on Windows) to be installed.

Testing Checklist

The following is a summary list of steps needed to test Pyrseas on a new machine. Refer to development for details on how to accomplish a given installation task. "Package manager" refers to the platform's package management system utility such as apt-get or yum. Installation from PyPI can be done with pip. Some operations require administrative or superuser privileges, at either the operating system or Postgres level.

  • Install Git using package manager or from https://git-scm.com/download (on Windows, prefer Git Bash)

  • git clone git://github.com/perseas/Pyrseas.git

  • Install Python 3.7 or higher, using package manager or from installers at https://www.python.org/downloads/.

  • Install Postgres 13, 12, 11 or 10, using package manager or binary installers at https://www.postgresql.org/download/

    Note

    On Linux, make sure you install the contrib and plperl packages, e.g., on Debian, postgresql-contrib-n and postgresql-plperl-n (where n is the Postgres version number)

  • Install Psycopg, using package manager, or from PyPI (https://pypi.org/project/psycopg/).

    Note

    On Windows, you may first want to install a version of Microsoft Visual Studio from here. An alternative that may work is MinGW. See these blog posts for more details.

  • Install PyYAML, using package manager, or from PyPI (https://pypi.org/project/PyYAML/) or http://pyyaml.org/download/pyyaml/.

  • Install pytest, using package manager, or from PyPI (https://pypi.org/project/pytest/).

  • Install Tox, using package manager, or from PyPI (https://pypi.org/project/tox/)

  • On Windows, install Perl (see discussion above under "Restrictions"). On Linux, usually Perl is already available.

  • As postgres user, using psql or pgAdmin, create a test user, e.g., your name. The user running tests must have at a minimum createdb privilege, in order to create the test database. To run all the tests, the user also needs superuser privilege.

  • Create a Postgres password file, e.g., on Linux: ~/.pgpass, on Windows: %APPDATA%\postgresql\pgpass.conf.

  • Create directories to hold tablespaces, e.g., /extra/pg/13.0/ts1 on Linux, C:\\extra\\pg\\13.0\\ts1 on Windows. The directories need to be owned by the postgres user. This may be tricky on older Windows versions, but the command cacls <dir> /E /G postgres:F should suffice. Using psql, create tablespaces ts1 and ts2, e.g., CREATE TABLESPACE ts1 LOCATION '<directory>' (on Windows, you'll have to use, e.g., E'C:\\dir\\ts1', to specify the directory).

  • Install the locale fr_FR.utf8 on Linux/Unix or the language French.France.1252 on Windows.

    • On Debian and derivatives, this can be done with the command:

      sudo dpkg-reconfigure locales

    • On Windows, open the Control Panel, select Date, Time, Language, and Regional Options, then Regional and Language Options (or Add other languages), click on the Advanced tab in the dialog and then choose “French (France)” from the dropdown. Finally, click OK and respond to any subsequent prompts to install the locale, including rebooting the machine.

  • Change to the Pyrseas source directory (created by the second step above).

    • Define the PYTHONPATH environment variable to the Pyrseas source directory, e.g., on Linux, export PYTHONPATH=$PWD, on Windows, set PYTHONPATH=%USERPROFILE%\somedir\Pyrseas.
    • Define the environment variables PG100_PORT, PG110_PORT, PG120_PORT and PG130_PORT to point to the corresponding Postgres connection ports.

  • Invoke tox. This will create virtualenvs in a .tox subdirectory, install Pyrseas and its prerequisites (Psycopg and PyYAML) into each virtualenv and run the unit tests for each combination of Postgres and Python.

If you find any problems with the instructions above, please open an issue on GitHub.