3.5 Testing Connector/J

The Connector/J source code repository or packages that are shipped with source code include an extensive test suite, containing test cases that can be executed independently. The test cases are divided into the following categories:

• Functional or unit tests: Classes from the package testsuite.simple. Include test code for the main features of the Connector/J.

• Performance tests: Classes from the package testsuite.perf. Include test code to make measurements for the performance of Connector/J.

• Regression tests: Classes from the package testsuite.regression. Includes code for testing bug and regression fixes.

The bundled Ant build file contains targets like test and test-multijvm, which can facilitate the process of running the Connector/J tests; see the target descriptions in the build file for details. Besides the requirements for building Connector/J from the source code described in Section 3.4, “Installing from Source”, a number of the tests also require the File System Service Provider 1.2 for the Java Naming and Directory Interface (JNDI), available at http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html)—place the jar files downloaded from there into the lib directory or in the directory pointed to by the property com.mysql.jdbc.extra.libs.

To run the test using Ant, in addition to the properties required for Section 3.4, “Installing from Source”, you must set the following properties in the build.properties file or through the Ant -D options:

• com.mysql.jdbc.testsuite.url: it specifies the JDBC URL for connection to a MySQL test server; see Section 5.3, “Configuration Properties for Connector/J”.

• com.mysql.jdbc.testsuite.jvm: the JVM to be used for the tests. If the property is set, the specified JVM will be used for all test cases except if it points to a Java 5 directory, in which case any test cases for JDBC 4.0 and later are run with the JVM supplied with the property com.mysql.jdbc.jdk8 (for 5.1.36 and earlier, supplied with the property com.mysql.jdbc.jdk6). If the property is not set, the JVM supplied with com.mysql.jdbc.jdk5 will be used to run test cases for JDBC 3.0 and the one supplied with com.mysql.jdbc.jdk8 (for 5.1.36 and earlier, supplied with the property com.mysql.jdbc.jdk6) will be used to run test cases for JDBC 4.0 and later.

After setting these parameters, run the tests with Ant in the following ways:

• Building the test target with ant test runs all test cases by default on a single server instance. If you want to run a particular test case, put the test's fully qualified class names in the test variable; for example:

  shell > ant -Dtest=testsuite.simple.StringUtilsTest test

  You can also run individual tests in a test case by specifying the names of the corresponding methods in the methods variable, separating multiple methods by commas; for example:

  shell > ant -Dtest=testsuite.simple.StringUtilsTest -Dmethods=testIndexOfIgnoreCase,testGetBytes test

• Building the test-multijvm target with ant test-multijvm runs all the test cases using multiple JVMs of different versions on multiple server instances. For example, if you want to run the tests using a Java 7 and a Java 8 JVM on three server instances with different configurations, you will need to use the following properties:

  com.mysql.jdbc.testsuite.jvm.1=path_to_Java_7
  com.mysql.jdbc.testsuite.jvm.2=path_to_Java_8
  com.mysql.jdbc.testsuite.url.1=URL_to_1st_server
  com.mysql.jdbc.testsuite.url.2=URL_to_2nd_server
  com.mysql.jdbc.testsuite.url.3=URL_to_3rd_server

  Unlike the target test, the target test-multijvm only recognizes the properties com.mysql.jdbc.testsuite.jvm.N and com.mysql.jdbc.testsuite.url.N, where N is a numeric suffice; the same properties without the suffices are ignored by test-multijvm. As with the target test, if any of the com.mysql.jdbc.testsuite.jvm.N settings points to Java 5, then Ant relies on the property com.mysql.jdbc.jdk8 to run the tests specific to JDBC 4.0 and later.

  You can choose to run individual test cases or specific tests by using the test or methods property, as explained in the last bullet for the target test. Each test is run once per possible combination of JVMs and server instances (that is, 6 times in total for in this example).

  When a test for a certain JVM-server combination has failed, test-multijvm does not throw an error, but moves on to the next combination, until all tests for all combinations are finished.

While the test results are partially reported by the console, complete reports in HTML and XML formats are provided:

• For results of test: view the HTML report by opening build/junit/unitregress/report/index.html. XML version of the reports are located in the folder build/junit/unitregress.

• For results of test-multijvm: view the HTML report for each JVM-server combination by opening build/junit/MySQLN.server_version/operating_system_version/jvm-version/unitregress/report/index.html. XML version of the reports are located in the folder build/junit/MySQLN.server_version/operating_system_version/jvm-version/unitregress.