Chapter 8 Plugins for Testing Plugin Services

MySQL server plugins have access to server “services,” as described in MySQL Services for Plugins. As of MySQL 5.7.8, MySQL distributions include plugins that demonstrate how to test plugin service APIs:

• The test_framework plugin is a bare bones plugin that shows the minimum required framework for service testing.

• The test_services plugin demonstrates how to test the my_snprintf and my_plugin_log_service services in unthreaded context.

• The test_services_threaded plugin is like test_services, but for threaded context.

The source code for the plugins is located in the plugin/test_services directory of MySQL source distributions. The README file in that directory contains instructions for running the test cases available for the test_services and test_services_threaded plugins.

Note

The test plugins in plugin/test_services are daemon plugins (see Daemon Plugins). For an example of a nondaemon service-testing plugin plugin, see the test_security_context.cc file (available as of MySQL 5.7.9) in the plugin/audit_null directory. This file creates an audit plugin for testing the security_context service.

Use the following procedure to create a new service-testing plugin based on one of those provided in the plugin/test_services directory. Assume that you want to create a new plugin named test_myservice (or test_myservice_threaded to test in threaded context).

1. Select a source file to use as a basis for the new plugin:

   • To begin with a bare bones plugin, copy test_framework.cc to test_myservice.cc.

   • To begin with a plugin that already includes code for running tests in unthreaded context, copy test_services.cc to test_myservice.cc.

   • To begin with a plugin that already includes code for running tests in threaded context, copy test_services_threaded.cc to test_myservice_threaded.cc.

2. There is a plugin descriptor near the end of the new source file. Modify this descriptor appropriately for your plugin. Change the name, author, and descr members that indicate the plugin name and author and provide a description. For example, if you copied test_framework.cc, those members look like this:

   "test_framework",
   "Horst Hunger",
   "Test framework",
   

   Change them to something like this:

   "test_myservice",
   "Your Name Here",
   "Test My Service",
   

3. Modify your source file appropriately for the service to be tested:

   • If you copied test_framework.cc, your file has no tests initially and is set up for unthreaded context. In this case, add code to the test_services_plugin_init() function. This code should invoke the service to be tested.

   • If you copied test_services.cc or test_services_threaded.cc, the file contains tests for the my_snprintf and my_plugin_log_service services in unthreaded or threaded contexts. Replace or modify those tests with code for your own tests.

Compiling your plugin creates a plugin library file, which you should install in the directory named by the plugin_dir system variable. The file base name is the same as that of the source file. The file name suffix differs per platform (for example, .so for Unix and Unix-like systems, .dll for Windows).

To install or unintall your plugin at server startup, use the --plugin-load or --plugin-load-add option. For example, you can use these lines in an option file (adjust the file name as necessary):

[mysqld]
plugin-load-add=test_myservice.so

To install or uninstall the plugin at runtime, use these statements (adjust the plugin name and file name as necessary):

INSTALL PLUGIN test_myservice SONAME 'test_myservice.so';
UNINSTALL PLUGIN test_myservice;

For addition information about plugin loading, see Installing and Uninstalling Plugins.

For information about creating and running test cases for your new plugin, adapt the instructions in the README file in the plugin/test_services directory. Test cases for the test_services and test_services_threaded plugins are located in mysql-test/suite/test_services.