[4489] Miscellaneous editing changes to unit test documentation

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
+details. We used to have Python unit-tests inherited from BIND10
-days. Those tests are removed now, so please do not develop any new Python
+days but have been removed, so please do not write any new Kea unit
-tests in Kea. If you want to write DHCP tests in Python, we encourage you to
+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
+take a look at ISC Forge: http://kea.isc.org/wiki/IscForge.)
-gtest installed or at least extracted in a directory before compiling Kea
+
-unit-tests. To enable unit-tests in Kea, use:
+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
+  create its lock file. If not specified, it is <i>prefix</i>/var/run/kea,
-  defaults to /usr/local. This variable must not end with a slash. There is one
+  where <i>prefix</i> defaults to /usr/local. This variable must not end
-  special value: "none", which instructs Kea to not create lock file at
+  with a slash. There is one special value, "none", which instructs Kea to
-  all. This may cause issues if several processes log to the same file.
+  not create a lock file at all. This may cause issues if several processes
-  Also see Kea User's Guide, section 15.3.
+  log to the same file.  (Also see the Kea User's Guide, section 15.3.)
 
-- KEA_LOGGER_DESTINATION - Specifies logging destination. If not set, logged
+- KEA_LOGGER_DESTINATION - Specifies the logging destination. If not set, logged
-  messages will not be recorded anywhere. There are 3 special values:
+  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
+  as used by dhcp::Daemon or its derivatives. If not specified, the
-  prefix/var/run/kea, where prefix defaults to /usr/local. This variable must
+  default is <i>prefix</i>/var/run/kea, where <i>prefix</i> defaults to
-  not end with a slash.
+  /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
+  sockets are created. There is an operating system limitation on how
-  path can be. It is typcially slightly over 100 characters. If you
+  long a Unix socket path can be, typically slightly over 100
-  happen to build and run unit-tests in deeply nested directories, this
+  characters. If you happen to build and run unit-tests in deeply nested
-  may become a problem. KEA_SOCKET_TEST_DIR can be specified to instruct
+  directories, this may become a problem. KEA_SOCKET_TEST_DIR can be
-  unit-test to use a different directory. Must not end with slash (e.g.
+  specified to instruct unit-test to use a different directory. It must
-  /tmp).
+  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 <i>keatest</i> database
+  Unit tests validating database backends require that the <i>keatest</i>
-  is created. This database should be empty (should not include any relations).
+  database is created. This database should be empty.  The unit tests
-  Unit tests will create required tables for each test case, and drop these tables
+  also require that the <i>keatest</i> user is created and that this user
-  when the test case ends. The unit tests also require that <i>keatest</i> user
+  is configured to access the database with a password of <i>keatest</i>.
-  is created and that this user is configured to access <i>keatest</i>
-  database with a <i>keatest</i> password.
-
   Unit tests use these credentials to create database schema, run test cases
   and drop the schema. Thus, the <i>keatest</i> 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
+  The database backends which support read only access to the host
-  databases (currently MySQL and PostgreSQL), include unit tests verifying that
+  reservations databases (currently MySQL and PostgreSQL) include unit
-  a database user, with read-only privileges, can be used to retrieve host
+  tests verifying that a database user with read-only privileges can be
-  reservations. Those tests require that a user <i>keatest_readonly</i>, with
+  used to retrieve host reservations. Those tests require another user,
-  SQL SELECT privilege to the <i>keatest</i> database (without INSERT, UPDATE etc.),
+  <i>keatest_readonly</i>, with SQL SELECT privilege to the <i>keatest</i>
-  is also created.
+  database (i.e. without INSERT, UPDATE etc.), is also created.
+  <i>keatest_readonly</i> should also have the password <i>keatest</i>.
 
   The following sections provide step-by-step guidelines how to setup the
   databases for running unit tests.
 
   @subsection mysqlUnitTestsPrerequisites MySQL Database
 
-  A database called <i>keatest</i> must be created. A database user, also called
+  The steps to create the database and users are:
-  <i>keatest</i> (and with a password <i>keatest</i>) 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:
 
   -# 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 <i>keatest</i> and <i>localhost</i> are
+  (the apostrophes around the words <i>keatest</i>, <i>keatest_readonly</i>, and
-  required):
+   <i>localhost</i> 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 <a href="http://kea.isc.org/docs/kea-guide.html">Kea Administrator
   Reference Manual</a>).
 
  @subsection pgsqlUnitTestsPrerequisites PostgreSQL Database
 
