From: Stephen Morris Date: Wed, 24 Aug 2016 22:43:31 +0000 (+0100) Subject: [4489] Miscellaneous editing changes to unit test documentation X-Git-Tag: trac4631_base~9^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a0f25b08ac9b9ebe665f76faa18b65e2db361549;p=thirdparty%2Fkea.git [4489] Miscellaneous editing changes to unit test documentation --- diff --git a/doc/devel/unit-tests.dox b/doc/devel/unit-tests.dox index 7801e1448f..59722bf488 100644 --- a/doc/devel/unit-tests.dox +++ b/doc/devel/unit-tests.dox @@ -12,12 +12,13 @@ Kea uses the Google C++ Testing Framework (also called googletest or gtest) as a base for our C++ unit-tests. See http://code.google.com/p/googletest/ for -details. We used to have Python unit-tests that were inherited from BIND10 -days. Those tests are removed now, so please do not develop any new Python -tests in Kea. If you want to write DHCP tests in Python, we encourage you to -take a look at ISC Forge: http://kea.isc.org/wiki/IscForge. You must have \c -gtest installed or at least extracted in a directory before compiling Kea -unit-tests. To enable unit-tests in Kea, use: +details. We used to have Python unit-tests inherited from BIND10 +days but have been removed, so please do not write any new Kea unit +tests in Python. (If you want to write DHCP tests in Python, we encourage you to +take a look at ISC Forge: http://kea.isc.org/wiki/IscForge.) + +You must have \c gtest installed or at least extracted in a directory +before compiling Kea unit-tests. To enable unit-tests in Kea, use: @code ./configure --with-gtest=/path/to/your/gtest/dir @@ -31,41 +32,40 @@ or Depending on how you compiled or installed \c gtest (e.g. from sources or using some package management system) one of those two switches will -find \c gtest. After that you make run unit-tests: +find \c gtest. After that you make and run the unit-tests with: @code make check - @endcode @section unitTestsEnvironmentVariables Environment Variables -The following environment variable can affect unit-tests: +The following environment variable can affect the unit tests: - KEA_LOCKFILE_DIR - Specifies a directory where the logging system should - create its lock file. If not specified, it is prefix/var/run/kea, where prefix - defaults to /usr/local. This variable must not end with a slash. There is one - special value: "none", which instructs Kea to not create lock file at - all. This may cause issues if several processes log to the same file. - Also see Kea User's Guide, section 15.3. - -- KEA_LOGGER_DESTINATION - Specifies logging destination. If not set, logged - messages will not be recorded anywhere. There are 3 special values: + create its lock file. If not specified, it is prefix/var/run/kea, + where prefix defaults to /usr/local. This variable must not end + with a slash. There is one special value, "none", which instructs Kea to + not create a lock file at all. This may cause issues if several processes + log to the same file. (Also see the Kea User's Guide, section 15.3.) + +- KEA_LOGGER_DESTINATION - Specifies the logging destination. If not set, logged + messages will not be recorded anywhere. There are three special values: stdout, stderr and syslog. Any other value is interpreted as a filename. - Also see Kea User's Guide, section 15.3. + (Also see Kea User's Guide, section 15.3.) - KEA_PIDFILE_DIR - Specifies the directory which should be used for PID files - as used by dhcp::Daemon or its derivatives. If not specified, the default is - prefix/var/run/kea, where prefix defaults to /usr/local. This variable must - not end with a slash. + as used by dhcp::Daemon or its derivatives. If not specified, the + default is prefix/var/run/kea, where prefix defaults to + /usr/local. This variable must not end with a slash. - KEA_SOCKET_TEST_DIR - if set, it specifies the directory where Unix - sockets are created. There's OS limitation on how long a Unix socket - path can be. It is typcially slightly over 100 characters. If you - happen to build and run unit-tests in deeply nested directories, this - may become a problem. KEA_SOCKET_TEST_DIR can be specified to instruct - unit-test to use a different directory. Must not end with slash (e.g. - /tmp). + sockets are created. There is an operating system limitation on how + long a Unix socket path can be, typically slightly over 100 + characters. If you happen to build and run unit-tests in deeply nested + directories, this may become a problem. KEA_SOCKET_TEST_DIR can be + specified to instruct unit-test to use a different directory. It must + not end with slash. @section unitTestsDatabaseConfig Databases Configuration for Unit Tests @@ -75,36 +75,29 @@ The following environment variable can affect unit-tests: @subsection unitTestsDatabaseUsers Database Users Required for Unit Tests - Unit tests validating database backends require that keatest database - is created. This database should be empty (should not include any relations). - Unit tests will create required tables for each test case, and drop these tables - when the test case ends. The unit tests also require that keatest user - is created and that this user is configured to access keatest - database with a keatest password. - + Unit tests validating database backends require that the keatest + database is created. This database should be empty. The unit tests + also require that the keatest user is created and that this user + is configured to access the database with a password of keatest. Unit tests use these credentials to create database schema, run test cases and drop the schema. Thus, the keatest user must have sufficiently high privileges to create and drop tables, as well as insert and modify the data within those tables. - The database backends, which support read only access to the host reservations - databases (currently MySQL and PostgreSQL), include unit tests verifying that - a database user, with read-only privileges, can be used to retrieve host - reservations. Those tests require that a user keatest_readonly, with - SQL SELECT privilege to the keatest database (without INSERT, UPDATE etc.), - is also created. + The database backends which support read only access to the host + reservations databases (currently MySQL and PostgreSQL) include unit + tests verifying that a database user with read-only privileges can be + used to retrieve host reservations. Those tests require another user, + keatest_readonly, with SQL SELECT privilege to the keatest + database (i.e. without INSERT, UPDATE etc.), is also created. + keatest_readonly should also have the password keatest. The following sections provide step-by-step guidelines how to setup the databases for running unit tests. @subsection mysqlUnitTestsPrerequisites MySQL Database - A database called keatest must be created. A database user, also called - keatest (and with a password keatest) must also be created and - be given full privileges in that database. The unit tests create the schema - in the database before each test and delete it afterwards. - - In detail, the steps to create the database and user are: + The steps to create the database and users are: -# Log into MySQL as root: @verbatim @@ -117,8 +110,8 @@ The following environment variable can affect unit-tests: mysql> CREATE DATABASE keatest; mysql>@endverbatim\n -# Create the users under which the test client will connect to the database - (the apostrophes around the words keatest and localhost are - required): + (the apostrophes around the words keatest, keatest_readonly, and + localhost are required): @verbatim mysql> CREATE USER 'keatest'@'localhost' IDENTIFIED BY 'keatest'; mysql> CREATE USER 'keatest_readonly'@'localhost' IDENTIFIED BY 'keatest'; @@ -137,27 +130,19 @@ The following environment variable can affect unit-tests: %@endverbatim The unit tests are run automatically when "make check" is executed (providing - that Kea has been build with the \--with-dhcp-mysql switch (see the installation + that Kea has been build with the \c --with-dhcp-mysql switch (see the installation section in the Kea Administrator Reference Manual). @subsection pgsqlUnitTestsPrerequisites PostgreSQL Database - Conceptually, the steps required to run PostgreSQL unit-tests are the same as - in MySQL. First, a database called keatest must be created. A database - user, also called keatest (that will be allowed to log in using password - keatest) must be created and given full privileges in that database. A - database user, called keatest_readonly (using password keatest) - must be created with SELECT privilege on all tables. - The unit tests create the schema in the database before each test and delete it - afterwards. - - PostgreSQL set up differs from system to system. Please consult your OS-specific - PostgreSQL documentation. The remainder of that section uses Ubuntu 13.10 x64 - (with PostgreSQL 9.0+) as an example. On Ubuntu, after installing PostgreSQL - (with sudo apt-get install postgresql), it is installed as user - postgres. To create new databases or add new users, initial commands - must be issued as user postgres: + PostgreSQL set up differs from system to system. Please consult your + operating system-specific PostgreSQL documentation. The remainder of + that section uses Ubuntu 13.10 x64 (with PostgreSQL 9.0+) as an example. + + On Ubuntu, PostgreSQL is installed (with sudo apt-get install + postgresql) under user postgres. To create new databases + or add new users, initial commands must be issued under this username: @verbatim $ sudo -u postgres psql postgres @@ -180,10 +165,10 @@ postgres=# \q To ensure that the user has specific privileges to tables dynamically created by the unit tests, the default schema privileges must be altered. - The following example demonstrates how to create user keatest_readonly, + The following example demonstrates how to create the user keatest_readonly, which has SELECT privilege to the tables within the keatest database, in Postgres 9.0+. For earlier versions of Postgres, it is recommended to - simply grant full privileges to keatest_readonly user, using the + simply grant full privileges to keatest_readonly, using the same steps as for the keatest user. @verbatim @@ -206,7 +191,7 @@ ALTER DEFAULT PRIVILEGES keatest=> \q @endverbatim - Note that keatest user (rather than postgres) is used to grant + Note that the keatest user (rather than postgres) is used to grant privileges to the keatest_readonly user. This ensures that the SELECT privilege is granted only on the tables that the keatest user can access within the public schema. @@ -229,12 +214,12 @@ Type "help" for help. keatest=> @endverbatim - If instead of seeing keatest=> prompt, your login will be refused with error + If instead of seeing keatest=> prompt, your login is refused with an error code about failed peer or indent authentication, it means that PostgreSQL is - configured to check unix username and reject login attepts if PostgreSQL names - are different. To alter that, PostgreSQL configuration must be changed. - /etc/postgresql/9.1/main/pg_hba.conf config file - has to be tweaked. It may be in a different location in your system. The following + configured to check unix username and reject login attempts if PostgreSQL names + are different. To alter that, the PostgreSQL configuration must be changed - + the /etc/postgresql/9.1/main/pg_hba.conf config file + has to be altered. (It may be in a different location in your system.) The following lines: @verbatim @@ -243,7 +228,7 @@ host all all 127.0.0.1/32 md5 host all all ::1/128 md5 @endverbatim - were replaced with: +need to be replaced with: @verbatim local all all password @@ -251,12 +236,14 @@ host all all 127.0.0.1/32 password host all all ::1/128 password @endverbatim - Another possible problem is to get no password prompt, in general because - you have no pg_hba.conf config file and everybody is by default - trusted. As it has a very bad effect on the security you should have - been warned it is a highly unsafe config. The solution is the same, - i.e., require password or md5 authentication method. If you lose - the postgres user access you can add first: + Another possible problem is that you get no password prompt. This is + most probably because you have no pg_hba.conf config file + and everybody is by default trusted. As it has a very bad effect + on the security you should have been warned this is a highly unsafe + configuration. The solution is the same, i.e., require password or + md5 authentication method. + + If you lose the postgres user access you can first add: @verbatim local all postgres trust @endverbatim @@ -269,7 +256,7 @@ local all postgres trust that runs tests. Use caution! The unit tests are run automatically when "make check" is executed (providing - that Kea has been build with the \--with-dhcp-pgsql switch (see the installation + that Kea has been build with the \c --with-dhcp-pgsql switch (see the installation section in the Kea Administrator Reference Manual).