split CREATE USER and GRANT (Mantis#1727)
[racktables] / tests / README.md
1 # This directory stores PHPUnit tests.
2
3 To run a specific test:
4 ```
5 $ phpunit TestName
6 ```
7
8 To run all small tests (several seconds to complete):
9 ```
10 $ phpunit --group small
11 ```
12
13 To run all tests (several minutes to complete):
14 ```
15 $ phpunit
16 ```
17
18 ## The Unit Testing Database
19
20 Tests should never be run against a production instance of RackTables.
21
22 The `bootstrap.php` script (configured for use in `phpunit.xml`) calls
23 method `TestHelper::ensureUsingUnitTestDatabase()` to check that the
24 database DSN contains the string "_unittest".
25
26 Checking the DSN is a relatively easy way to ensure that tests are
27 only run with a dedicated testing database. While PHPUnit supports
28 [Database_TestCases](https://phpunit.de/manual/current/en/database.html),
29 the RackTables tests do not yet use that framework. This may be
30 incorporated at a future date.
31
32
33 ## Creating and configuring a Unit Testing Database
34
35 Assuming you have installed your development RackTables using the web
36 interface, you will already have a working database. You can clone
37 that database to a new dedicated unit testing database (where the
38 database name contains the string "_unittest") from the command line.
39 Note that you should use the `$db_username` variable contained in
40 `wwwroot/inc/secret.php` instead of "racktables_user".
41
42 ```
43 mysql -u root -p
44 CREATE DATABASE racktables_unittest CHARACTER SET utf8 COLLATE utf8_general_ci;
45 CREATE USER IF NOT EXISTS racktables_user@localhost IDENTIFIED BY 'MY_SECRET_PASSWORD';
46 GRANT ALL PRIVILEGES ON racktables_unittest.* TO racktables_user@localhost;
47 exit
48 ```
49
50 Then duplicate the existing database to your new unit testing database:
51
52 ```
53 mysqldump -u racktables_user -p MY_SECRET_PASSWORD racktables_db | \
54 mysql -u racktables_user -p MY_SECRET_PASSWORD racktables_unittest
55 ```
56
57 Edit the `secret.php` file and change the dbname in `$pdo_dsn` to the new
58 "_unittest" database, e.g.:
59 ```
60 $pdo_dsn = 'mysql:host=127.0.0.1;dbname=racktables_unittest';
61 ```
62 To switch to another database, edit the `secret.php` file.