MySQL  8.0.26
Source Code Documentation
Unit Testing Using the Google Test Framework

The Google Test unit-testing framework is available in MySQL source trees and distributions.

Google Test, like MyTAP, provides a unit- testing framework, but Google Test provides richer functionality, such as:

  • A rich set of predicates
  • User-defined predicates and assertions
  • Automatic test registration
  • Nice error reporting when a predicate fails (with line number, expected and actual values, and additional comments)
  • Test fixtures, and setup/teardown logic
  • Death tests
  • Disabled tests
  • Test filtering and shuffling

Google Test runs on many platforms. Some functionality is missing on some platforms (such as death tests and parameterized tests), so those features should not be used.

This section provides notes about using Google Test within the context of MySQL development. For general-purpose information about Google Test, see these resources:

Installing Google Test and Running Unit Tests

MySQL sources do not include Google Test. To install it so that you can use it, use one of these approaches:

  • Install Google Test in individual source trees. Use the -DENABLE_DOWNLOADS=1 configuration option. This causes CMake to download Google Test and install it in your source tree for you.

  • Install a single instance of Google Test. MySQL requires Google Test 1.6 or higher.

    When Google Test has been installed, set the GTEST_PREFIX environment variable appropriately for your command interpreter. For example, use this command line for bash:

    export GTEST_PREFIX

Installing Google Test in individual source trees is the recommended method. The single-instance installation method can be used only if all MySQL builds on a machine take place in the same environment (same operating system, same compiler), for reasons discussed at

At configuration time, CMake looks for gtest.h. The build process compiles all Google Test-based unit tests or ignores them, depending on whether gtest.h is found.

After the build has completed, to run the tests, change location into the unittest/gunit directory and execute the ctest command. It need not be invoked with any options, but you can run it with the --help option to see what options are available.

Another way to run the unit tests is with this command:

make test-unit

For internal MySQL testing, PushBuild has been extended to install Google Test as a separate “package”. All trees named mysql-trunk.* are set up to depend on this package.

Writing Unit Tests for Google Test

Most of The Google Test unit test files are located in the unittest/gunit directory. You can look at these files to see how tests are written. Here are some examples:

  • A simple test of some list classes
  • Some tests of metadata locking (MDL), including testing of lock acquisition from multiple threads
  • The same tests as, but written for MyTAP, to illustrate some features of Google Test

Most MyTAP-based tests are likely easily converted to Google Test. However, there might be low-level tests that absolutely must be run on every platform, and thus require MyTAP.

To see what options are available, run a test executable with the --help option.