Latest revision as of 03:18, 30 August 2021

This is mostly for automated back-end testing. For automated testing of front-end or UI components, see Using Qunit for testing JS.

Configuring The Test Database

In early 2015 we made a separate set of config files for using with automated tests, so that they could run against a separate database and not pollute the server's primary database. These are the steps that need to be taken in order to configure a server for running the automated test suite.

Directory For Test Configs

First, you need to make sure the local test directory exists on your server. Then, if you haven't done so already, copy the default test config files to the local test directory. (If you have a Dreamhack, this may have been done for you.)

cd $LJHOME
mkdir -p ext/local/t
cp t/config-test-private.pl ext/local/t/config-test-private.pl 
cp t/config-test.pl ext/local/t/config-test.pl 

config-test-private.pl

Once you have a local copy of config-test-private.pl in the right place, edit it to include the correct connection info and password for your testing database. If you are using a dreamhack, the database should be named test_dreamhack_<username>, the username will be dh_<yourusername> and the password is likely the same password that was assigned to the dreamhack_<username> database you normally use. Ping mark if you get an error trying to use this test database - it may not have been automatically created.

If your database setup is not clustered (most dreamhacks aren't), you should delete the 'c01' and 'c02' entries from %DBINFO and only use 'master'. You can also safely delete the entry for 'theschwartz' if you haven't configured that. This is the simplest example of a working config-test-private.pl on a dreamhack:

{
  package DW::PRIVATE;
 
  %DBINFO = (
       master => {
           dbname => "test_dreamhack_kareila",
           user => "dh_kareila",
           pass => "xxxxxxxxxxxx",
       }
  );
}

config-test.pl

In your local copy of config-test.pl, delete the 'c01' and 'c02' entries from %DBINFO in this file as well.

You also need to add cluster1 => 1 to the 'role' hashref for 'master' in config-test.pl.

Finally, change @CLUSTERS and $DEFAULT_CLUSTER in t/config-test.pl to be (1) and [1], respectively.

Initialize the DB

Once the config files are copied and edited properly, there is one final step that must be taken, which is to initialize the test database. Note: The initial section of this script may show failure messages on newly created dreamhacks, which already have a test database prepared for the user.

cd $LJHOME
t/bin/initialize-db

This script effectively runs update-db.pl and texttool.pl on the test database. You should do this as often as you update your regular server database, so that any schema changes are adopted in both places.

If the initialize-db script gives you errors, there is likely a problem with your config files that needs to be corrected before you can proceed. Some errors can be more easily identified and troubleshooted by running the dev-setup.t test file and seeing which specific tests fail.

cd $LJHOME
prove -v t/dev-setup.t

Running The Tests

To run the entire suite of tests:

cd $LJHOME
prove -r t/

To prove a specific test:

cd $LJHOME
prove t/sometest.t

If everything is working as it should, you should see the text "ok" printed once per test file, to indicate that the tests in that file all passed. Sometimes you will see the text "skipped" followed by a short explanation of why that set of tests was skipped. If a test fails, you should get a large amount of information to assist in diagnosing the problem, and you can get even more information by using prove -v. Running the entire test suite should take less than five minutes.

(See also Test process for QA testing, though this is less relevant to most devs)

Writing new tests

In an ideal world, test-driven development means writing a test to replicate the bug, fixing the bug, then checking that the test passes. Look at the lists of tests in $LJHOME/t/ to find something similar if needed.

If you're adding a new test to an existing file, remember to update the count of tests planned at the top of the file - there will be a row like:

use Test::More tests => 36;

Other quirks

• To have a beautiful set of passing tests, you'll need to have CAPTCHA set up on your Dreamhack, though not necessarily enabled: How to enable CAPTCHAs on your Dreamhack