-  Conceptually, the steps required to run PostgreSQL unit-tests are the same as
+  PostgreSQL set up differs from system to system. Please consult your
-  in MySQL. First, a database called <i>keatest</i> must be created. A database
+  operating system-specific PostgreSQL documentation. The remainder of
-  user, also called <i>keatest</i> (that will be allowed to log in using password
+  that section uses Ubuntu 13.10 x64 (with PostgreSQL 9.0+) as an example.
-  <i>keatest</i>) must be created and given full privileges in that database. A
-  database user, called <i>keatest_readonly</i> (using password <i>keatest</i>)
-  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
+  On Ubuntu, PostgreSQL is installed (with <tt>sudo apt-get install
-  PostgreSQL documentation. The remainder of that section uses Ubuntu 13.10 x64
+  postgresql</tt>) under user <i>postgres</i>. To create new databases
-  (with PostgreSQL 9.0+) as an example. On Ubuntu, after installing PostgreSQL
+  or add new users, initial commands must be issued under this username:
-  (with <tt>sudo apt-get install postgresql</tt>), it is installed as user
-  <i>postgres</i>. To create new databases or add new users, initial commands
-  must be issued as user postgres:
 
 @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 <i>keatest_readonly</i>,
+  The following example demonstrates how to create the user <i>keatest_readonly</i>,
   which has SELECT privilege to the tables within the <i>keatest</i> database,
   in Postgres 9.0+. For earlier versions of Postgres, it is recommended to
-  simply grant full privileges to <i>keatest_readonly</i> user, using the
+  simply grant full privileges to <i>keatest_readonly</i>, using the
   same steps as for the <i>keatest</i> user.
 
 @verbatim
@@ -206,7 +191,7 @@ ALTER DEFAULT PRIVILEGES
 keatest=> \q
 @endverbatim
 
-  Note that <i>keatest</i> user (rather than <i>postgres</i>) is used to grant
+  Note that the <i>keatest</i> user (rather than <i>postgres</i>) is used to grant
   privileges to the <i>keatest_readonly</i> user. This ensures that the SELECT
   privilege is granted only on the tables that the <i>keatest</i> 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
+  configured to check unix username and reject login attempts if PostgreSQL names
-  are different. To alter that, PostgreSQL configuration must be changed.
+  are different. To alter that, the PostgreSQL configuration must be changed -
-  <tt>/etc/postgresql/9.1/main/pg_hba.conf</tt> config file
+  the <tt>/etc/postgresql/9.1/main/pg_hba.conf</tt> config file
-  has to be tweaked. It may be in a different location in your system. The following
+  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
+  Another possible problem is that you get no password prompt. This is
-  you have no <tt>pg_hba.conf</tt> config file and everybody is by default
+  most probably because you have no <tt>pg_hba.conf</tt> config file
-  trusted. As it has a very bad effect on the security you should have
+  and everybody is by default trusted. As it has a very bad effect
-  been warned it is a highly unsafe config. The solution is the same,
+  on the security you should have been warned this is a highly unsafe
-  i.e., require password or md5 authentication method. If you lose
+  configuration. The solution is the same, i.e., require password or
-  the postgres user access you can add first:
+  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 <a href="http://kea.isc.org/docs/kea-guide.html">Kea Administrator
   Reference Manual</a>).