Typically, you run the test suite either from within a source tree (after MySQL has been built), or on a host where the MySQL server distribution has been installed.

(If you find that the test suite is not included in your distribution, look for a similar distribution with -test in the name and install that as well.)

To run tests, your current working directory should be the mysql-test directory of your source tree or installed distribution. In a source distribution, mysql-test is under the root of the source tree. In a binary distribution, the location of mysql-test depends on the distribution layout. The program that runs the test suite, mysql-test-run.pl, will figure out whether you are in a source tree or an installed directory tree.

To run the test suite, change location into your mysql-test directory and invoke the mysql-test-run.pl script:

shell> cd mysql-test
shell> ./mysql-test-run.pl

mysql-test-run.pl accepts options on the command line. For example:

shell> ./mysql-test-run.pl --force --suite=binlog

By default, mysql-test-run.pl exits if a test case fails. --force causes execution to continue regardless of test case failure.

For a full list of the supported options, see mysql-test-run.pl — Run MySQL Test Suite.

To run one or more specific test cases, name them on the mysql-test-run.pl command line. Test case files have names like t/test_name.test, where test_name is the name of the test case, but each name given on the command line should be the test case name, not the full test case file name. The following command runs the test case named rpl_abcd, which has a test file of t/rpl_abcd.test:

shell> ./mysql-test-run.pl rpl_abcd

To run a family of test cases for which the names share a common prefix, use the --do-test option:

shell> ./mysql-test-run.pl --do-test=prefix

For example, the following command runs the events tests (test cases that have names beginning with events):

shell> ./mysql-test-run.pl --do-test=events

To run a specific named testsuite with all the test cases in it, use the --suite option:

shell> ./mysql-test-run.pl --suite=suite_name

For example, the following command runs the replication tests located in the rpl suite:

shell> ./mysql-test-run.pl --suite=rpl

mysql-test-run.pl starts the MySQL server, sets up the environment for calling the mysqltest program, and invokes mysqltest to run the test case. For each test case to be run, mysqltest handles operations such as reading input from the test case file, creating server connections, and sending SQL statements to servers.

The language used in test case files is a mix of commands that the mysqltest program understands and SQL statements. Input that mysqltest doesn't understand is assumed to consist of SQL statements to be sent to the database server. This makes the test case language familiar to those that know how to write SQL and powerful enough to add the control needed to write test cases.

You need not start a MySQL server first before running tests. Instead, the mysql-test-run.pl program will start the server or servers as needed. Any servers started for the test run use ports in the range from 13000 by default.

Running Tests in Parallel

It is possible to run more than one instance of mysql-test-run.pl simultaneously on the same machine. Both will by default use server ports from 13000 but will coordinate used port numbers as well as check for availibility, to avoid conflicts.

Running several instances from the same mysql-test directory is possible but problematic. You must the use the --vardir to set different log directories for each instance. Even so, you can get into trouble becuse they will write .reject files to the same directories.

It is also possible to have a single mysql-test-run.pl run tests in several threads in parallel. Execution of the tests will be distributed among the threads. This is achieved using the --parallel option, with the number of threads as argument. The special value auto will ask mysql-test-run.pl to pick a value automatically, based on system information. The parallel option may also be given using the environment variable MTR_PARALLEL.

Note: Test cases which use not_parallel.inc are run at the end with a parallel value of 1 overriding the --parallel option value. Such test cases will be executed at the end of the test run one at a time.