unit-tests.dox 10.8 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13
// Copyright (C) 2015-2016 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.

/**

 @page unitTests Building Kea with Unit Tests

@section unitTestsIntroduction Introduction

Kea uses the Google C++ Testing Framework (also called googletest or gtest) as a
14
base for our C++ unit-tests. See https://github.com/google/googletest for
15 16
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
17
tests in Python. If you want to write DHCP tests in Python, we encourage you to
18
take a look at ISC Forge: http://oldkea.isc.org/wiki/IscForge .
19 20 21

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:
22 23 24 25 26 27 28 29 30 31 32 33 34

@code
./configure --with-gtest=/path/to/your/gtest/dir
@endcode

or

@code
./configure --with-gtest-source=/path/to/your/gtest/dir
@endcode

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
35
find \c gtest. After that you make and run the unit-tests with:
36 37 38 39 40 41 42

@code
make check
@endcode

@section unitTestsEnvironmentVariables Environment Variables

43
The following environment variable can affect the unit tests:
44 45

- KEA_LOCKFILE_DIR - Specifies a directory where the logging system should
46 47 48 49 50 51 52 53
  create its lock file. If not specified, it is <i>prefix</i>/var/run/kea,
  where <i>prefix</i> 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:
54
  stdout, stderr and syslog. Any other value is interpreted as a filename.
55
  (Also see Kea User's Guide, section 15.3.)
56 57

- KEA_PIDFILE_DIR - Specifies the directory which should be used for PID files
58 59 60
  as used by dhcp::Daemon or its derivatives. If not specified, the
  default is <i>prefix</i>/var/run/kea, where <i>prefix</i> defaults to
  /usr/local. This variable must not end with a slash.
61 62

- KEA_SOCKET_TEST_DIR - if set, it specifies the directory where Unix
63 64 65 66 67 68
  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.
69 70 71 72 73 74 75 76 77

@section unitTestsDatabaseConfig Databases Configuration for Unit Tests

  With the use of databases requiring separate authorisation, there are
  certain database-specific pre-requisites for successfully running the unit
  tests.  These are listed in the following sections.

  @subsection unitTestsDatabaseUsers Database Users Required for Unit Tests

78 79 80 81
  Unit tests validating database backends require that the <i>keatest</i>
  database is created. This database should be empty.  The unit tests
  also require that the <i>keatest</i> user is created and that this user
  is configured to access the database with a password of <i>keatest</i>.
82 83 84 85 86
  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.

87 88 89 90 91 92 93
  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,
  <i>keatest_readonly</i>, with SQL SELECT privilege to the <i>keatest</i>
  database (i.e. without INSERT, UPDATE etc.), is also created.
  <i>keatest_readonly</i> should also have the password <i>keatest</i>.
94 95 96 97 98 99

  The following sections provide step-by-step guidelines how to setup the
  databases for running unit tests.

  @subsection mysqlUnitTestsPrerequisites MySQL Database

100
  The steps to create the database and users are:
101 102 103 104 105 106 107 108 109 110 111 112

  -# Log into MySQL as root:
  @verbatim
  % mysql -u root -p
  Enter password:
     :
  mysql>@endverbatim\n
  -# Create the test database.  This must be called "keatest":
  @verbatim
  mysql> CREATE DATABASE keatest;
  mysql>@endverbatim\n
  -# Create the users under which the test client will connect to the database
113 114
  (the apostrophes around the words <i>keatest</i>, <i>keatest_readonly</i>, and
   <i>localhost</i> are required):
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
  @verbatim
  mysql> CREATE USER 'keatest'@'localhost' IDENTIFIED BY 'keatest';
  mysql> CREATE USER 'keatest_readonly'@'localhost' IDENTIFIED BY 'keatest';
  mysql>@endverbatim\n
  -# Grant the created users permissions to access the <i>keatest</i> database
  (again, the apostrophes around the user names and <i>localhost</i>
  are required):
  @verbatim
  mysql> GRANT ALL ON keatest.* TO 'keatest'@'localhost';
  mysql> GRANT SELECT ON keatest.* TO 'keatest_readonly'@'localhost';
  mysql>@endverbatim\n
  -# Exit MySQL:
  @verbatim
  mysql> quit
  Bye
  %@endverbatim

  The unit tests are run automatically when "make check" is executed (providing
133
  that Kea has been build with the \c --with-mysql switch (see the installation
134
  section in the <a href="http://oldkea.isc.org/docs/kea-guide.html">Kea Administrator
135 136 137 138
  Reference Manual</a>).

 @subsection pgsqlUnitTestsPrerequisites PostgreSQL Database

139 140 141 142 143 144 145
  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 <tt>sudo apt-get install
  postgresql</tt>) under user <i>postgres</i>. To create new databases
  or add new users, initial commands must be issued under this username:
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167

@verbatim
$ sudo -u postgres psql postgres
[sudo] password for thomson:
psql (9.1.12)
Type "help" for help.
postgres=# CREATE USER keatest WITH PASSWORD 'keatest';
CREATE ROLE
postgres=# CREATE DATABASE keatest;
CREATE DATABASE
postgres=# GRANT ALL PRIVILEGES ON DATABASE keatest TO keatest;
GRANT
postgres=# \q
@endverbatim

  PostgreSQL versions earlier than 9.0 don't provide an SQL statement for granting
  privileges on all tables in a database. In newer PostgreSQL versions, it is
  possible to grant specific privileges on all tables within a schema.
  However, this only affects tables which exist when the privileges are granted.
  To ensure that the user has specific privileges to tables dynamically created
  by the unit tests, the default schema privileges must be altered.

168
  The following example demonstrates how to create the user <i>keatest_readonly</i>,
169 170
  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
171
  simply grant full privileges to <i>keatest_readonly</i>, using the
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188
  same steps as for the <i>keatest</i> user.

@verbatim
$ psql -U postgres
Password for user postgres:
psql (9.1.12)
Type "help" for help.

postgres=# CREATE USER keatest_readonly WITH PASSWORD 'keatest';
CREATE ROLE
postgres=# \q

$ psql -U keatest
Password for user keatest:
psql (9.1.12)
Type "help" for help.

189
keatest=> ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES to keatest_readonly;
190 191 192 193
ALTER DEFAULT PRIVILEGES
keatest=> \q
@endverbatim

194
  Note that the <i>keatest</i> user (rather than <i>postgres</i>) is used to grant
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216
  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.

  Now we  should be able to log into the newly created database using both user
  names:
@verbatim
$ psql -d keatest -U keatest
Password for user keatest:
psql (9.1.12)
Type "help" for help.

keatest=> \q

$ psql -d keatest -U keatest_readonly
Password for user keatest_readonly:
psql (9.1.12)
Type "help" for help.

keatest=>
@endverbatim

217
  If instead of seeing keatest=> prompt, your login is refused with an error
218
  code about failed peer or indent authentication, it means that PostgreSQL is
219 220 221 222
  configured to check unix username and reject login attempts if PostgreSQL names
  are different. To alter that, the PostgreSQL configuration must be changed -
  the <tt>/etc/postgresql/9.1/main/pg_hba.conf</tt> config file
  has to be altered. (It may be in a different location in your system.) The following
223 224 225 226 227 228 229 230
  lines:

@verbatim
local   all             all                                     peer
host    all             all             127.0.0.1/32            md5
host    all             all             ::1/128                 md5
@endverbatim

231
need to be replaced with:
232 233 234 235 236 237 238

@verbatim
local   all             all                                     password
host    all             all             127.0.0.1/32            password
host    all             all             ::1/128                 password
@endverbatim

239 240 241 242 243 244 245 246
  Another possible problem is that you get no password prompt. This is
  most probably because you have no <tt>pg_hba.conf</tt> 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:
247 248 249 250 251 252 253 254 255 256 257 258
@verbatim
local   all             postgres                                trust
@endverbatim
  to trust only the local postgres user. Note the postgres user can
  be pgsql on some systems.

  Please consult your PostgreSQL user manual before applying those changes as
  those changes may expose your other databases that you run on the same system.
  In general case, it is a poor idea to run anything of value on a system
  that runs tests. Use caution!

  The unit tests are run automatically when "make check" is executed (providing
259
  that Kea has been build with the \c --with-pgsql switch (see the installation
260
  section in the <a href="http://oldkea.isc.org/docs/kea-guide.html">Kea Administrator
261 262 263
  Reference Manual</a>).


264 265
 @subsection cqlUnitTestsPrerequisites Cassandra database

266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285
 @todo: Describe steps necessary to set up Cassandra database suitable
 for running unittests.

 It seems this was enough:

 -# Launch cassandra if not running (-f for foreground)
 @verbatim
 % cassandra -f
 @endverbatim

 The tool is cqlsh:

 -# Run the tool
 @verbatim
 % cqlsh
 Connected to Test Cluster at 127.0.0.1:9042.
 [cqlsh 5.0.1 | Cassandra 3.11.1 | CQL spec 3.4.4 | Native protocol v4]
 Use HELP for help.
 cqlsh> @endverbatim\n
 
286
 */