Author: paul
Date: 2009-11-04 22:04:47 +0100 (Wed, 04 Nov 2009)
New Revision: 17451
Log:
r46123@frost: paul | 2009-11-04 15:03:31 -0500
Fork mysqltest manual for bjorn to work on 2.0 version
Added:
trunk/mysqltest-2.0/Makefile
trunk/mysqltest-2.0/Makefile.depends
trunk/mysqltest-2.0/all-entities.ent
trunk/mysqltest-2.0/command-reference.xml
trunk/mysqltest-2.0/components.xml
trunk/mysqltest-2.0/introduction.xml
trunk/mysqltest-2.0/legalnotice.en.xml
trunk/mysqltest-2.0/mysqltest.xml
trunk/mysqltest-2.0/preface.xml
trunk/mysqltest-2.0/programs.xml
trunk/mysqltest-2.0/renamed-nodes.txt
trunk/mysqltest-2.0/running-tests.xml
trunk/mysqltest-2.0/test-nodes
trunk/mysqltest-2.0/unit-test.xml
trunk/mysqltest-2.0/writing-tests.xml
Modified:
trunk/Makefile
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 07c7e7b4-24e3-4b51-89d0-6dc09fec6bec:/mysqldoc-local/mysqldoc/trunk:27523
07c7e7b4-24e3-4b51-89d0-6dc09fec6bec:/mysqldoc-local/trunk:25547
4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:43968
4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/trunk:44480
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:46122
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:39036
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/trunk:39546
+ 07c7e7b4-24e3-4b51-89d0-6dc09fec6bec:/mysqldoc-local/mysqldoc/trunk:27523
07c7e7b4-24e3-4b51-89d0-6dc09fec6bec:/mysqldoc-local/trunk:25547
4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:43968
4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/trunk:44480
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:46123
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:39036
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/trunk:39546
Modified: trunk/Makefile
===================================================================
--- trunk/Makefile 2009-11-04 21:04:40 UTC (rev 17450)
+++ trunk/Makefile 2009-11-04 21:04:47 UTC (rev 17451)
Changed blocks: 1, Lines Added: 1, Lines Deleted: 0; 314 bytes
@@ -18,6 +18,7 @@
mysqldoc-guide \
mysqlqb \
mysqltest \
+ mysqltest-2.0 \
mysql-backup \
ndbapi \
proto-doc \
Added: trunk/mysqltest-2.0/Makefile
===================================================================
--- trunk/mysqltest-2.0/Makefile (rev 0)
+++ trunk/mysqltest-2.0/Makefile 2009-11-04 21:04:47 UTC (rev 17451)
Changed blocks: 1, Lines Added: 68, Lines Deleted: 0; 1906 bytes
@@ -0,0 +1,68 @@
+# Makefile for MySQL test framework manual
+
+# Location of repository root relative to current directory
+REPO_ROOT = ..
+
+# Include the main repo configuration
+include $(REPO_ROOT)/Makefile.repo
+
+# Set any variables here that should override imported standard variables
+
+DOC_LANG = en
+MAIN_DOC_BASENAME = mysqltest
+GENERATE_AUTOLINK = 1
+
+DOC_URL_BASE = http://dev.mysql.com/doc/$(MAIN_DOC_BASENAME)/$(DOC_LANG)/
+
+# Set IDMAP and remap variables
+
+IDMAP_LANG = $(DOC_LANG)
+IDMAP_MAIN = mysqltest
+
+IDMAP_URLBASE = $(IDMAP_MAIN)/$(IDMAP_LANG)
+IDMAP_REFS = $(REPO_ROOT)/mysqltest $(REPO_ROOT)/refman-5.1
+IDMAP_SRCS = $(call base_xml_files)
+
+# Import standard variables
+
+include $(MAKE_DIR)/vars-layout
+include $(MAKE_DIR)/vars-shell
+include $(MAKE_DIR)/vars-docbook
+
+# Import default target rule (causes help message to print)
+
+include $(MAKE_DIR)/default-target
+
+# Files for which to generate dependencies
+DEPEND_FILES = mysqltest.xml
+
+clean::
+ $(RM) mysqltest.txt
+
+# Import document dependency specifications
+
+include Makefile.depends
+
+# Import standard target rules
+
+include $(MAKE_DIR)/xml-valid
+include $(MAKE_DIR)/xml-format
+include $(MAKE_DIR)/xml-useless
+include $(MAKE_DIR)/xml-prep
+include $(MAKE_DIR)/xml-html
+include $(MAKE_DIR)/xml-html-section
+include $(MAKE_DIR)/xml-html-chapter
+include $(MAKE_DIR)/xml-html-web
+include $(MAKE_DIR)/xml-chm
+include $(MAKE_DIR)/xml-xhtml
+include $(MAKE_DIR)/xml-pdf
+include $(MAKE_DIR)/xml-toc
+include $(MAKE_DIR)/xml-txt
+include $(MAKE_DIR)/xml-info
+include $(MAKE_DIR)/xml-man
+include $(MAKE_DIR)/xml-remark
+include $(MAKE_DIR)/xml-depend
+
+# Import directory specific extensions
+
+include $(MAKE_DIR)/Makefile.ext
Added: trunk/mysqltest-2.0/Makefile.depends
===================================================================
--- trunk/mysqltest-2.0/Makefile.depends (rev 0)
+++ trunk/mysqltest-2.0/Makefile.depends 2009-11-04 21:04:47 UTC (rev 17451)
Changed blocks: 1, Lines Added: 172, Lines Deleted: 0; 7543 bytes
@@ -0,0 +1,172 @@
+command_reference_INCLUDES = \
+ ../common/fixedchars.ent \
+ all-entities.ent
+command_reference_IMAGES =
+command_reference_SOURCES = command-reference.xml $(command_reference_INCLUDES)
+command_reference_IDMAPS = \
+ metadata/command-reference.idmap \
+ metadata/writing-tests.idmap
+command-reference.validpure: $(command_reference_SOURCES)
+command-reference.titles: $(command_reference_SOURCES)
+command-reference.useless: $(command_reference_SOURCES)
+command-reference.valid: $(command_reference_SOURCES) $(command_reference_IDMAPS)
+command-reference.validwarn: $(command_reference_SOURCES) $(command_reference_IDMAPS)
+command-reference-prepped.xml: $(command_reference_SOURCES) $(command_reference_IDMAPS)
+command-reference-manprepped.xml: $(command_reference_SOURCES)
$(command_reference_IDMAPS)
+command-reference-remprepped.xml: $(command_reference_SOURCES)
$(command_reference_IDMAPS)
+
+components_INCLUDES = \
+ ../common/fixedchars.ent \
+ all-entities.ent
+components_IMAGES =
+components_SOURCES = components.xml $(components_INCLUDES)
+components_IDMAPS = \
+ metadata/writing-tests.idmap
+components.validpure: $(components_SOURCES)
+components.titles: $(components_SOURCES)
+components.useless: $(components_SOURCES)
+components.valid: $(components_SOURCES) $(components_IDMAPS)
+components.validwarn: $(components_SOURCES) $(components_IDMAPS)
+components-prepped.xml: $(components_SOURCES) $(components_IDMAPS)
+components-manprepped.xml: $(components_SOURCES) $(components_IDMAPS)
+components-remprepped.xml: $(components_SOURCES) $(components_IDMAPS)
+
+introduction_INCLUDES = \
+ ../common/fixedchars.ent \
+ all-entities.ent
+introduction_IMAGES =
+introduction_SOURCES = introduction.xml $(introduction_INCLUDES)
+introduction_IDMAPS =
+introduction.validpure: $(introduction_SOURCES)
+introduction.titles: $(introduction_SOURCES)
+introduction.useless: $(introduction_SOURCES)
+introduction.valid: $(introduction_SOURCES) $(introduction_IDMAPS)
+introduction.validwarn: $(introduction_SOURCES) $(introduction_IDMAPS)
+introduction-prepped.xml: $(introduction_SOURCES) $(introduction_IDMAPS)
+introduction-manprepped.xml: $(introduction_SOURCES) $(introduction_IDMAPS)
+introduction-remprepped.xml: $(introduction_SOURCES) $(introduction_IDMAPS)
+
+legalnotice_en_INCLUDES =
+legalnotice_en_IMAGES =
+legalnotice_en_SOURCES = legalnotice.en.xml $(legalnotice_en_INCLUDES)
+legalnotice_en_IDMAPS =
+legalnotice.en.validpure: $(legalnotice_en_SOURCES)
+legalnotice.en.titles: $(legalnotice_en_SOURCES)
+legalnotice.en.useless: $(legalnotice_en_SOURCES)
+legalnotice.en.valid: $(legalnotice_en_SOURCES) $(legalnotice_en_IDMAPS)
+legalnotice.en.validwarn: $(legalnotice_en_SOURCES) $(legalnotice_en_IDMAPS)
+legalnotice.en-prepped.xml: $(legalnotice_en_SOURCES) $(legalnotice_en_IDMAPS)
+legalnotice.en-manprepped.xml: $(legalnotice_en_SOURCES) $(legalnotice_en_IDMAPS)
+legalnotice.en-remprepped.xml: $(legalnotice_en_SOURCES) $(legalnotice_en_IDMAPS)
+
+mysqltest_INCLUDES = \
+ ../common/fixedchars.ent \
+ all-entities.ent \
+ command-reference.xml \
+ components.xml \
+ introduction.xml \
+ legalnotice.en.xml \
+ preface.xml \
+ programs.xml \
+ running-tests.xml \
+ unit-test.xml \
+ writing-tests.xml
+mysqltest_IMAGES =
+mysqltest_SOURCES = mysqltest.xml $(mysqltest_INCLUDES)
+mysqltest_IDMAPS = \
+ ../refman-5.1/metadata/installing-source-core.idmap \
+ metadata/command-reference.idmap \
+ metadata/programs.idmap \
+ metadata/writing-tests.idmap
+mysqltest.validpure: $(mysqltest_SOURCES)
+mysqltest.titles: $(mysqltest_SOURCES)
+mysqltest.useless: $(mysqltest_SOURCES)
+mysqltest.valid: $(mysqltest_SOURCES) $(mysqltest_IDMAPS)
+mysqltest.validwarn: $(mysqltest_SOURCES) $(mysqltest_IDMAPS)
+mysqltest-prepped.xml: $(mysqltest_SOURCES) $(mysqltest_IDMAPS)
+mysqltest-manprepped.xml: $(mysqltest_SOURCES) $(mysqltest_IDMAPS)
+mysqltest-remprepped.xml: $(mysqltest_SOURCES) $(mysqltest_IDMAPS)
+
+preface_INCLUDES = \
+ ../common/fixedchars.ent \
+ all-entities.ent
+preface_IMAGES =
+preface_SOURCES = preface.xml $(preface_INCLUDES)
+preface_IDMAPS =
+preface.validpure: $(preface_SOURCES)
+preface.titles: $(preface_SOURCES)
+preface.useless: $(preface_SOURCES)
+preface.valid: $(preface_SOURCES) $(preface_IDMAPS)
+preface.validwarn: $(preface_SOURCES) $(preface_IDMAPS)
+preface-prepped.xml: $(preface_SOURCES) $(preface_IDMAPS)
+preface-manprepped.xml: $(preface_SOURCES) $(preface_IDMAPS)
+preface-remprepped.xml: $(preface_SOURCES) $(preface_IDMAPS)
+
+programs_INCLUDES = \
+ ../common/fixedchars.ent \
+ all-entities.ent
+programs_IMAGES =
+programs_SOURCES = programs.xml $(programs_INCLUDES)
+programs_IDMAPS = \
+ ../refman-5.1/metadata/installing-source-core.idmap \
+ metadata/command-reference.idmap \
+ metadata/writing-tests.idmap
+programs.validpure: $(programs_SOURCES)
+programs.titles: $(programs_SOURCES)
+programs.useless: $(programs_SOURCES)
+programs.valid: $(programs_SOURCES) $(programs_IDMAPS)
+programs.validwarn: $(programs_SOURCES) $(programs_IDMAPS)
+programs-prepped.xml: $(programs_SOURCES) $(programs_IDMAPS)
+programs-manprepped.xml: $(programs_SOURCES) $(programs_IDMAPS)
+programs-remprepped.xml: $(programs_SOURCES) $(programs_IDMAPS)
+
+running_tests_INCLUDES = \
+ ../common/fixedchars.ent \
+ all-entities.ent
+running_tests_IMAGES =
+running_tests_SOURCES = running-tests.xml $(running_tests_INCLUDES)
+running_tests_IDMAPS = \
+ metadata/programs.idmap
+running-tests.validpure: $(running_tests_SOURCES)
+running-tests.titles: $(running_tests_SOURCES)
+running-tests.useless: $(running_tests_SOURCES)
+running-tests.valid: $(running_tests_SOURCES) $(running_tests_IDMAPS)
+running-tests.validwarn: $(running_tests_SOURCES) $(running_tests_IDMAPS)
+running-tests-prepped.xml: $(running_tests_SOURCES) $(running_tests_IDMAPS)
+running-tests-manprepped.xml: $(running_tests_SOURCES) $(running_tests_IDMAPS)
+running-tests-remprepped.xml: $(running_tests_SOURCES) $(running_tests_IDMAPS)
+
+unit_test_INCLUDES = \
+ ../common/fixedchars.ent \
+ all-entities.ent
+unit_test_IMAGES =
+unit_test_SOURCES = unit-test.xml $(unit_test_INCLUDES)
+unit_test_IDMAPS =
+unit-test.validpure: $(unit_test_SOURCES)
+unit-test.titles: $(unit_test_SOURCES)
+unit-test.useless: $(unit_test_SOURCES)
+unit-test.valid: $(unit_test_SOURCES) $(unit_test_IDMAPS)
+unit-test.validwarn: $(unit_test_SOURCES) $(unit_test_IDMAPS)
+unit-test-prepped.xml: $(unit_test_SOURCES) $(unit_test_IDMAPS)
+unit-test-manprepped.xml: $(unit_test_SOURCES) $(unit_test_IDMAPS)
+unit-test-remprepped.xml: $(unit_test_SOURCES) $(unit_test_IDMAPS)
+
+writing_tests_INCLUDES = \
+ ../common/fixedchars.ent \
+ all-entities.ent
+writing_tests_IMAGES =
+writing_tests_SOURCES = writing-tests.xml $(writing_tests_INCLUDES)
+writing_tests_IDMAPS = \
+ metadata/command-reference.idmap \
+ metadata/programs.idmap \
+ metadata/writing-tests.idmap
+writing-tests.validpure: $(writing_tests_SOURCES)
+writing-tests.titles: $(writing_tests_SOURCES)
+writing-tests.useless: $(writing_tests_SOURCES)
+writing-tests.valid: $(writing_tests_SOURCES) $(writing_tests_IDMAPS)
+writing-tests.validwarn: $(writing_tests_SOURCES) $(writing_tests_IDMAPS)
+writing-tests-prepped.xml: $(writing_tests_SOURCES) $(writing_tests_IDMAPS)
+writing-tests-manprepped.xml: $(writing_tests_SOURCES) $(writing_tests_IDMAPS)
+writing-tests-remprepped.xml: $(writing_tests_SOURCES) $(writing_tests_IDMAPS)
+
+# End of dependencies
Added: trunk/mysqltest-2.0/all-entities.ent
===================================================================
--- trunk/mysqltest-2.0/all-entities.ent (rev 0)
+++ trunk/mysqltest-2.0/all-entities.ent 2009-11-04 21:04:47 UTC (rev 17451)
Changed blocks: 1, Lines Added: 11, Lines Deleted: 0; 794 bytes
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ This file names all the entity files needed by .xml files in the
+ current directory. All ENTITY declarations should be given
+ first, followed by references to the those entities.
+-->
+<!ENTITY base-url-downloads "http://dev.mysql.com/downloads/">
+<!ENTITY base-url-generic-refman "http://dev.mysql.com/doc/mysql/en">
+<!ENTITY base-url-uploads "ftp://ftp.mysql.com/pub/mysql/upload/">
+<!ENTITY % fixedchars.entities SYSTEM "../common/fixedchars.ent">
+%fixedchars.entities;
Added: trunk/mysqltest-2.0/command-reference.xml
===================================================================
--- trunk/mysqltest-2.0/command-reference.xml (rev 0)
+++ trunk/mysqltest-2.0/command-reference.xml 2009-11-04 21:04:47 UTC (rev 17451)
Changed blocks: 1, Lines Added: 2791, Lines Deleted: 0; 86338 bytes
@@ -0,0 +1,2791 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % all.entities SYSTEM "all-entities.ent">
+ %all.entities;
+]>
+<chapter id="mysqltest-reference">
+
+ <title><command>mysqltest</command> Language Reference</title>
+
+ <para>
+ This chapter describes the test language implemented by
+ <command>mysqltest</command>. The language allows input to contain a
+ mix of comments, commands executed by <command>mysqltest</command>
+ itself, and SQL statements that <command>mysqltest</command> sends
+ to a MySQL server for execution.
+ </para>
+
+ <para>
+ <emphasis role="bold">Terminology notes:</emphasis>
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A <quote>command</quote> is an input test that
+ <command>mysqltest</command> recognizes and executes itself. A
+ <quote>statement</quote> is an SQL statement or query that
+ <command>mysqltest</command> sends to the MySQL server to be
+ executed.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When <command>mysqltest</command> starts, it opens a connection
+ named <literal>default</literal> to the MySQL server, using any
+ connection parameters specified by the command options. (For a
+ local server, the default user name is <literal>root</literal>.
+ For an external server, the default user name is
+ <literal>test</literal> or the user specified with the
+ <option>--user</option> option.) You can use the
+ <literal>connect</literal> command to open other connections,
+ the <literal>connection</literal> command to switch between
+ connections, and the <literal>disconnect</literal> command to
+ close connections. However, the capability for switching
+ connections means that the connection named
+ <literal>default</literal> need not be the connection in use at
+ a given time. To avoid ambiguity, this document avoids the term
+ <quote>default connection.</quote> It uses the term
+ <quote>current connection</quote> to mean <quote>the connection
+ currently in use,</quote> which might be different from
+ <quote>the connection named
<literal>default</literal>.</quote>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <section id="mysqltest-input-conventions">
+
+ <title><command>mysqltest</command> Input Conventions</title>
+
+ <para>
+ <command>mysqltest</command> reads input lines and processes them
+ as follows:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <quote>End of line</quote> means a newline (linefeed)
+ character. A carriage return/linefeed (CRLF) pair also is
+ allowable as as a line terminator (the carriage return is
+ ignored). Carriage return by itself is
+ <emphasis>not</emphasis> allowed as a line terminator.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A line that begins with
<quote><literal>#</literal></quote> as
+ the first nonwhitespace content is treated as a comment that
+ extends to the end of the line and is ignored. Example:
+ </para>
+
+<programlisting>
+# this is a comment
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ (Deprecated syntax) A line that begins with
+ <quote><literal>--</literal></quote> as the first
+ nonwhitespace content also is treated as a comment that
+ extends to the end of the line. However, unlike
+ <quote><literal>#</literal></quote> comments, if the
first
+ word of the comment is a valid <command>mysqltest</command>
+ command, <command>mysqltest</command> executes the line from
+ that word to the end of the line as a command.
+ </para>
+
+ <para>
+ <command>mysqltest</command> interprets the following lines as
+ comments because the first word is not a
+ <command>mysqltest</command> command:
+ </para>
+
+<programlisting>
+-- this is a comment
+-- clean up from previous test runs
+</programlisting>
+
+ <para>
+ <command>mysqltest</command> interprets the following lines as
+ commands and executes them because the first word is a
+ <command>mysqltest</command> command:
+ </para>
+
+<programlisting>
+--disconnect conn1
+-- error 1050
+</programlisting>
+
+ <para>
+ The <quote><literal>--</literal></quote> syntax is
useful for
+ writing commands that contain embedded instances of the
+ command delimiter:
+ </para>
+
+<programlisting>
+-- echo write this text; it goes to the result file
+</programlisting>
+
+ <para>
+ The <quote><literal>--</literal></quote> syntax for
writing
+ comments is deprecated because of the potential for
+ accidentally writing comments that begin with a keyword and
+ being executed. This syntax cannot be used for comments as of
+ MySQL 5.1.30/6.0.8.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Other input is taken as normal command input. The command
+ extends to the next occurrence of the command delimiter, which
+ is semicolon (<quote><literal>;</literal></quote>) by
default.
+ The delimiter can be changed with the
+ <literal>delimiter</literal> command.
+ </para>
+
+ <para>
+ If <command>mysqltest</command> recognizes the first word of
+ the delimiter-terminated command, <command>mysqltest</command>
+ executes the command itself. Otherwise,
+ <command>mysqltest</command> assumes that the command is an
+ SQL statement and sends it to the MySQL server to be executed.
+ </para>
+
+ <para>
+ Because the command extends to the delimiter, a given input
+ line can contain multiple commands, and a given command can
+ span multiple lines. The ability to write multiple-line
+ statements is useful for making long statements more readable,
+ such as a <literal>create table</literal> statement for a
+ table that has many columns.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ After <command>mysqltest</command> reads a command up to a
+ delimiter and executes it, input reading restarts following the
+ delimiter and any remaining input on the line that contains the
+ delimiter is treated as though it begins on a new line. Consider
+ the following two input lines:
+ </para>
+
+<programlisting>
+echo issue a select statement; select 1; echo done
+issuing the select statement;
+</programlisting>
+
+ <para>
+ That input contains two commands and one SQL statement:
+ </para>
+
+<programlisting>
+echo issue a SELECT statement
+SELECT 1;
+echo done issuing the SELECT statement
+</programlisting>
+
+ <para>
+ Similarly, <quote><literal>#</literal></quote> comments or
+ <quote><literal>--</literal></quote> comments can begin on
a
+ command line following a delimiter:
+ </para>
+
+<programlisting>
+SELECT 'hello'; # select a string value
+SELECT 'hello'; -- echo that was a SELECT statement
+</programlisting>
+
+ <para>
+ On a multiple-line command,
<quote><literal>#</literal></quote> or
+ <quote><literal>--</literal></quote> at the beginning of
the
+ second or following lines is not special. Thus, the second and
+ third lines of the following variable-assignment command are not
+ taken as comments. Instead, the variable <literal>$a</literal> is
+ set to a value that contains two linefeed characters:
+ </para>
+
+<programlisting>
+let $a= This is a variable
+# assignment that sets a variable
+-- to a multiple-line value;
+ </programlisting>
+
+ <para>
+ Note that <quote><literal>--</literal></quote> comments and
normal
+ commands have complementary properties with regard to how
+ <command>mysqltest</command> reads them:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A <quote><literal>--</literal></quote> comment is
terminated
+ by a newline, regardless of how many delimiters it contains.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A normal command (without
+ <quote><literal>--</literal></quote>) is terminated by
the
+ delimiter (semicolon), no matter how many newlines it
+ contains.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ <command>mysqltest</command> commands can be written either as
+ comments (with a leading
<quote><literal>--</literal></quote>) or
+ as normal command input (no leading
+ <quote><literal>--</literal></quote>). Use the command
delimiter
+ only in the latter case. Thus, these two lines are equivalent:
+ </para>
+
+<programlisting>
+--sleep 2
+sleep 2;
+</programlisting>
+
+ <para>
+ The equivalence is true even for the <literal>delimiter</literal>
+ command. For example, to set the delimiter to
+ <quote><literal>//</literal></quote>, either of these
commands
+ work:
+ </para>
+
+<programlisting>
+--delimiter //
+delimiter //;
+</programlisting>
+
+ <para>
+ To set the delimiter back to <quote>;</quote>, use either of these
+ commands:
+ </para>
+
+<programlisting>
+--delimiter ;
+delimiter ;//
+</programlisting>
+
+ <para>
+ The input language has certain ambiguities. For example, if you
+ write the following line, intending it as a comment that indicates
+ where test 43 ends, it will not work:
+ </para>
+
+<programlisting>
+-- End of test 43
+</programlisting>
+
+ <para>
+ The <quote>comment</quote> is not treated as such because
+ <literal>end</literal> is a valid
<command>mysqltest</command>
+ command. Thus, although it is <emphasis>possible</emphasis> to
+ write a noncommand comment that begins with
+ <quote><literal>--</literal></quote>, it is better to use
+ <quote><literal>#</literal></quote> instead. Writing
comments with
+ <quote><literal>#</literal></quote> also has less potential
to
+ cause problems in the future. For example,
+ <command>mysqltest</command> interprets the line
<literal>--switch
+ to conn1</literal> as a comment currently, but if
+ <command>mysqltest</command> is extended in the future to add a
+ <literal>switch</literal> command, that line will be treated as a
+ command instead. If you use
<quote><literal>#</literal></quote>
+ for all comments, this problem will not occur.
+ </para>
+
+ <para>
+ Another ambiguity occurs because a noncomment line can contain
+ either a <command>mysqltest</command> command or an SQL statement.
+ This has a couple of implications:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ No <command>mysqltest</command> command should be the same as
+ any keyword that can begin an SQL statement.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Should extensions to SQL be implemented in the future, it is
+ possible that a new SQL keyword could be impossible for
+ <command>mysqltest</command> to recognize as such if that
+ keyword is already used as a <command>mysqltest</command>
+ command.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <remark role="todo">
+ Describe quoting and escaping rules. How to include a literal
+ quote? Double it? Escape it? Can you escape a delimiter as "\;"?
+ But then what if the delimiter is multiple characters? (I guess
+ that wouldn't matter. If the first char is not taken as a
+ delimiter beginning, the rest wouldn't be recognized, either.
+ Escaping appears to be allowable only in limited contexts?
+ </remark>
+
+ </section>
+
+ <section id="mysqltest-commands">
+
+ <title><command>mysqltest</command> Commands</title>
+
+ <remark>
+ For echo, exec, system, variable expansion does not appear to work
+ very well before MySQL 5.0.19.
+ </remark>
+
+ <para>
+ <command>mysqltest</command> supports the commands described in
+ this section. Command names are not case sensitive.
+ </para>
+
+ <para>
+ Some examples of command use are given, but you can find many more
+ by searching the test case files in the
+ <filename>mysql-test/t</filename> directory.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal>append_file <replaceable>file_name</replaceable>
+ [<replaceable>terminator</replaceable>]</literal>
+ </para>
+
+ <para>
+ <literal>append_file</literal> is like
+ <literal>write_file</literal> except that the lines up to the
+ terminator are added to the end of the file. The file is
+ created if it does not exist. The file name argument is
+ subject to variable substitution.
+ </para>
+
+<programlisting>
+write_file /tmp/data01;
+line one for the file
+line two for the file
+EOF
+append_file /tmp/data01;
+line three for the file
+EOF
+</programlisting>
+
+<programlisting>
+write_file /tmp/data02 END_OF_FILE;
+line one for the file
+line two for the file
+END_OF_FILE
+append_file /tmp/data02 END_OF_FILE;
+line three for the file
+END_OF_FILE
+</programlisting>
+
+ <para>
+ <literal>append_file</literal> was added in MySQL
+ 4.1.23/5.0.41/5.1.17.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>cat_file
+ <replaceable>file_name</replaceable></literal>
+ </para>
+
+ <para>
+ <literal>cat_file</literal> writes the contents of the file to
+ the output. The file name argument is subject to variable
+ substitution.
+ </para>
+
+<programlisting>
+cat_file /tmp/data01;
+</programlisting>
+
+ <para>
+ <literal>cat_file</literal> was added in MySQL
+ 4.1.23/5.0.41/5.1.17.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>change_user [<replaceable>user_name</replaceable>],
+ [<replaceable>password</replaceable>],
+ [<replaceable>db_name</replaceable>]</literal>
+ </para>
+
+ <para>
+ Changes the current user and causes the database specified by
+ <replaceable>db_name</replaceable> to become the default
+ database for the current connection.
+ </para>
+
+<programlisting>
+change_user root;
+--change_user root,,test
+</programlisting>
+
+ <para>
+ <literal>change_user</literal> was added in MySQL 5.1.23.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>character_set
+ <replaceable>charset_name</replaceable></literal>
+ </para>
+
+ <para>
+ Set the default character set to
+ <replaceable>charset_name</replaceable>. Initially, the
+ character set is <literal>latin1</literal>.
+ </para>
+
+<programlisting>
+character_set utf8;
+--character_set sjis
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>chmod_file <replaceable>octal_mode</replaceable>
+ <replaceable>file_name</replaceable></literal>
+ </para>
+
+ <para>
+ Change the mode of the given file. The file mode must be given
+ as a four-digit octal number. The file name argument is
+ subject to variable substitution, but must evaluate to a
+ literal file name, not a file name pattern.
+ </para>
+
+<programlisting>
+chmod_file 0644 /tmp/data_xxx01;
+</programlisting>
+
+ <para>
+ <literal>chmod_file</literal> was added in MySQL
+ 4.1.23/5.0.32/5.1.15.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>connect (<replaceable>name</replaceable>,
+ <replaceable>host_name</replaceable>,
+ <replaceable>user_name</replaceable>,
+ <replaceable>password</replaceable>,
+ <replaceable>db_name</replaceable>
+ [,<replaceable>port_num</replaceable>
+ [,<replaceable>socket</replaceable>
+ [,<replaceable>options</replaceable>]]])</literal>
+ </para>
+
+ <para>
+ Open a connection to the server and make the connection the
+ current connection. (Syntax oddities: There must be whitespace
+ between <command>connect</command> and the opening
+ parenthesis, and no whitespace after the opening parenthesis.)
+ </para>
+
+ <para>
+ The arguments to <literal>connect</literal> are:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <replaceable>name</replaceable> is the name for the
+ connection (for use with the
+ <literal>connection</literal>,
+ <literal>disconnect</literal>, and
+ <literal>dirty_close</literal> commands). This name must
+ not already be in use by an open connection.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <replaceable>host_name</replaceable> indicates the host
+ where the server is running.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <replaceable>user_name</replaceable> and
+ <replaceable>password</replaceable> are the user name and
+ password of the MySQL account to use.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <replaceable>db_name</replaceable> is the default database
+ to use. As a special case, <literal>*NO-ONE*</literal>
+ means that no default database should be selected. You can
+ also leave <replaceable>db_name</replaceable> blank to
+ select no database.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <replaceable>port_num</replaceable>, if given, is the
+ TCP/IP port number to use for the connection. This
+ parameter can be given by using a variable.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <replaceable>socket</replaceable>, if given, is the socket
+ file to use for connections to
+ <literal>localhost</literal>. This parameter can be given
+ by using a variable.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <replaceable>options</replaceable> can be one or more of
+ the words <literal>SSL</literal> and
+ <literal>COMPRESS</literal>, separated by spaces. These
+ specify the use of SSL and the compressed client/server
+ protocol, respectively.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ To omit an argument, just leave it blank. For an omitted
+ argument, <command>mysqltest</command> uses an empty string
+ for the first five arguments and the
+ <replaceable>options</replaceable> argument. For omitted port
+ or socket options, <command>mysqltest</command> uses the
+ default port or socket.
+ </para>
+
+<programlisting>
+connect (conn1,localhost,root,,);
+connect (conn2,localhost,root,mypass,test);
+connect (conn1,127.0.0.1,root,,test,$MASTER_MYPORT);
+</programlisting>
+
+ <para>
+ The last example assumes that the
+ <literal>$MASTER_MYPORT</literal> variable has already been
+ set (perhaps as an environment variable).
+ </para>
+
+ <para>
+ If a connection attempt fails initially,
+ <command>mysqltest</command> retries five times if the
+ abort-on-error setting is enabled.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>connection
+ <replaceable>connection_name</replaceable></literal>
+ </para>
+
+ <para>
+ Select <replaceable>connection_name</replaceable> as the
+ current connection. To select the connection that
+ <command>mysqltest</command> opens when it starts, use the
+ name <literal>default</literal>.
+ </para>
+
+<programlisting>
+connection master;
+connection conn2;
+connection default;
+</programlisting>
+
+ <para>
+ As of MySQL 5.1.32 and 6.0.10, a variable can be used to
+ specify the <replaceable>connection_name</replaceable> value.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>copy_file <replaceable>from_file</replaceable>
+ <replaceable>to_file</replaceable></literal>
+ </para>
+
+ <para>
+ Copy the file <replaceable>from_file</replaceable> to the file
+ <replaceable>to_file</replaceable>. The command fails if
+ <replaceable>to_file</replaceable> already exists. The file
+ name arguments are subject to variable substitution.
+ </para>
+
+ <para>
+ <literal>copy_file</literal> was added in MySQL
+ 4.1.23/5.0.30/5.1.13.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>dec
$<replaceable>var_name</replaceable></literal>
+ </para>
+
+ <para>
+ Decrement a numeric variable. If the variable does not have a
+ numeric value, the result is undefined.
+ </para>
+
+<programlisting>
+dec $count;
+dec $2;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>delimiter
<replaceable>str</replaceable></literal>
+ </para>
+
+ <para>
+ Set the command delimiter to <replaceable>str</replaceable>,
+ which may consist of 1 to 15 characters. The default delimiter
+ is the semicolon character
+ (<quote><literal>;</literal></quote>).
+ </para>
+
+ <remark>
+ The Wiki docs state a max length of 16, but that isn't
+ correct. The value of 16 includes the terminating null byte.
+ </remark>
+
+<programlisting>
+delimiter //;
+--delimiter stop
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>die
[<replaceable>message</replaceable>]</literal>
+ </para>
+
+ <para>
+ Aborts the test with an error code after printing the given
+ message as the reason. Suppose that a test file contains the
+ following line:
+ </para>
+
+<programlisting>
+die "Cannot continue";
+</programlisting>
+
+ <para>
+ When <command>mysqltest</command> encounters that line, it
+ produces the following result and exits:
+ </para>
+
+<programlisting>
+mysqltest: At line 1: "Cannot continue"
+not ok
+</programlisting>
+
+ <para>
+ <literal>die</literal> was added in MySQL
+ 4.1.23/5.0.30/5.1.12.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>diff_files <replaceable>file_name1</replaceable>
+ <replaceable>file_name2</replaceable></literal>
+ </para>
+
+ <para>
+ Compare the two files. The command succeeds if the files are
+ the same, and fails if they are different or either file does
+ not exist. The file name arguments are subject to variable
+ substitution.
+ </para>
+
+ <para>
+ <literal>diff_files</literal> was added in MySQL
+ 4.1.23/5.0.41/5.1.17.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>dirty_close
+ <replaceable>connection_name</replaceable></literal>
+ </para>
+
+ <para>
+ Close the named connection. This is like
+ <literal>disconnect</literal> except that it calls
+ <literal>vio_delete()</literal> before it closes the
+ connection. If the connection is the current connection, you
+ should use the <literal>connection</literal> command to switch
+ to a different connection before executing further SQL
+ statements.
+ </para>
+
+ <para>
+ As of MySQL 5.1.32 and 6.0.10, a variable can be used to
+ specify the <replaceable>connection_name</replaceable> value.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>disable_abort_on_error</literal>,
+ <literal>enable_abort_on_error</literal>
+ </para>
+
+ <para>
+ Disable or enable abort-on-error behavior. This setting is
+ enabled by default. With this setting enabled,
+ <command>mysqltest</command> aborts the test when a statement
+ sent to the server results in an unexpected error, and does
+ not generate the <filename>.reject</filename> file. For
+ discussion of reasons why it can be useful to disable this
+ behavior, see <xref linkend="error-handling"/>.
+ </para>
+
+<programlisting>
+--disable_abort_on_error
+--enable_abort_on_error
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>disable_info</literal>,
+ <literal>enable_info</literal>
+ </para>
+
+ <para>
+ Disable or enable additional information about SQL statement
+ results. This setting is disabled by default. With this
+ setting enabled, <command>mysqltest</command> displays the
+ affected-rows count and the output from the
+ <literal>mysql_info()</literal> C API function. The
+ <quote>affected-rows</quote> value is <quote>rows
+ selected</quote> for statements such as
+ <literal>SELECT</literal> and <quote>rows
modified</quote> for
+ statements that change data.
+ </para>
+
+<programlisting>
+--disable_info
+--enable_info
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>disable_metadata</literal>,
+ <literal>enable_metadata</literal>
+ </para>
+
+ <para>
+ Disable or enable query metadata display. This setting is
+ disabled by default. With this setting enabled,
+ <command>mysqltest</command> adds query metadata to the
+ result. This information consists of the values corresponding
+ to the members of the <literal>MYSQL_FIELD</literal> C API
+ data structure, for each column of the result.
+ </para>
+
+<programlisting>
+--disable_metadata
+--enable_metadata
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>disable_parsing</literal>,
+ <literal>enable_parsing</literal>
+ </para>
+
+ <para>
+ Disable or enable query parsing. This setting is enabled by
+ default. When disabled, <command>mysqltest</command> ignores
+ everything until <literal>enable_parsing</literal>.
+ </para>
+
+<programlisting>
+--disable_parsing
+--enable_parsing
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>disable_ps_protocol</literal>,
+ <literal>enable_ps_protocol</literal>
+ </para>
+
+ <para>
+ Disable or enable prepared-statement protocol. This setting is
+ disabled by default unless the <option>--ps-protocol</option>
+ option is given.
+ </para>
+
+<programlisting>
+--disable_ps_protocol
+--enable_ps_protocol
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>disable_ps_warnings</literal>,
+ <literal>enable_ps_warnings</literal>
+ </para>
+
+ <para>
+ Disable or enable prepared-statement warnings. This setting is
+ enabled by default.
+ </para>
+
+<programlisting>
+--disable_ps_warnings
+--enable_ps_warnings
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>disable_query_log</literal>,
+ <literal>enable_query_log</literal>
+ </para>
+
+ <para>
+ Disable or enable query logging. This setting is enabled by
+ default. With this setting enabled,
+ <command>mysqltest</command> echoes input SQL statements to
+ the test result.
+ </para>
+
+ <para>
+ One reason to disable query logging is to reduce the amount of
+ test output produces, which also makes comparison of actual
+ and expected results more efficient.
+ </para>
+
+<programlisting>
+--disable_query_log
+--enable_query_log
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>disable_reconnect</literal>,
+ <literal>enable_reconnect</literal>
+ </para>
+
+ <para>
+ Disable or enable automatic reconnect for dropped connections.
+ (The default depends the client library version.) This command
+ applies to connections made afterward.
+ </para>
+
+<programlisting>
+--disable_reconnect
+--enable_reconnect
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>disable_result_log</literal>,
+ <literal>enable_result_log</literal>
+ </para>
+
+ <para>
+ Disable or enable the result log. This setting is enabled by
+ default. With this setting enabled,
+ <command>mysqltest</command> displays query results (and
+ results from commands such as <literal>echo</literal> and
+ <literal>exec</literal>).
+ </para>
+
+<programlisting>
+--disable_result_log
+--enable_result_log
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>disable_rpl_parse</literal>,
+ <literal>enable_rpl_parse</literal>
+ </para>
+
+ <para>
+ Disable or enable parsing of statements to determine whether
+ they go to the master or slave. (MySQL 4.0 and up only.) The
+ default is whatever the default is for the C API library.
+ </para>
+
+<programlisting>
+--disable_rpl_parse
+--enable_rpl_parse
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>disable_warnings</literal>,
+ <literal>enable_warnings</literal>
+ </para>
+
+ <para>
+ Disable or enable warnings. This setting is enabled by
+ default. With this setting enabled,
+ <command>mysqltest</command> uses <literal>SHOW
+ WARNINGS</literal> to display any warnings produced by SQL
+ statements.
+ </para>
+
+<programlisting>
+--disable_warnings
+--enable_warnings
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>disconnect
+ <replaceable>connection_name</replaceable></literal>
+ </para>
+
+ <para>
+ Close the named connection. If the connection is the current
+ connection, you should use the <literal>connection</literal>
+ command to switch to a different connection before executing
+ further SQL statements.
+ </para>
+
+<programlisting>
+disconnect conn2;
+disconnect slave;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>echo <replaceable>text</replaceable></literal>
+ </para>
+
+ <para>
+ Echo the text to the test result. References to variables
+ within the text are replaced with the corresponding values.
+ </para>
+
+<programlisting>
+--echo "Another sql_mode test"
+echo "should return only 1 row";
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>end</literal>
+ </para>
+
+ <para>
+ End an <literal>if</literal> or
<literal>while</literal>
+ block. If there is no such block open,
+ <command>mysqltest</command> exits with an error. See
+ <xref linkend="mysqltest-flow-control"/>, for information on
+ flow-control constructs.
+ </para>
+
+ <para>
+ <command>mysqltest</command> considers
<literal>}</literal>
+ and <literal>end</literal> the same: Both end the current
+ block.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>end_timer</literal>
+ </para>
+
+ <para>
+ Stop the timer. By default, the timer does not stop until just
+ before <command>mysqltest</command> exits.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>error <replaceable>error_code</replaceable> [,
+ <replaceable>error_code</replaceable>] ...</literal>
+ </para>
+
+ <para>
+ Specify one or more comma-separated error values that the next
+ command is expected to return. Each
+ <replaceable>error_code</replaceable> value is a
+ MySQL-specific error number or an SQLSTATE value. (These are
+ the kinds of values returned by the
+ <literal>mysql_errno()</literal> and
+ <literal>mysql_sqlstate()</literal> C API functions,
+ respectively.)
+ </para>
+
+ <para>
+ If you specify an SQLSTATE value, it should begin with an
+ <literal>S</literal> to enable
<command>mysqltest</command> to
+ distinguish it from a MySQL error number. For example, the
+ error number 1050 and the SQLSTATE value
+ <literal>42S01</literal> are equivalent, so the following
+ commands specify the same expected error:
+ </para>
+
+<programlisting>
+--error 1050
+--error S42S01
+</programlisting>
+
+ <para>
+ SQLSTATE values should be five characters long and may contain
+ only digits and uppercase letters.
+ </para>
+
+ <para>
+ Is is also possible to use the symbolic error name from
+ <filename>mysqld_error.h</filename>:
+ </para>
+
+<programlisting>
+--error ER_TABLE_EXISTS_ERROR
+</programlisting>
+
+ <para>
+ If a statement fails with an error that has not been specified
+ as expected by means of a <literal>error</literal> command,
+ <command>mysqltest</command> aborts and reports the error
+ message returned by the MySQL server.
+ </para>
+
+ <para>
+ If a statement fails with an error that has been specified as
+ expected by means of a <literal>error</literal> command,
+ <command>mysqltest</command> does not abort. Instead, it
+ continues and writes a message to the result output.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If an <literal>error</literal> command is given with a
+ single error value and the statement fails with that
+ error, <command>mysqltest</command> reports the error
+ message returned by the MySQL server.
+ </para>
+
+ <para>
+ Input:
+ </para>
+
+<programlisting>
+--error S42S02
+DROP TABLE t;
+</programlisting>
+
+ <para>
+ <command>mysqltest</command> reports:
+ </para>
+
+<programlisting>
+ERROR 42S02: Unknown table 't'
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ If an <literal>error</literal> command is given with
+ multiple error values and the statement fails with that
+ error, <command>mysqltest</command> reports a generic
+ message. (This is true even if the error values are all
+ the same, a fact that can be used if you want a message
+ that does not contain varying information such as table
+ names.)
+ </para>
+
+ <para>
+ Input:
+ </para>
+
+<programlisting>
+--error S41S01,S42S02
+DROP TABLE t;
+</programlisting>
+
+ <para>
+ <command>mysqltest</command> reports:
+ </para>
+
+<programlisting>
+Got one of the listed errors
+</programlisting>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ An error value of 0 or <literal>S00000</literal> means
+ <quote>no error,</quote> so using either for an
+ <literal>error</literal> command is the same as saying
+ explicitly, <quote>no error is expected, the statement must
+ succeed.</quote>.
+ </para>
+
+ <remark role="note">
+ [PD] The following behavior was documented in the Wiki, so
+ apparently it is deliberate. I don't understand the intent of
+ the different behavior, though. It seems like a bug to me.
+ </remark>
+
+ <para>
+ To indicate that you expect success or a given error or
+ errors, specify 0 or <literal>S00000</literal> first in the
+ error list. If you put the no-error value later in the list,
+ the test will abort if the statement is successful. That is,
+ these two commands have different effects:
+ </para>
+
+<programlisting>
+--error 0,1051
+--error 1051,0
+</programlisting>
+
+ <para>
+ You can use <literal>error</literal> to specify shell status
+ values for testing the value of shell commands executed via
+ the <literal>exec</literal> command. This does not apply to
+ <literal>system</literal>, for which the command status is
+ ignored.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>eval
<replaceable>statement</replaceable></literal>
+ </para>
+
+ <para>
+ Evaluate the statement by replacing references to variables
+ within the text with the corresponding values. Then send the
+ resulting statement to the server to be executed. Use
+ <quote><literal>\$</literal></quote> to specify a
literal
+ <quote><literal>$</literal></quote> character.
+ </para>
+
+ <para>
+ The advantage of using <literal>eval
+ <replaceable>statement</replaceable></literal> versus just
+ <replaceable>statement</replaceable> is that
+ <literal>eval</literal> provides variable expansion.
+ </para>
+
+<programlisting>
+eval USE $DB;
+eval CHANGE MASTER TO MASTER_PORT=$SLAVE_MYPORT;
+eval PREPARE STMT1 FROM "$my_stmt";
+</programlisting>
+ </listitem>
+
+<!--
+According to Magnus, this isn't used. Commenting it out.
+ <listitem>
+ <para>
+ <literal>eval_result</literal>
+ </para>
+
+ <para>
+ Unknown.
+ </para>
+ </listitem>
+-->
+
+ <listitem>
+ <para>
+ <literal>exec <replaceable>command</replaceable>
+ [<replaceable>arg</replaceable>] ...</literal>
+ </para>
+
+ <para>
+ Execute the shell command using the <literal>popen()</literal>
+ library call. References to variables within the command are
+ replaced with the corresponding values. Use
+ <quote><literal>\$</literal></quote> to specify a
literal
+ <quote><literal>$</literal></quote> character.
+ </para>
+
+ <para>
+ On Cygwin, the command is executed from
+ <command>cmd.exe</command>, so commands such as
+ <command>rm</command> cannot be executed with
+ <literal>exec</literal>. Use <literal>system</literal>
+ instead.
+ </para>
+
+<programlisting>
+--exec $MYSQL_DUMP --xml --skip-create test
+--exec rm $MYSQLTEST_VARDIR/tmp/t1
+exec $MYSQL_SHOW test -v -v;
+</programlisting>
+
+ <note>
+ <para>
+ <literal>exec</literal> or <literal>system</literal>
are
+ sometimes used to perform file system operations, but the
+ command for doing so tend to be operating system specifc,
+ which reduces test portability. <command>mysqltest</command>
+ now has several commands to perform these operations
+ portably, so they should be used instead:
+ <literal>remove_file</literal>,
+ <literal>chmod_file</literal>,
<literal>mkdir</literal>, and
+ so forth.
+ </para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>exit</literal>
+ </para>
+
+ <para>
+ Terminate the test case. This is considered a <quote>normal
+ termination.</quote> That is, using <literal>exit</literal>
+ does not result in evaluation of the test case as having
+ failed.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>file_exists
+ <replaceable>file_name</replaceable></literal>
+ </para>
+
+ <para>
+ <literal>file_exists</literal> succeeds if the name file
+ exists and fails otherwise. The file name argument is subject
+ to variable substitution.
+ </para>
+
+<programlisting>
+file_exists /etc/passwd;
+</programlisting>
+
+ <para>
+ <literal>file_exists</literal> was added in MySQL
+ 4.1.23/5.0.30/5.1.13.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>horizontal_results</literal>
+ </para>
+
+ <para>
+ Set the default query result display format to horizontal.
+ Initially, the default is to display results horizontally.
+ </para>
+
+<programlisting>
+--horizontal_results
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>if (<replaceable>expr</replaceable>)</literal>
+ </para>
+
+ <para>
+ Begin an <literal>if</literal> block, which continues until an
+ <literal>end</literal> line.
<command>mysqltest</command>
+ executes the block if the expression is true. There is no
+ provision for <literal>else</literal> with
+ <literal>if</literal>. See
+ <xref linkend="mysqltest-flow-control"/>, for further
+ information about <literal>if</literal> statements.
+ </para>
+
+<programlisting>
+let $counter= 0;
+if ($counter)
+{
+ echo Counter is greater than 0, (counter=0);
+}
+if (!$counter)
+{
+ echo Counter is not 0, (counter=0);
+}
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>inc
$<replaceable>var_name</replaceable></literal>
+ </para>
+
+ <para>
+ Increment a numeric variable. If the variable does not have a
+ numeric value, the result is undefined.
+ </para>
+
+<programlisting>
+inc $i;
+inc $3;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>let $<replaceable>var_name</replaceable> =
+ <replaceable>value</replaceable></literal>
+ </para>
+
+ <para>
+ <literal>let $<replaceable>var_name</replaceable> =
+ query_get_value(<replaceable>query</replaceable>,
+ <replaceable>col_name</replaceable>,
+ <replaceable>row_num</replaceable>)</literal>
+ </para>
+
+ <para>
+ Assign a value to a variable. The variable name cannot contain
+ whitespace or the <quote><literal>=</literal></quote>
+ character. <command>mysqltest</command> aborts with an error
+ if the value is erroneous.
+ </para>
+
+ <para>
+ As of MySQL 5.0.26/5.1.12, references to variables within
+ <replaceable>value</replaceable> are replaced with their
+ corresponding values.
+ </para>
+
+ <para>
+ If the <literal>let</literal> command is specified as a normal
+ command (that is, not beginning with
+ <quote><literal>--</literal></quote>),
+ <replaceable>value</replaceable> includes everything up to the
+ command delimiter, and thus can span multiple lines.
+ </para>
+
+<programlisting>
+--let $1= 0
+let $count= 10;
+</programlisting>
+
+ <para>
+ The result from executing a query can be assigned to a
+ variable by enclosing the query within backtick
+ (<quote><literal>`</literal></quote>) characters:
+ </para>
+
+<programlisting>
+let $q= `SELECT VERSION()`;
+</programlisting>
+
+ <remark role="todo">
+ It appears that there can be no space between the variable
+ name and the <literal>=</literal> operator before MySQL
+ 4.1.15? (Otherwise, the statement might assign no value.)
+ </remark>
+
+ <para>
+ The <literal>let</literal> command can set environment
+ variables, not just <command>mysqltest</command> test language
+ variables. To assign a value to an environment variable rather
+ than a test language variable, just omit the dollar sign:
+ </para>
+
+<programlisting>
+let $mysqltest_variable= foo;
+let ENV_VARIABLE= bar;
+</programlisting>
+
+ <para>
+ This is useful in interaction with external tools. In
+ particular, when using the <literal>perl</literal> command,
+ the Perl code cannot access test language variables, but it
+ can access environment variables. For example, the following
+ statement can access the <literal>ENV_VARIABLE</literal>
+ value:
+ </para>
+
+<programlisting>
+print $ENV{'ENV_VARIABLE'};
+</programlisting>
+
+ <para>
+ As of MySQL 4.1.24/5.0.44/5.1.20, <literal>let</literal>
+ syntax is extended to allow the retrieval of a value from a
+ query result set produced by a statement such as
+ <literal>SELECT</literal> or <literal>SHOW</literal>.
See the
+ description of <literal>query_get_value()</literal> for more
+ information.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>mkdir
<replaceable>dir_name</replaceable></literal>
+ </para>
+
+ <para>
+ Create a directory named <replaceable>dir_name</replaceable>.
+ Returns 0 for success and 1 for failure.
+ </para>
+
+<programlisting>
+--mkdir testdir
+</programlisting>
+
+ <para>
+ <literal>mkdir</literal> was added in MySQL
+ 5.0.58/5.1.24/6.0.5.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>move_file <replaceable>from_name</replaceable>
+ <replaceable>to_name</replaceable></literal>
+ </para>
+
+ <para>
+ <literal>move_file</literal> renames
+ <replaceable>from_name</replaceable> to
+ <replaceable>to_name</replaceable>. The file name arguments
+ are subject to variable substitution, but must evaluate to a
+ literal file name, not a file name pattern.
+ </para>
+
+<programlisting>
+move_file /tmp/data01 /tmp/test.out;
+</programlisting>
+
+ <para>
+ <literal>move_file</literal> was added in MySQL 5.1.34/6.0.12.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>perl
+ [<replaceable>terminator</replaceable>]</literal>
+ </para>
+
+ <para>
+ Use Perl to execute the following lines of the test file. The
+ lines end when a line containing the terminator is
+ encountered. The default terminator is <literal>EOF</literal>,
+ but a different terminator can be provided.
+ </para>
+
+<programlisting>
+perl;
+print "This is a test\n";
+EOF
+</programlisting>
+
+<programlisting>
+perl END_OF_FILE;
+print "This is another test\n";
+END_OF_FILE
+</programlisting>
+
+ <para>
+ <literal>perl</literal> was added in MySQL
+ 4.1.23/5.0.30/5.1.13.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>ping</literal>
+ </para>
+
+ <para>
+ Ping the server. This executes the
+ <literal>mysql_ping()</literal> C API function. The function
+ result is discarded. The effect is that if the connection has
+ dropped and reconnect is enabled, pinging the server causes a
+ reconnect.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>query
+ [<replaceable>statement</replaceable>]</literal>
+ </para>
+
+ <para>
+ Send the statement to the server to be executed. The
+ <literal>query</literal> command can be used to force
+ <command>mysqltest</command> to send a statement to the server
+ even if it begins with a keyword that is a
+ <command>mysqltest</command> command.
+ </para>
+
+ <remark role="todo">
+ What happens if the optional statement is omitted? Same effect
+ as for <literal>send</literal>?
+ </remark>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>query_get_value(<replaceable>query</replaceable>,
+ <replaceable>col_name</replaceable>,
+ <replaceable>row_num</replaceable>)</literal>
+ </para>
+
+ <para>
+ As of MySQL 4.1.24/5.0.44/5.1.20, the
+ <literal>query_get_value()</literal> function can be used on
+ on the right hand side of a variable assigment in a
+ <literal>let</literal> statement.
+ </para>
+
+ <para>
+ <literal>query_get_value()</literal> enables retrieval of a
+ value from a query result set produced by a statement such as
+ <literal>SELECT</literal> or <literal>SHOW</literal>.
The
+ first argument indicates the query to execute. The second and
+ third arguments indicate the column name and row number that
+ specify which value to extract from the result set. The column
+ name is case sensitive. Row numbers begin with 1. The
+ arguments can be given literally or supplied using variables.
+ </para>
+
+ <para>
+ Suppose that the test file contains this input:
+ </para>
+
+<programlisting>
+CREATE TABLE t1(a INT, b VARCHAR(255), c DATETIME);
+SHOW COLUMNS FROM t1;
+let $value= query_get_value(SHOW COLUMNS FROM t1, Type, 1);
+echo $value;
+</programlisting>
+
+ <para>
+ The result will be:
+ </para>
+
+<programlisting>
+CREATE TABLE t1(a INT, b VARCHAR(255), c DATETIME);
+SHOW COLUMNS FROM t1;
++Field Type Null Key Default Extra
++a int(11) YES NULL
++b varchar(255) YES NULL
++c datetime YES NULL
+
+let $value= query_get_value(SHOW COLUMNS FROM t1, Type, 1);
+echo $value;
++int(11)
+</programlisting>
+
+ <para>
+ If the query fails, an error message occurs and the test
+ fails.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>query_horizontal
+ <replaceable>statement</replaceable></literal>
+ </para>
+
+ <para>
+ Execute the statement and display its result horizontally.
+ </para>
+
+<programlisting>
+query_horizontal SELECT PI();
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>query_vertical
+ <replaceable>statement</replaceable></literal>
+ </para>
+
+ <para>
+ Execute the statement and display its result vertically.
+ </para>
+
+<programlisting>
+query_vertical SELECT PI();
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>real_sleep
<replaceable>num</replaceable></literal>
+ </para>
+
+ <para>
+ Sleep <replaceable>num</replaceable> seconds.
+ <replaceable>num</replaceable> can have a fractional part.
+ Unlike the <literal>sleep</literal> command,
+ <literal>real_sleep</literal> is not affected by the
+ <option>--sleep</option> command-line option.
+ </para>
+
+<programlisting>
+--real_sleep 10
+real_sleep 5;
+</programlisting>
+
+ <para>
+ Try not to use <literal>sleep</literal> or
+ <literal>real_sleep</literal> commands more than necessary.
+ The more of them there are, the slower the test suite becomes.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>reap</literal>
+ </para>
+
+ <para>
+ Receive the result of the statement sent with the
+ <literal>send</literal> command within the current session.
+ You should not use <replaceable>reap</replaceable> unless a
+ statement has been sent with <literal>send</literal>, and you
+ should not use <literal>send</literal> again if there is an
+ outstanding <literal>send</literal> that has not been
+ processed with <literal>reap</literal>.
+ </para>
+
+ <remark role="todo">
+ BUG#20304: If no statement has yet been sent, you'll end up
+ waiting a very long time for the result.
+ </remark>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>remove_file
+ <replaceable>file_name</replaceable></literal>
+ </para>
+
+ <para>
+ <literal>remove_file</literal> removes the file. It fails with
+ an error if the file does not exist. The file name argument is
+ subject to variable substitution, but must evaluate to a
+ literal file name, not a file name pattern.
+ </para>
+
+<programlisting>
+remove_file /tmp/data01;
+</programlisting>
+
+ <para>
+ <literal>remove_file</literal> was added in MySQL
+ 4.1.23/5.0.30/5.1.13.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>replace_column <replaceable>col_num</replaceable>
+ <replaceable>value</replaceable>
+ [<replaceable>col_num</replaceable>
+ <replaceable>value</replaceable>] ...</literal>
+ </para>
+
+ <para>
+ Replace strings in the output from the next statement. The
+ value in <replaceable>col_num</replaceable> is replaced by the
+ corresponding <replaceable>value</replaceable>. There can be
+ more than one
+
<replaceable>col_num</replaceable>/<replaceable>value</replaceable>
+ pair. Column numbers start with 1.
+ </para>
+
+ <para>
+ A replacement value can be double-quoted. (Use
+ <quote><literal>\"</literal></quote> to specify a
double quote
+ within a replacement string.) Variables can be used in a
+ replacement value if it is not double-quoted.
+ </para>
+
+ <para>
+ If mixed
+
<literal>replace_<replaceable>xxx</replaceable></literal>
+ commands are given, only the final one applies.
+ </para>
+
+ <para>
+ Note: Although <literal>replace_regex</literal> and
+ <literal>replace_result</literal> affect the output from
+ <literal>exec</literal>,
<literal>replace_column</literal>
+ does not because <literal>exec</literal> output is not
+ necessarily columnar.
+ </para>
+
+<programlisting>
+--replace_column 9 #
+replace_column 1 b 2 d;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>replace_regex
+
/<replaceable>pattern</replaceable>/<replaceable>replacement</replaceable>/[i]
+ ...</literal>
+ </para>
+
+ <para>
+ In the output from the next statement, find strings within
+ columns of the result set that match
+ <replaceable>pattern</replaceable> (a regular expression) and
+ replace them with <replaceable>replacement</replaceable>. Each
+ instance of a string in a column that matches the pattern is
+ replaced. Matching is case sensitive by default. Specify the
+ optional <literal>i</literal> modifier to cause matching to be
+ case insensitive.
+ </para>
+
+ <para>
+ The syntax for allowable patterns is the same as for the
+ <literal>REGEXP</literal> SQL operator. In addition, the
+ pattern can contain parentheses to mark substrings matched by
+ parts of the pattern. These substrings can be referenced in
+ the replacement string: An instance of
+ <literal>\<replaceable>N</replaceable></literal> in the
+ replacement string causes insertion of the
+ <replaceable>N</replaceable>-th substring matched by the
+ pattern. For example, the following command matches
+ <literal>strawberry</literal> and replaces it with
+ <literal>raspberry and strawberry</literal>:
+ </para>
+
+<programlisting>
+--replace_regex /(strawberry)/raspberry and \1/
+</programlisting>
+
+ <para>
+ Multiple
+
<replaceable>pattern</replaceable>/<replaceable>replacement</replaceable>
+ pairs may be given. The following command replaces instances
+ of <literal>A</literal> with <literal>C</literal> (the
first
+ pattern replaces <literal>A</literal> with
+ <literal>B</literal>, the second replaces
<literal>B</literal>
+ with <literal>C</literal>):
+ </para>
+
+<programlisting>
+--replace_regex /A/B/ /B/C/
+</programlisting>
+
+ <para>
+ If a given pattern is not found, no error occurs and the input
+ is unchanged.
+ </para>
+
+ <para>
+ The <literal>replace_regex</literal> command was added in
+ MySQL 5.1.6.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>replace_result <replaceable>from_val
+ to_val</replaceable> [<replaceable>from_val
+ to_val</replaceable>] ...</literal>
+ </para>
+
+ <para>
+ Replace strings in the result. Each occurrence of
+ <replaceable>from_val</replaceable> is replaced by the
+ corresponding <replaceable>to_val</replaceable>. There can be
+ more than
+
<replaceable>from_val</replaceable>/<replaceable>to_val</replaceable>
+ pair. Arguments can be quoted with single quotes or double
+ quotes. Variable references within the arguments are expanded
+ before replacement occurs. Values are matched literally. To
+ use patterns, use the <literal>replace_regex</literal>
+ command.
+ </para>
+
+<programlisting>
+--replace_result 1024 MAX_KEY_LENGTH 3072 MAX_KEY_LENGTH
+replace_result $MASTER_MYPORT MASTER_PORT;
+</programlisting>
+
+ <remark role="todo">
+ Inconsistencies: <literal>replace_column</literal> applies
+ only to the data rows, and not to the row of column headers.
+ <literal>replace_regex</literal> applies both to the column
+ header row and to the data rows.
+ <literal>replace_result</literal> applies to the column header
+ row, the data rows, <emphasis>and</emphasis> to the SQL
+ statement that generates the query output. (Perhaps
+ <literal>replace_regex</literal> also should apply to the
+ query)
+ </remark>
+
+ <remark role="todo">
+ BUG (?): The behavior for <literal>replace_result</literal>
+ also differs from <literal>replace_regex</literal> this way:
+ <literal>replace_result a b b c</literal> does not change
+ <literal>a</literal> to <literal>c</literal>.
Apparently,
+ result replacement for a column stops as soon as a match is
+ found?
+ </remark>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>require
+ <replaceable>file_name</replaceable></literal>
+ </para>
+
+ <para>
+ This command specifies a file to be used for comparison
+ against the results of the next query. If the contents of the
+ file do not match or there is some other error, the test
+ aborts with a <quote>this test is not supported</quote> error
+ message.
+ </para>
+
+<programlisting>
+--require r/slave-stopped.result
+--require r/have_moscow_leap_timezone.require
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>result
<replaceable>file_name</replaceable></literal>
+ </para>
+
+ <para>
+ This command specifies a file to be used for comparison when
+ the test case completes. If the content does not match or
+ there is some other error, write the result to
+
<filename>r/<replaceable>file_name</replaceable>.reject</filename>.
+ </para>
+
+ <para>
+ If the <option>--record</option> command-line option is given,
+ the <literal>result</literal> command changes the file by
+ writing the ew test result to it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>rmdir
<replaceable>dir_name</replaceable></literal>
+ </para>
+
+ <para>
+ Remove a directory named <replaceable>dir_name</replaceable>.
+ Returns 0 for success and 1 for failure.
+ </para>
+
+<programlisting>
+--rmdir testdir
+</programlisting>
+
+ <para>
+ <literal>rmdir</literal> was added in MySQL
+ 5.0.58/5.1.24/6.0.5.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>rpl_probe</literal>
+ </para>
+
+ <para>
+ Unknown.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>save_master_pos</literal>
+ </para>
+
+ <para>
+ For a master replication server, save the current binary log
+ file name and position. These values can be used for
+ subsequent <literal>sync_with_master</literal> or
+ <literal>sync_slave_with_master</literal> commands.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>send
[<replaceable>statement</replaceable>]</literal>
+ </para>
+
+ <para>
+ Send a statement to the server but do not wait for the result.
+ The result must be received with the <literal>reap</literal>
+ command.
+ </para>
+
+ <para>
+ If <replaceable>statement</replaceable> is omitted, the
+ <literal>send</literal> command applies to the next statement
+ executed. This means that <literal>send</literal> can be used
+ on a line by itself before a statement. Thus, this command:
+ </para>
+
+<programlisting>
+send SELECT 1;
+</programlisting>
+
+ <para>
+ Is equivalent to these commands:
+ </para>
+
+<programlisting>
+send;
+SELECT 1;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>shutdown_server
+ [<replaceable>timeout</replaceable>]</literal>
+ </para>
+
+ <para></para>
+
+ <para>
+ Stops the server. This command waits for the server to shut
+ down by monitoring its process ID (PID) file. If the server's
+ process ID file is not gone after
+ <replaceable>timeout</replaceable> seconds, the process will
+ be killed. If <replaceable>timeout</replaceable> is omitted,
+ the default is 60 seconds.
+ </para>
+
+<programlisting>
+shutdown_server;
+shutdown_server 30;
+</programlisting>
+
+ <para>
+ This command was added in MySQL 5.1.26/6.0.6.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>skip
[<replaceable>message</replaceable>]</literal>
+ </para>
+
+ <para>
+ Skips the rest of the test file after printing the given
+ message as the reason. This can be used after checking a
+ condition that must be satisfied, as a way of performing an
+ exit that displays a reason. Suppose that the test file
+ <filename>mytest</filename> has these contents:
+ </para>
+
+<programlisting>
+if ( 1 != 0 )
+{
+ skip "One not equal to zero, skipping test";
+}
+echo "This command is never reached";
+</programlisting>
+
+ <para>
+ Executing <command>mysqltest -x mytest</command> yields these
+ results:
+ </para>
+
+<programlisting>
+The test './mytest' is not supported by this installation
+Detected in file ./mytest at line 3
+reason: "One not equal to zero, skipping test"
+skipped
+</programlisting>
+
+ <para>
+ <literal>skip</literal> was added in MySQL
+ 4.1.23/5.0.32/5.1.18.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>sleep <replaceable>num</replaceable></literal>
+ </para>
+
+ <para>
+ Sleep <replaceable>num</replaceable> seconds.
+ <replaceable>num</replaceable> can have a fractional part. If
+ the <option>--sleep</option> command-line option was given,
+ the option value overrides the value given in the
+ <literal>sleep</literal> command. For example, if
+ <command>mysqltest</command> is started with
+ <option>--sleep=10</option>, the command <literal>sleep
+ 15</literal> sleeps 10 seconds, not 15.
+ </para>
+
+<programlisting>
+--real_sleep 10
+real_sleep 5;
+</programlisting>
+
+ <para>
+ Try not to use <literal>sleep</literal> or
+ <literal>real_sleep</literal> commands more than necessary.
+ The more of them there are, the slower the test suite becomes.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>sorted_result</literal>
+ </para>
+
+ <para>
+ Sort the output from the next statement if it produces a
+ result set. <literal>sorted_result</literal> is applied just
+ before displaying the result, after any other result modifiers
+ that might have been specified, such as
+ <literal>replace_result</literal> or
+ <literal>replace_column</literal>. If the next statement
+ produces no result set, <literal>sorted_result</literal> has
+ no effect because there is nothing to sort.
+ </para>
+
+<programlisting>
+sorted_result;
+SELECT 2 AS "my_col" UNION SELECT 1;
+let $my_stmt=SELECT 2 AS "my_col" UNION SELECT 1;
+--sorted_result
+eval $my_stmt;
+--sorted_result
+--replace_column 1 #
+SELECT '1' AS "my_col1",2 AS "my_col2"
+UNION
+SELECT '2',1;
+</programlisting>
+
+ <para>
+ <literal>sorted_result</literal> sorts the entire result of
+ the next query. If this involves constructs such as
+ <literal>UNION</literal>, stored procedures, or
+ multi-statements, the output will be in a fixed order, but all
+ the results will be sorted together and might appear somewhat
+ strange.
+ </para>
+
+ <para>
+ The purpose of the <literal>sorted_result</literal> command is
+ to produce output with a deterministic order for a given set
+ of result rows. It is possible to use <literal>ORDER
+ BY</literal> to sort query results, but that can sometimes
+ present its own problems. For example, if the optimizer is
+ being investigated for some bug, <literal>ORDER BY</literal>
+ might order the result but return an incorrect set of rows.
+ <literal>sorted_result</literal> can be used to produce sorted
+ output even in the absence of <literal>ORDER BY</literal>.
+ </para>
+
+ <para>
+ <literal>sorted_result</literal> is useful for eliminating
+ differences between test runs that may otherwise be difficult
+ to compensate for. Results without <literal>ORDER BY</literal>
+ are not guaranteed to be returned in any given order, so the
+ result for a given query might differ between test runs. For
+ example, the order might vary between different server
+ versions, so a result file created by one server might fail
+ when compared to the result created by another server. The
+ same is true for different storage engines.
+ <literal>sorted_result</literal> eliminates these order
+ differences by producing a deterministic row order.
+ </para>
+
+ <para>
+ Other ways to eliminate differences from results without use
+ of <literal>sorted_result</literal> include:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Remove columns from the select list to reduce variability
+ in the output
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Use aggregate functions such as <literal>AVG()</literal>
+ on all columns of the select list
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Use <literal>ORDER BY</literal>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The use of aggregate functions or <literal>ORDER BY</literal>
+ may also have the advantage of exposing other bugs by
+ introducing additional stress on the server. The choice of
+ whether to use <literal>sorted_result</literal> or
+ <literal>ORDER BY</literal> (or perhaps both) may be dictated
+ by whether you are trying to expose bugs, or avoid having them
+ affect results. This means that care should be taken with
+ <literal>sorted_result</literal> because it has the potential
+ of hiding server bugs that result in true problems with result
+ order.
+ </para>
+
+ <para>
+ <literal>sorted_result</literal> was added in MySQL
+ 4.1.23/5.0.32/5.1.18.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>source
<replaceable>file_name</replaceable></literal>
+ </para>
+
+ <para>
+ Read test input from the named file.
+ </para>
+
+ <para>
+ If you find that several test case files contain a common
+ section of commands (for example, statements that create a
+ standard set of tables), you can put those commands in another
+ file and those test cases that need the file can include it by
+ means of a <literal>source
+ <replaceable>file_name</replaceable></literal> command. This
+ enables you to write the code just once rather than in
+ multiple test cases.
+ </para>
+
+ <para>
+ Normally, the file name in the <literal>source</literal>
+ command is relative to the <filename>mysql-test</filename>
+ directory because <command>mysqltest</command> usually is
+ invoked in that directory.
+ </para>
+
+ <para>
+ A sourced file can use <literal>source</literal> to read other
+ files, but take care to avoid a loop. The maximum nesting
+ level is 16.
+ </para>
+
+<programlisting>
+--source include/have_csv.inc
+source include/varchar.inc;
+</programlisting>
+
+ <para>
+ As of MySQL 4.1.24, 5.0.50, and 5.1.21, the file name can
+ include variable references. Variables are expanded including
+ any quotes in the values, so normally the values should not
+ include quotes. Suppose that <filename>/tmp/junk</filename>
+ contains this line:
+ </para>
+
+<programlisting>
+SELECT 'I am a query';
+</programlisting>
+
+ <para>
+ The following example shows one way in which variable
+ references could be used to specify the file name:
+ </para>
+
+<programlisting>
+let $dir= /tmp;
+let $file= junk;
+source $dir/$file;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>start_timer</literal>
+ </para>
+
+ <para>
+ Restart the timer, overriding any timer start that occurred
+ earlier. By default, the timer starts when
+ <command>mysqltest</command> begins execution.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>sync_slave_with_master
+ [<replaceable>connection_name</replaceable>]</literal>
+ </para>
+
+ <para>
+ Executing this command is equivalent to executing the
+ following commands:
+ </para>
+
+<programlisting>
+save_master_pos;
+connection <replaceable>connection_name</replaceable>;
+sync_with_master 0;
+</programlisting>
+
+ <para>
+ If <replaceable>connection_name</replaceable> is not
+ specified, the connection named <literal>slave</literal> is
+ used.
+ </para>
+
+ <para>
+ The effect is to save the replication coordinates (binary log
+ file name and position) for the server on the current
+ connection (which is assumed to be a master replication
+ server), and then switch to a slave server and wait until it
+ catches up with the saved coordinates. Note that this command
+ implicitly changes the current connection.
+ </para>
+
+ <para>
+ As of MySQL 5.1.32 and 6.0.10, a variable can be used to
+ specify the <replaceable>connection_name</replaceable> value.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>sync_with_master
+ <replaceable>offset</replaceable></literal>
+ </para>
+
+ <remark role="todo">
+ Is the argument optional? If so, what is the default?
+ </remark>
+
+ <para>
+ For a slave replication server, wait until it has caught up
+ with the master. The position to synchronize to is the
+ position saved by the most recent
+ <literal>save_master_pos</literal> command plus
+ <replaceable>offset</replaceable>.
+ </para>
+
+ <para>
+ To use this command, <literal>save_master_pos</literal> must
+ have been executed at some point earlier in the test case to
+ cause <command>mysqltest</command> to save the master's
+ replication coordinates.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>system <replaceable>command</replaceable>
+ [<replaceable>arg</replaceable>] ...</literal>
+ </para>
+
+ <para>
+ Execute the shell command using the
+ <literal>system()</literal> library call. References to
+ variables within the command are replaced with the
+ corresponding values. Use
<quote><literal>\$</literal></quote>
+ to specify a literal
<quote><literal>$</literal></quote>
+ character.
+ </para>
+
+ <para>
+ On Cygwin, the command is executed from
+ <command>cmd.exe</command>, so commands such as
+ <command>rm</command> cannot be executed with
+ <literal>exec</literal>. Use <literal>system</literal>
+ instead.
+ </para>
+
+<programlisting>
+--system echo '[mysqltest1]' > $MYSQLTEST_VARDIR/tmp/tmp.cnf
+--system echo 'port=1234' >> $MYSQLTEST_VARDIR/tmp/tmp.cnf
+system rm $MYSQLTEST_VARDIR/master-data/test/t1.MYI;
+</programlisting>
+
+ <note>
+ <para>
+ <literal>exec</literal> or <literal>system</literal>
are
+ sometimes used to perform file system operations, but the
+ command for doing so tend to be operating system specifc,
+ which reduces test portability. <command>mysqltest</command>
+ now has several commands to perform these operations
+ portably, so they should be used instead:
+ <literal>remove_file</literal>,
+ <literal>chmod_file</literal>,
<literal>mkdir</literal>, and
+ so forth.
+ </para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>vertical_results</literal>
+ </para>
+
+ <para>
+ Set the default query result display format to vertical.
+ Initially, the default is to display results horizontally.
+ </para>
+
+<programlisting>
+--vertical_results
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>wait_for_slave_to_stop</literal>
+ </para>
+
+ <para>
+ Poll the current connection, which is assumed to be a
+ connection to a slave replication server, by executing
+ <literal>SHOW STATUS LIKE 'Slave_running'</literal> statements
+ until the result is <literal>OFF</literal>.
+ </para>
+
+ <para>
+ For information about alternative means of slave server
+ control, see
+ <xref linkend="writing-tests-replication-tests"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>while
(<replaceable>expr</replaceable>)</literal>
+ </para>
+
+ <para>
+ Begin a <literal>while</literal> loop block, which continues
+ until an <literal>end</literal> line.
+ <command>mysqltest</command> executes the block repeatedly as
+ long as the expression is true. See flow-control constructs.
+ <xref linkend="mysqltest-flow-control"/>, for further
+ information about <literal>while</literal> statements.
+ </para>
+
+ <para>
+ Make sure that the loop includes some exit condition that
+ eventually occurs. This can be done by writing
+ <replaceable>expr</replaceable> so that it becomes false at
+ some point.
+ </para>
+
+<programlisting>
+let $i=5;
+while ($i)
+{
+ echo $i;
+ dec $i;
+}
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>write_file <replaceable>file_name</replaceable>
+ [<replaceable>terminator</replaceable>]</literal>
+ </para>
+
+ <para>
+ Write the following lines of the test file to the given file,
+ until a line containing the terminator is encountered. The
+ default terminator is <literal>EOF</literal>, but a different
+ terminator can be provided. The file name argument is subject
+ to variable substitution. An error occurs if the file already
+ exists.
+ </para>
+
+<programlisting>
+write_file /tmp/data01;
+line one for the file
+line two for the file
+EOF
+</programlisting>
+
+<programlisting>
+write_file /tmp/data02 END_OF_FILE;
+line one for the file
+line two for the file
+END_OF_FILE
+</programlisting>
+
+ <para>
+ <literal>write_file</literal> was added in MySQL
+ 4.1.23/5.0.30/5.1.13.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ <section id="mysqltest-variables">
+
+ <title><command>mysqltest</command> Variables</title>
+
+ <para>
+ You can define variables and refer to their values. You can also
+ refer to environment variables, and there is a built-in variable
+ that contains the result of the most recent SQL statement.
+ </para>
+
+ <para>
+ To define a variable, use the <literal>let</literal> command.
+ Examples:
+ </para>
+
+<programlisting>
+let $a= 14;
+let $b= this is a string;
+--let $a= 14
+--let $b= this is a string
+</programlisting>
+
+ <para>
+ The variable name cannot contain whitespace or the
+ <quote><literal>=</literal></quote> character.
+ </para>
+
+ <para>
+ If a variable has a numeric value, you can increment or decrement
+ the value:
+ </para>
+
+<programlisting>
+inc $a;
+dec $a;
+--inc $a
+--dec $a
+</programlisting>
+
+ <para>
+ <literal>inc</literal> and <literal>dec</literal> are
commonly
+ used in <literal>while</literal> loops to modify the value of a
+ counter variable that controls loop execution.
+ </para>
+
+ <para>
+ The result from executing a query can be assigned to a variable by
+ enclosing the query within backtick
+ (<quote><literal>`</literal></quote>) characters:
+ </para>
+
+<programlisting>
+let $q= `select version()`;
+</programlisting>
+
+ <para>
+ References to variables can occur in the <literal>echo</literal>,
+ <literal>eval</literal>, <literal>exec</literal>, and
+ <literal>system</literal> commands. Variable references are
+ replaced by their values. As of MySQL 5.0.26/5.1.12, a nonquery
+ value assigned to a variable in a <literal>let</literal> command
+ also can refer to variables.
+ </para>
+
+ <para>
+ As of MySQL 4.1.23/5.0.42/5.1.18, variable references that occur
+ within
<literal>`<replaceable>query</replaceable>`</literal> are
+ expanded before the query is sent to the server for execution.
+ </para>
+
+ <para>
+ You can refer to environment variables. For example, this command
+ displays the value of the <literal>$PATH</literal> variable from
+ the environment:
+ </para>
+
+<programlisting>
+--echo $PATH
+</programlisting>
+
+ <para>
+ <literal>$mysql_errno</literal> is a built-in variable that
+ contains the numeric error returned by the most recent SQL
+ statement sent to the server, or 0 if the command executed
+ successfully. <literal>$mysql_errno</literal> has a value of
+ −1 if no statement has yet been sent.
+ </para>
+
+ <para>
+ <command>mysqltest</command> first checks
+ <command>mysqltest</command> variables and then environment
+ variables. <command>mysqltest</command> variable names are not
+ case sensitive. Environment variable names are case sensitive.
+ </para>
+
+ </section>
+
+ <section id="mysqltest-flow-control">
+
+ <title><command>mysqltest</command> Flow Control
Constructs</title>
+
+ <para>
+ The syntax for <literal>if</literal> and
<literal>while</literal>
+ blocks looks like this:
+ </para>
+
+<programlisting>
+if (<replaceable>expr</replaceable>)
+{
+ <replaceable>command list</replaceable>
+}
+</programlisting>
+
+<programlisting>
+while (<replaceable>expr</replaceable>)
+{
+ <replaceable>command list</replaceable>
+}
+</programlisting>
+
+ <para>
+ An expression result is true if nonzero, false if zero. If the
+ expression begins with <literal>!</literal>, the sense of the test
+ is reversed.
+ </para>
+
+ <para>
+ There is no provision for <literal>else</literal> with
+ <literal>if</literal>.
+ </para>
+
+ <para>
+ For a <literal>while</literal> loop, make sure that the loop
+ includes some exit condition that eventually occurs. This can be
+ done by writing <replaceable>expr</replaceable> so that it becomes
+ false at some point.
+ </para>
+
+ <para>
+ The allowable syntax for <replaceable>expr</replaceable> is
+ <literal>$<replaceable>var_name</replaceable></literal>,
+ <literal>!$<replaceable>var_name</replaceable></literal>, a
string
+ or integer, or
+ <literal>`<replaceable>query</replaceable>`</literal>.
+ </para>
+
+ <para>
+ The opening <literal>{</literal> must be separated from the
+ preceding <literal>)</literal> by whitespace (such as a space or a
+ line break).
+ </para>
+
+ <remark role="todo">
+ No spaces allowed between parens and the expression within the
+ parens?
+ </remark>
+
+ <para>
+ As of MySQL 4.1.23/5.0.42/5.1.18, variable references that occur
+ within
<literal>`<replaceable>query</replaceable>`</literal> are
+ expanded before the query is sent to the server for execution.
+ </para>
+
+ </section>
+
+ <section id="error-handling">
+
+ <title>Error Handling</title>
+
+ <para>
+ If an expected error is specified and that error occurs,
+ <command>mysqltest</command> continues reading input. If the
+ command is successful or a different error occurs,
+ <command>mysqltest</command> aborts.
+ </para>
+
+ <para>
+ If no expected error is specified, <command>mysqltest</command>
+ aborts unless the command is successful. (It is implicit that you
+ expect <literal>$mysql_errno</literal> to be 0.)
+ </para>
+
+ <para>
+ By default, <command>mysqltest</command> aborts for certain
+ conditions:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A statement that fails when it should have succeeded. The
+ following statement should succeed if table
+ <literal>t</literal> exists;
+ </para>
+
+<programlisting>
+SELECT * FROM t;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ A statement that fails with an error different from that
+ specified:
+ </para>
+
+<programlisting>
+--error 1
+SELECT * FROM no_such_table;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ A statement that succeeds when an error was expected:
+ </para>
+
+<programlisting>
+--error 1
+SELECT 'a string';
+</programlisting>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ You can disable the abort for errors of the first type by using
+ the <literal>disable_abort_on_error</literal> command. In this
+ case, when errors occur for statements that should succeed,
+ <command>mysqltest</command> continues processing intput.
+ </para>
+
+ <para>
+ <literal>disable_abort_on_error</literal> does
+ <emphasis>not</emphasis> cause <command>mysqltest</command>
to
+ ignore errors for the other two types, where you explicitly state
+ which error you expect. This behavior is intentional. The
+ rationale is that if you use the <literal>error</literal> command
+ to specify an expected error, it is assumed that the test is
+ sufficiently well characterized that only the specified error is
+ accceptable.
+ </para>
+
+ <para>
+ If you do not use the <literal>error</literal> command, it is
+ assumed that you might not know which error to expect or that it
+ might be difficult to characterize all possible errors that could
+ occur. In this case, <literal>disable_abort_on_error</literal> is
+ useful for causing <command>mysqltest</command> to continue
+ processing input. This can be helpful in the following
+ circumstances:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ During test case development, it is useful to process all
+ input even if errors occur so that you can see all errors at
+ once, such as those that occur due to typographical or syntax
+ errors. Otherwise, you can see and fix only one scripting
+ problem at a time.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Within a file that is included with a
+ <literal>source</literal> command by several different test
+ cases, errors might vary depending on the processing
+ environment that is set up prior to the
+ <literal>source</literal> command.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Tests that follow a given statement that can fail are
+ independent of that statement and do not depend on its result.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+</chapter>
Added: trunk/mysqltest-2.0/components.xml
===================================================================
--- trunk/mysqltest-2.0/components.xml (rev 0)
+++ trunk/mysqltest-2.0/components.xml 2009-11-04 21:04:47 UTC (rev 17451)
Changed blocks: 1, Lines Added: 671, Lines Deleted: 0; 22800 bytes
@@ -0,0 +1,671 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % all.entities SYSTEM "all-entities.ent">
+ %all.entities;
+]>
+<chapter id="test-framework-components">
+
+ <title>MySQL Test Framework Components</title>
+
+ <indexterm>
+ <primary>test framework</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>unit tests</primary>
+ </indexterm>
+
+ <para>
+ The MySQL test framework consists of programs that run tests, and
+ directories and files used by those programs.
+ </para>
+
+ <para>
+ <emphasis role="bold">Test Framework Programs</emphasis>
+ </para>
+
+ <para>
+ The MySQL test framework uses several programs:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The <command>mysql-test-run.pl</command> Perl script is the main
+ application used to run the test suite. It invokes
+ <command>mysqltest</command> to run individual test cases.
+ (Prior to MySQL 4.1, a similar shell script,
+ <command>mysql-test-run</command>, can be used instead.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <command>mysqltest</command> runs test cases. A version named
+ <command>mysqltest_embedded</command> is similar but is built
+ with support for the <literal>libmysqld</literal> embedded
+ server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <command>mysql_client_test</command> program is used for
+ testing aspects of the MySQL client API that cannot be tested
+ using <command>mysqltest</command> and its test language.
+ <command>mysql_client_test_embedded</command> is similar but
+ used for testing the embedded server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <command>mysql-stress-test.pl</command> Perl script performs
+ stress-testing of the MySQL server. (MySQL 5.0 and up only)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A unit-testing facility is provided so that individual unit test
+ programs can be created for storage engines and plugins. (MySQL
+ 5.1 and up only)
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Test suite programs can be found in these locations:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ For a source distribution, <command>mysqltest</command> is in
+ the <filename>client</filename> directory. For a binary
+ distribution, it is in the MySQL <filename>bin</filename>
+ directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ For a source distribution, <command>mysql_client_test</command>
+ is in the <filename>tests</filename> directory. For a binary
+ distribution, it is in the MySQL <filename>bin</filename>
+ directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The other programs are located in the
+ <filename>mysql-test</filename> directory. For a source
+ distribution, <filename>mysql-test</filename> is found under the
+ source tree root. For a binary distribution, the location of
+ <filename>mysql-test</filename> depends on the layout used for
+ the distribution format.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ <emphasis role="bold">Test Framework Directories and
+ Files</emphasis>
+ </para>
+
+ <para>
+ The test suite is located in the <filename>mysql-test</filename>
+ directory, which contains the following components:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The <command>mysql-test-run.pl</command> and
+ <command>mysql-stress-test.pl</command> programs that are used
+ for running tests.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <filename>t</filename> directory contains test case input
+ files. A test case file might also have option files associated
+ with it.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A file name of the form
+
<filename><replaceable>test_name</replaceable>.test</filename>
+ is a test case file for a test named
+ <replaceable>test_name</replaceable>. For example,
+ <filename>subquery.test</filename> is the test case file for
+ the test named <literal>subquery</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A file name of the form
+
<filename><replaceable>test_name</replaceable>-master.opt</filename>
+ provides options to associate with the named test case.
+ <literal>mysql-test-run.pl</literal> restarts the server
+ with the options given in the file if the options are
+ different from those required for the currently running
+ server.
+ </para>
+
+ <para>
+ Note that the <filename>-master.opt</filename> file is used
+ for the <quote>main</quote> server of a test, even if no
+ replication is involved.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A file name of the form
+
<filename><replaceable>test_name</replaceable>-slave.opt</filename>
+ provides slave options.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A file name of the form
+
<filename><replaceable>test_name</replaceable>-im.opt</filename>
+ provides Instance Manager options.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <filename>disabled.def</filename> file contains
+ information about deferred/disabled tests. When a test is
+ failing because of a bug in the server and you want it to be
+ ignored by <command>mysql-test-run.pl</command>, list the
+ test in this file.
+ </para>
+
+ <para>
+ The format of a line in the
+ <filename>disabled.def</filename> file looks like this,
+ where fields are separated by one or more spaces (Tab
+ characters are not allowed):
+ </para>
+
+<programlisting>
+<replaceable>test_name</replaceable> :
BUG#<replaceable>nnnnn</replaceable>
<replaceable>YYYY-MM-DD</replaceable>
<replaceable>disabler</replaceable>
<replaceable>comment</replaceable>
+</programlisting>
+
+ <para>
+ Example:
+ </para>
+
+<programlisting>
+rpl_row_blob_innodb : BUG#18980 2006-04-10 kent Test fails randomly
+</programlisting>
+
+ <para>
+ <replaceable>test_name</replaceable> is the test case name.
+
<literal>BUG#<replaceable>nnnnn</replaceable></literal>
+ indicates the bug related to the test that causes it to fail
+ (and thus requires it to be disabled).
+ <replaceable>disabler</replaceable> is the name of the
+ person that disabled the test.
+ <replaceable>comment</replaceable> normally provides a
+ reason why the test was disabled.
+ </para>
+
+ <para>
+ A comment line can be written in the file by beginning the
+ line with a <quote><literal>#</literal></quote>
character.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <filename>r</filename> directory contains test case result
+ files:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A file name of the form
+
<filename><replaceable>test_name</replaceable>.result</filename>
+ is the expected result for the named test case. A file
+
<filename>r/<replaceable>test_name</replaceable>.result</filename>
+ is the output that corresponds to the input in the test case
+ file
+
<filename>t/<replaceable>test_name</replaceable>.test</filename>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A file name of the form
+
<filename><replaceable>test_name</replaceable>.reject</filename>
+ contains output for the named test case if the test fails.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ For a test case that succeeds, the <filename>.result</filename>
+ file represents both the expected and actual result. For a test
+ case that fails, the <filename>.result</filename> file
+ represents the expected result, and the
+ <filename>.reject</filename> file represents the actual result.
+ </para>
+
+ <para>
+ If a <filename>.reject</filename> file is created because a test
+ fails, <command>mysql-test-run.pl</command> removes the file
+ later the next time the test succeeds.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <filename>include</filename> directory contains files that
+ are included by test case files using the
+ <literal>source</literal> command. These include files
+ encapsulate operations of varying complexity into a single file
+ so that you can perform the operations in a single step. See
+ <xref linkend="writing-tests-include-files"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <filename>lib</filename> directory contains library files
+ used by <command>mysql-test-run.pl</command>, and database
+ initialization SQL code.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <filename>std_data</filename> directory contains data files
+ used by some of the tests.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <filename>var</filename> directory is used during test runs
+ for various kinds of files: log files, temporary files, trace
+ files, Unix socket files for the servers started during the
+ tests, and so forth. This directory cannot be shared by
+ simultaneous test runs.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Unit test-related files are located in the
+ <filename>unittest</filename> directory. Additional files specific
+ to storage engines and plugins may be present under the
+ subdirectories of the <filename>storage</filename> or
+ <filename>plugin</filename> directories.
+ </para>
+
+ <para>
+ <emphasis role="bold">Test Execution and Evaluation</emphasis>
+ </para>
+
+ <para>
+ There are a number of targets in the top-level
+ <filename>Makefile</filename> that can be used to run sets of tests.
+ <command>make test</command> runs all the tests. Other targets run
+ subsets of the tests, or run tests with specific options for the
+ test programs. Have a look at the <filename>Makefile</filename> to
+ see what targets are available.
+ </para>
+
+ <para>
+ A <quote>test case</quote> is a single file. The case might contain
+ multiple individual test commands. If any individual command fails,
+ the entire test case is considered to fail. Note that
+ <quote>fail</quote> means <quote>does not produce the expected
+ result.</quote> It does <emphasis>not</emphasis> necessarily mean
+ <quote>executes without error,</quote> because some tests are
+ written precisely to verify that an illegal statement does in fact
+ produce an error. In such an instance, if the statement executes
+ successfully without producing the expected error, that is
+ considered failure of the test.
+ </para>
+
+ <para>
+ Test case output (the test result) consists of:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Input SQL statements and their output. Each statement is written
+ to the result followed by its output. Columns in output
+ resulting from SQL statements are separated by tab characters.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The result from <command>mysqltest</command> commands such as
+ <literal>echo</literal> and <literal>exec</literal>. The
+ commands themselves are not echoed to the result, only their
+ output.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The <literal>disable_query_log</literal> and
+ <literal>enable_query_log</literal> commands control logging of
+ input SQL statements. The <literal>disable_result_log</literal> and
+ <literal>enable_result_log</literal> commands control logging of SQL
+ statement results, and warning or error messages resulting from
+ those statements.
+ </para>
+
+ <para>
+ <command>mysqltest</command> reads a test case file from its
+ standard input by default. The <option>--test-file</option> or
+ <option>-x</option> option can be given to name a test case file
+ explicitly.
+ </para>
+
+ <para>
+ <command>mysqltest</command> writes test case output to the standard
+ output by default. The <option>--result-file</option> or
+ <option>-R</option> option can be used to indicate the location of
+ the result file. That option, together with the
+ <option>--record</option> option, determine how
+ <command>mysqltest</command> treats the test actual and expected
+ results for a test case:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If the test produces no results, <command>mysqltest</command>
+ exits with an error message to that effect.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Otherwise, if <option>--result-file</option> is not given,
+ <command>mysqltest</command> sends test results to the standard
+ output.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ With <option>--result-file</option> but not
+ <option>--record</option>, <command>mysqltest</command>
reads
+ the expected results from the given file and compares them with
+ the actual results. If the results do not match,
+ <command>mysqltest</command> writes a
+ <filename>.reject</filename> file in the same directory as the
+ result file and exits with an error.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ With both <option>--result-file</option> and
+ <option>--record</option>, <command>mysqltest</command>
updates
+ the given file by writing the actual test results to it.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ <command>mysqltest</command> itself knows nothing of the
+ <filename>t</filename> and <filename>r</filename> directories
under
+ the <filename>mysql-test</filename> directory. The use of files in
+ those directories is a convention that is used by
+ <command>mysql-test-run.pl</command>, which invokes
+ <command>mysqltest</command> with the appropriate options for each
+ test case to tell <command>mysqltest</command> where to read input
+ and write output.
+ </para>
+
+ <section id="tests-system-requirement">
+
+ <title>Test Framework System Requirements</title>
+
+ <para>
+ The <command>mysqltest</command> and
+ <command>mysql_client_test</command> programs are written in C and
+ are available on any system where MySQL itself can be compiled, or
+ for which a binary MySQL distribution is avaiable.
+ </para>
+
+ <para>
+ Other parts of the test framework such as
+ <command>mysql-test-run.pl</command> are Perl scripts and should
+ run on systems with Perl installed.
+ </para>
+
+ <para>
+ <command>mysqltest</command> uses the
<command>diff</command>
+ program to compare expected and actual test results. If
+ <command>diff</command> is not found,
<command>mysqltest</command>
+ writes an error message and dumps the entire contents of the
+ <filename>.result</filename> and
<filename>.reject</filename>
+ files so that you can try to determine why a test did not succeed.
+ If your system does not have <command>diff</command>, you may be
+ able to obtain it from one of these sites:
+ </para>
+
+<programlisting>
+<ulink url="http://www.gnu.org/software/diffutils/diffutils.html"/>
+<ulink url="http://gnuwin32.sourceforge.net/packages/diffutils.htm"/>
+</programlisting>
+
+ </section>
+
+ <section id="tests-and-ssl">
+
+ <title>The Test Framework and SSL</title>
+
+ <para>
+ When <command>mysql-test-run.pl</command> starts, it checks
+ whether <command>mysqld</command> supports SSL connections:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If <command>mysqld</command> supports SSL,
+ <command>mysql-test-run.pl</command> starts it with the proper
+ <option>--ssl-<replaceable>xxx</replaceable></option>
options
+ that enable it to accept SSL connections for those test cases
+ that require secure connections (those with <quote>ssl</quote>
+ in their name). As <command>mysql-test-run.pl</command> runs
+ test cases, a secure connection to <command>mysqld</command>
+ is initiated for those cases that require one. For those test
+ cases that do not require SSL, an unencrypted connection is
+ initiated.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If <command>mysqld</command> does not support SSL,
+ <command>mysql-test-run.pl</command> skips those test cases
+ that require secure connections.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ If <command>mysql-test-run.pl</command> is started with the
+ <option>--ssl</option> option, it sets up a secure conection for
+ all test cases. In this case, if <command>mysqld</command> does
+ not support SSL, <command>mysql-test-run.pl</command> exits with
+ an error message: <literal>Couldn't find support for SSL</literal>
+ </para>
+
+ <para>
+ For <command>mysql-test-run</command> (the shell version), the
+ <option>--with-openssl</option> option corresponds to the
+ <option>--ssl</option> option for
+ <command>mysql-test-run.pl</command>.
+ </para>
+
+ </section>
+
+ <section id="reporting-mysqltest-bugs">
+
+ <title>How to Report Bugs in the MySQL Test Suite</title>
+
+ <para>
+ If test cases from the test suite fail, you should do the
+ following:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Do not file a bug report before you have found out as much as
+ possible about what when wrong. See the instructions at
+ <ulink url="&base-url-generic-refman;/bug-reports"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Make sure to include the output of
+ <command>mysql-test-run.pl</command>, as well as contents of
+ all <filename>.reject</filename> files in the
+ <filename>mysql-test/r</filename> directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Check whether an individual test in the test suite also fails
+ when run on its own:
+ </para>
+
+<programlisting>
+shell> <userinput>cd mysql-test</userinput>
+shell> <userinput>./mysql-test-run.pl
<replaceable>test_name</replaceable></userinput>
+</programlisting>
+
+ <para>
+ If this fails, you should configure MySQL with
+ <option>--with-debug</option> and run
+ <command>mysql-test-run.pl</command> with the
+ <option>--debug</option> option. If this also fails, send the
+ trace file
+ <filename>mysql-test/var/tmp/master.trace</filename> to
+ <ulink url="&base-url-uploads;"/> so that we can examine it.
+ Please remember to also include a full description of your
+ system, the version of the <command>mysqld</command> binary
+ and how you compiled it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Run <command>mysql-test-run.pl</command> with the
+ <option>--force</option> option to see whether any other tests
+ fail.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you have compiled MySQL yourself, check the MySQL Reference
+ Manual to see whether there are any platform-specific issues
+ for your system. There might be configuration workarounds to
+ deal with the problems that you observe. Also, consider using
+ one of the binaries we have compiled for you at
+ <ulink url="&base-url-downloads;"/>. All our standard binaries
+ should pass the test suite!
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you get an error such as <literal>Result length
+ mismatch</literal> or <literal>Result content
+ mismatch</literal> it means that the output of the test was
+ not an exact match for the expected output. This could be a
+ bug in MySQL or it could be that your version of
+ <command>mysqld</command> produces slightly different results
+ under some circumstances.
+ </para>
+
+ <para>
+ The results file is located in the <filename>r</filename>
+ directory and has a name with a <filename>.result</filename>
+ extension. A failed test result is put in a file with the same
+ basename as the result file and a <filename>.reject</filename>
+ extension. If your test case is failing, you should use
+ <command>diff</command> to compare the
+ <filename>.result</filename> and
<filename>.reject</filename>
+ files. If you cannot see how they are different, examine both
+ with <command>od -c</command> and also check their lengths.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If a test fails completely, you should check the logs file in
+ the <filename>mysql-test/var/log</filename> directory for
+ hints of what went wrong.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you have compiled MySQL with debugging, you can try to
+ debug test failures by running
+ <command>mysql-test-run.pl</command> with either or both of
+ the <option>--gdb</option> and <option>--debug</option>
+ options.
+ </para>
+
+ <para>
+ If you have not compiled MySQL for debugging you should
+ probably do so by specifying the <option>--with-debug</option>
+ option when you invoke <command>configure</command>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+</chapter>
Added: trunk/mysqltest-2.0/introduction.xml
===================================================================
--- trunk/mysqltest-2.0/introduction.xml (rev 0)
+++ trunk/mysqltest-2.0/introduction.xml 2009-11-04 21:04:47 UTC (rev 17451)
Changed blocks: 1, Lines Added: 178, Lines Deleted: 0; 7351 bytes
@@ -0,0 +1,178 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % all.entities SYSTEM "all-entities.ent">
+ %all.entities;
+]>
+<chapter id="mysqltest-introduction">
+
+ <title>Introduction to the MySQL Test Framework</title>
+
+ <indexterm>
+ <primary>test cases</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>unit tests</primary>
+ </indexterm>
+
+ <para>
+ MySQL distributions include a set of test cases and programs for
+ running them. These tools constitute the MySQL test framework that
+ provides a means for verifying that MySQL Server and its client
+ programs operate according to expectations. The test cases consist
+ mostly of SQL statements, but can also use test language constructs
+ that control how to run tests and verify their results. As of MySQL
+ 5.1, distributions also provide facilities for running unit tests
+ and creating new unit tests.
+ </para>
+
+ <para>
+ This document describes the components of the MySQL test framework,
+ how the test programs work, and the language used for writing test
+ cases. It also provides a tutorial for developing test cases and
+ executing them.
+ </para>
+
+ <para>
+ The application that runs the test suite is named
+ <command>mysql-test-run.pl</command>. Its location is the
+ <filename>mysql-test</filename> directory, which is present both in
+ source and binary MySQL Server distributions.
+ </para>
+
+ <note>
+ <para>
+ There are actually two scripts for running the test suite. The
+ <command>mysql-test-run.pl</command> Perl script is the main
+ application used to run the test suite. It invokes
+ <command>mysqltest</command> to run individual test cases. Prior
+ to MySQL 4.1, a similar shell script,
+ <command>mysql-test-run</command>, can be used instead.
+ <command>mysql-test-run.pl</command> is the script name used in
+ discussion and examples throughout this document. If you are using
+ a version of MySQL older than MySQL 4.1, substitute
+ <command>mysql-test-run</command> appropriately.
+ </para>
+ </note>
+
+ <para>
+ The <command>mysql-test-run.pl</command> application starts MySQL
+ servers, restarts them as necessary when a specific test case needs
+ different start arguments, and presents the test result. For each
+ test case, <command>mysql-test-run.pl</command> invokes the
+ <command>mysqltest</command> program (also referred to as the
+ <quote>test engine</quote>) to read the test case file, intepret the
+ test language constructs, and send SQL statements to the server.
+ </para>
+
+ <para>
+ Input for each test case is stored in a file, and the expected
+ result from running the test is stored in another file. The expected
+ result can be compared to the actual result produced by running a
+ test to verify proper processing of the input by MySQL.
+ </para>
+
+ <para>
+ For a MySQL source distribution,
+ <command>mysql-test-run.pl</command> is located in the
+ <filename>mysql-test</filename> directory, and
+ <command>mysqltest</command> is located in the
+ <filename>client</filename> directory. The
+ <filename>mysql-test</filename> and
<filename>client</filename>
+ directories are located in the root directory of the distribution.
+ </para>
+
+ <para>
+ For a MySQL binary distribution,
+ <command>mysql-test-run.pl</command> is located in the
+ <filename>mysql-test</filename> directory, and
+ <command>mysqltest</command> is located in the same directory where
+ other client programs such as <command>mysql</command> or
+ <command>mysqladmin</command> are installed. The locations of the
+ <filename>mysql-test</filename> and
<filename>client</filename>
+ directories depend on the layout used for the distribution format.
+ </para>
+
+ <para>
+ Within the <filename>mysql-test</filename> directory, test case
+ input files and result files are stored in the
+ <filename>t</filename> and <filename>r</filename>
directories,
+ respectively. The input and result files have the same basename,
+ which is the test name, but have extensions of
+ <filename>.test</filename> and <filename>.result</filename>,
+ respectively. For example, for a test named <quote>decimal,</quote>
+ the input and result files are
+ <filename>mysql-test/t/decimal.test</filename> and
+ <filename>mysql-test/r/decimal.result</filename>.
+ </para>
+
+ <para>
+ Each test file is referred to as one test case, but usually consists
+ of a sequence of related tests. An unexpected failure of a single
+ statement in a test case makes the test fail.
+ </para>
+
+ <para>
+ There are several ways a test case can fail:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The <command>mysqltest</command> test engine checks the result
+ codes from executing each SQL statement in the test input. If
+ the failure is unexpected, the test case fails.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A test case can fail if an error was expected but did not occur
+ (for example, if an SQL statement succeeded when it should have
+ failed).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The test case can fail by producing incorrect output. As a test
+ runs, it produces output (the results from
+ <literal>SELECT</literal>, <literal>SHOW</literal>, and
other
+ statements). This output is compared to the expected result
+ found in the <filename>mysql-test/r</filename> directory (in a
+ file with a <filename>.result</filename> suffix). If the
+ expected and actual results differ, the test case fails. The
+ actual test result is written to a file in the
+ <filename>mysql-test/r</filename> directory with a
+ <filename>.reject</filename> suffix, and the difference between
+ the <filename>.result</filename> and
+ <filename>.reject</filename> files is presented for evaluation.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ This method of checking test results puts some restrictions on how
+ test cases can be written. For example, the result cannot contain
+ information that varies from run to run, such as the current time.
+ However, if the information that varies is unimportant for test
+ evaluation, there are ways to instruct the test engine to replace
+ those fields in the output with fixed values.
+ </para>
+
+ <para>
+ Because the test cases consist mostly of SQL statements in a text
+ file, there is no direct support for test cases that are written in
+ C, Java, or other languages. Such tests are not within the scope of
+ this test framework. But the framework does support executing your
+ own scripts and initiating them with your own data. Also, a test
+ case can execute an external program, so in some respects the test
+ framework can be extended for uses other than testing SQL
+ statements.
+ </para>
+
+</chapter>
Added: trunk/mysqltest-2.0/legalnotice.en.xml
===================================================================
--- trunk/mysqltest-2.0/legalnotice.en.xml (rev 0)
+++ trunk/mysqltest-2.0/legalnotice.en.xml 2009-11-04 21:04:47 UTC (rev 17451)
Changed blocks: 1, Lines Added: 85, Lines Deleted: 0; 3948 bytes
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<legalnotice>
+
+<!--
+ The role attribute for each top-level legalnotice element determines
+ the context in which the element is used: 1) no role attribute: part
+ of the default legalnotice, used for regular documentation that is
+ not released under GPL; 2) role = legalnotice-gpl: for man page
+ legalnotices, which are released under GPL; 3) role =
+ legalnotice-all: included in legalnotice for all documentation.
+-->
+
+ <para>
+ Copyright 2006-2008 MySQL AB, 2009 Sun Microsystems, Inc.
+ </para>
+
+ <para>
+ This documentation is NOT distributed under a GPL license. Use of
+ this documentation is subject to the following terms: You may create
+ a printed copy of this documentation solely for your own personal
+ use. Conversion to other formats is allowed as long as the actual
+ content is not altered or edited in any way. You shall not publish
+ or distribute this documentation in any form or on any media, except
+ if you distribute the documentation in a manner similar to how Sun
+ disseminates it (that is, electronically for download on a Web site
+ with the software) or on a CD-ROM or similar medium, provided
+ however that the documentation is disseminated together with the
+ software on the same medium. Any other use, such as any
+ dissemination of printed copies or use of this documentation, in
+ whole or in part, in another publication, requires the prior written
+ consent from an authorized representative of Sun Microsystems, Inc.
+ Sun Microsystems, Inc. and MySQL AB reserve any and all rights to
+ this documentation not expressly granted above.
+ </para>
+
+ <para role="legalnotice-gpl">
+ Copyright 2007-2008 MySQL AB, 2009 Sun Microsystems, Inc.
+ </para>
+
+ <para role="legalnotice-gpl">
+ This documentation is free software; you can redistribute it and/or
+ modify it only under the terms of the GNU General Public License as
+ published by the Free Software Foundation; version 2 of the License.
+ </para>
+
+ <para role="legalnotice-gpl">
+ This documentation is distributed in the hope that it will be
+ useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+ of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ General Public License for more details.
+ </para>
+
+ <para role="legalnotice-gpl">
+ You should have received a copy of the GNU General Public License
+ along with the program; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301 USA or see http://www.gnu.org/licenses/.
+ </para>
+
+ <para>
+ For more information on the terms of this license, for details on
+ how the MySQL documentation is built and produced, or if you are
+ interested in doing a translation, please contact the
+ <ulink url="http://www.mysql.com/company/contact/">Documentation
+ Team</ulink>.
+ </para>
+
+ <para>
+ If you want help with using MySQL, please visit either the
+ <ulink url="http://forums.mysql.com">MySQL Forums</ulink> or
+ <ulink url="http://lists.mysql.com">MySQL Mailing Lists</ulink>
+ where you can discuss your issues with other MySQL users.
+ </para>
+
+ <para>
+ For additional documentation on MySQL products, including
+ translations of the documentation into other languages, and
+ downloadable versions in variety of formats, including HTML, CHM,
+ and PDF formats, see <ulink url="http://dev.mysql.com/doc">MySQL
+ Documentation Library</ulink>.
+ </para>
+
+</legalnotice>
Added: trunk/mysqltest-2.0/mysqltest.xml
===================================================================
--- trunk/mysqltest-2.0/mysqltest.xml (rev 0)
+++ trunk/mysqltest-2.0/mysqltest.xml 2009-11-04 21:04:47 UTC (rev 17451)
Changed blocks: 1, Lines Added: 61, Lines Deleted: 0; 1692 bytes
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % all.entities SYSTEM "all-entities.ent">
+ %all.entities;
+]>
+<book id="mysql-test-framework" lang="en">
+
+ <title>The MySQL Test Framework</title>
+
+ <bookinfo>
+
+ <abstract>
+
+ <para>
+ This manual describes the MySQL test framework.
+ </para>
+
+ <para>
+ Document generated on:
+
+<?dbtimestamp format="Y-m-d"?>
+
+ <remark role="repository.revision"/>
+ </para>
+
+ </abstract>
+
+ <xi:include href="legalnotice.en.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+ </bookinfo>
+
+ <xi:include href="preface.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+ <xi:include href="introduction.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+ <xi:include href="components.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+ <xi:include href="running-tests.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+ <xi:include href="writing-tests.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+ <xi:include href="programs.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+ <xi:include href="command-reference.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+ <xi:include href="unit-test.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+ <index/>
+
+</book>
Added: trunk/mysqltest-2.0/preface.xml
===================================================================
--- trunk/mysqltest-2.0/preface.xml (rev 0)
+++ trunk/mysqltest-2.0/preface.xml 2009-11-04 21:04:47 UTC (rev 17451)
Changed blocks: 1, Lines Added: 39, Lines Deleted: 0; 1554 bytes
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % all.entities SYSTEM "all-entities.ent">
+ %all.entities;
+]>
+<preface id="preface">
+
+ <title>Preface</title>
+
+ <para>
+ MySQL distributions include a set of test cases and programs for
+ running them. These tools constitute the MySQL test framework that
+ provides a means for verifying that MySQL Server and its client
+ programs operate according to expectations. The test cases consist
+ mostly of SQL statements, but can also use test language constructs
+ that control how to run tests and verify their results.
+ </para>
+
+ <para>
+ This manual describes the MySQL test framework. It describes the
+ programs used to run tests and the language used to write test
+ cases.
+ </para>
+
+ <para>
+ Much of the content of this manual is based on material originally
+ written by (in alphabetical order) Omer BarNir, Kent Boortz, and
+ Matthias Leich.
+ </para>
+
+ <para>
+ People within MySQL AB who work with MySQL testing include Omer
+ BarNir and Matthias Leich (test case development, test standards
+ development) and Magnus Svensson (testing tools development).
+ </para>
+
+</preface>
Added: trunk/mysqltest-2.0/programs.xml
===================================================================
--- trunk/mysqltest-2.0/programs.xml (rev 0)
+++ trunk/mysqltest-2.0/programs.xml 2009-11-04 21:04:47 UTC (rev 17451)
Changed blocks: 1, Lines Added: 4840, Lines Deleted: 0; 147178 bytes
@@ -0,0 +1,4840 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % all.entities SYSTEM "all-entities.ent">
+ %all.entities;
+]>
+<chapter id="test-programs">
+
+ <title>MySQL Test Programs</title>
+
+ <remark>
+ Note: The sections here that describe each program are written using
+ refentry markup so that the content can be included in the MySQL
+ Reference Manual and used for generating Unix man pages more easily.
+ </remark>
+
+ <para>
+ This chapter describes the test programs that run test cases. For
+ information about the language used for writing test cases, see
+ <xref linkend="mysqltest-reference"/>.
+ </para>
+
+ <para>
+ The test suite uses the following programs:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The <command>mysql-test-run.pl</command> Perl script is the main
+ application used to run the MySQL test suite. It invokes
+ <command>mysqltest</command> to run individual test cases.
+ (Prior to MySQL 4.1, a similar shell script,
+ <command>mysql-test-run</command>, can be used instead.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <command>mysqltest</command> runs test cases. A version named
+ <command>mysqltest_embedded</command> is similar but is built
+ with support for the <literal>libmysqld</literal> embedded
+ server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <command>mysql_client_test</command> program is used for
+ testing aspects of the MySQL client API that cannot be tested
+ using <command>mysqltest</command> and its test language.
+ <command>mysql_client_test_embedded</command> is similar but
+ used for testing the embedded server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <command>mysql-stress-test.pl</command> Perl script performs
+ stress-testing of the MySQL server. (MySQL 5.0 and up only)
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <refentry id="mysqltest">
+
+ <indexterm>
+ <primary>mysqltest</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>mysqltest_embedded</primary>
+ </indexterm>
+
+ <refmeta>
+ <refentrytitle><command>mysqltest</command></refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ <refmiscinfo class="manual">MySQL Database System</refmiscinfo>
+ <refmiscinfo class="source">MySQL</refmiscinfo>
+ <refmiscinfo class="refman">Program to Run Test Cases</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>mysqltest</refname>
+
+ <refpurpose>program to run test cases</refpurpose>
+ </refnamediv>
+
+ <refnamediv>
+ <refname>mysqltest_embedded</refname>
+
+ <refpurpose>program to run embedded test cases</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>mysqltest [<replaceable>options</replaceable>]
[<replaceable>db_name</replaceable>]</command>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>mysqltest_embedded
[<replaceable>options</replaceable>]
[<replaceable>db_name</replaceable>]</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection id="mysqltest-description">
+
+ <title>Description</title>
+
+ <para>
+ The <command>mysqltest</command> program runs a test case
+ against a MySQL server and optionally compares the output with a
+ result file. This program reads input written in a special test
+ language. Typically, you invoke <command>mysqltest</command> via
+ <command>mysql-test-run.pl</command> rather than invoking it
+ directly.
+ </para>
+
+ <para>
+ <command>mysqltest_embedded</command> is similar but is built
+ with support for the <literal>libmysqld</literal> embedded
+ server.
+ </para>
+
+ <para>
+ Features of <command>mysqltest</command>:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Can send SQL statements to MySQL servers for execution
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Can execute external shell commands
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Can test whether the result from an SQL statement or shell
+ command is as expected
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Can connect to one or more standalone
+ <command>mysqld</command> servers and switch between
+ connections
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Can connect to an embedded server
+ (<literal>libmysqld</literal>), if MySQL is compiled with
+ support for <literal>libmysqld</literal>. (In this case, the
+ executable is named <command>mysqltest_embedded</command>
+ rather than <command>mysqltest</command>.)
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ By default, <command>mysqltest</command> reads the test case on
+ the standard input. To run <command>mysqltest</command> this
+ way, you normally invoke it like this:
+ </para>
+
+<programlisting>
+shell> <userinput>mysqltest [<replaceable>options</replaceable>]
[<replaceable>db_name</replaceable>] <
<replaceable>test_file</replaceable></userinput>
+</programlisting>
+
+ <para>
+ You can also name the test case file with a
+
<option>--test-file=<replaceable>file_name</replaceable></option>
+ option.
+ </para>
+
+ <para>
+ The exit value from <command>mysqltest</command> is 0 for
+ success, 1 for failure, and 62 if it skips the test case (for
+ example, if after checking some preconditions it decides not to
+ run the test).
+ </para>
+
+ <remark role="note">
+ Also supports the standard SSL options. (And what else?)
+ </remark>
+
+ <para>
+ <command>mysqltest</command> supports the following options:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>help option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>help option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--help</option>, <option>-?</option>
+ </para>
+
+ <para>
+ Display a help message and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>basedir option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>basedir option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--basedir=<replaceable>dir_name</replaceable></option>,
+ <option>-b
<replaceable>dir_name</replaceable></option>
+ </para>
+
+ <para>
+ The base directory for tests.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>big-test option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>big-test option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--big-test</option>, <option>-B</option>
+ </para>
+
+ <para>
+ Define the <command>mysqltest</command> variable
+ <literal>$BIG_TEST</literal> as 1. This option was removed
+ in MySQL 4.1.23, 5.0.30, and 5.1.13.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>character-sets-dir option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>character-sets-dir option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--character-sets-dir=<replaceable>path</replaceable></option>
+ </para>
+
+ <para>
+ The directory where character sets are installed. This
+ option was added in MySQL 4.1.23, 5.0.32, and 5.1.13.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>compress option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>compress option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--compress</option>, <option>-C</option>
+ </para>
+
+ <para>
+ Compress all information sent between the client and the
+ server if both support compression.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>cursor-protocol option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>cursor-protocol option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--cursor-protocol</option>
+ </para>
+
+ <para>
+ Use cursors for prepared statements (implies
+ <option>--ps-protocol</option>). This option was added in
+ MySQL 5.0.19.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>database option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>database option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--database=<replaceable>db_name</replaceable></option>,
+ <option>-D
<replaceable>db_name</replaceable></option>
+ </para>
+
+ <para>
+ The default database to use.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>debug option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>debug option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--debug[=<replaceable>debug_options</replaceable>]</option>,
+
<option>-#[<replaceable>debug_options</replaceable>]</option>
+ </para>
+
+ <para>
+ Write a debugging log if MySQL is built with debugging
+ support. The default
+ <replaceable>debug_options</replaceable> value is
+ <literal>'d:t:S:i:O,/tmp/mysqltest.trace'</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="option_mysqltest_debug-check">
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>debug-check option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>debug-check option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--debug-check</option>
+ </para>
+
+ <para>
+ Print some debugging information when the program exits.
+ This option was added in MySQL 5.1.21.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="option_mysqltest_debug-info">
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>debug-info option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>debug-info option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--debug-info</option>
+ </para>
+
+ <para>
+ Print debugging information and memory and CPU usage
+ statistics when the program exits. This option was added in
+ MySQL 5.1.14.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>host option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>host option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--host=<replaceable>host_name</replaceable></option>,
+ <option>-h
<replaceable>host_name</replaceable></option>
+ </para>
+
+ <para>
+ Connect to the MySQL server on the given host.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>include option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>include option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--include=<replaceable>file_name</replaceable></option>,
+ <option>-i
<replaceable>file_name</replaceable></option>
+ </para>
+
+ <para>
+ Include the contents of the given file before processing the
+ contents of the test file. The included file should have the
+ same format as other <command>mysqltest</command> test
+ files. This option has the same effect as putting a
+ <literal>--source
+ <replaceable>file_name</replaceable></literal> command as
+ the first line of the test file. This option was added in
+ MySQL 4.1.23, 5.0.30, and 5.1.7.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>logdir option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>logdir option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--logdir=<replaceable>dir_name</replaceable></option>
+ </para>
+
+ <para>
+ The directory to use for log files. This option was added in
+ MySQL 5.1.14.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>mark-progress option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>mark-progress option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--mark-progress</option>
+ </para>
+
+ <para>
+ Write the line number and elapsed time to
+
<filename><replaceable>test_file</replaceable>.progress</filename>.
+ This option was added in MySQL 4.1.23, 5.0.30, and 5.1.12.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>max-connect-retries option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>max-connect-retries option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--max-connect-retries=<replaceable>num</replaceable></option>
+ </para>
+
+ <para>
+ The maximum number of connection attempts when connecting to
+ server. This option was added in MySQL 4.1.23, 5.0.23, and
+ 5.1.11.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>no-defaults option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>no-defaults option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--no-defaults</option>
+ </para>
+
+ <para>
+ Do not read default options from any option files.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>password option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>password option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--password[=<replaceable>password</replaceable>]</option>,
+
<option>-p[<replaceable>password</replaceable>]</option>
+ </para>
+
+ <para>
+ The password to use when connecting to the server. If you
+ use the short option form (<option>-p</option>), you
+ <emphasis>cannot</emphasis> have a space between the option
+ and the password. If you omit the
+ <replaceable>password</replaceable> value following the
+ <option>--password</option> or <option>-p</option>
option on
+ the command line, you are prompted for one.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>port option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>port option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--port=<replaceable>port_num</replaceable></option>,
+ <option>-P
<replaceable>port_num</replaceable></option>
+ </para>
+
+ <para>
+ The TCP/IP port number to use for the connection.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>ps-protocol option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>ps-protocol option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--ps-protocol</option>
+ </para>
+
+ <para>
+ Use the prepared-statement protocol for communication.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>quiet option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>quiet option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--quiet</option>
+ </para>
+
+ <para>
+ Suppress all normal output. This is a synonym for
+
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>silent option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>silent option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--silent</option>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>record option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>record option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--record</option>, <option>-r</option>
+ </para>
+
+ <remark role="todo">
+ What happens if no --result-file option is given?
+ </remark>
+
+ <para>
+ Record the output that results from running the test file
+ into the file named by the <option>--result-file</option>
+ option, if that option is given.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>result-file option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>result-file option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--result-file=<replaceable>file_name</replaceable></option>,
+ <option>-R
<replaceable>file_name</replaceable></option>
+ </para>
+
+ <para>
+ This option specifies the file for test case expected
+ results. <option>--result-file</option>, together with
+ <option>--record</option>, determines how
+ <command>mysqltest</command> treats the test actual and
+ expected results for a test case:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If the test produces no results,
+ <command>mysqltest</command> exits with an error message
+ to that effect.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Otherwise, if <option>--result-file</option> is not
+ given, <command>mysqltest</command> sends test results
+ to the standard output.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ With <option>--result-file</option> but not
+ <option>--record</option>,
<command>mysqltest</command>
+ reads the expected results from the given file and
+ compares them with the actual results. If the results do
+ not match, <command>mysqltest</command> writes a
+ <filename>.reject</filename> file in the same directory
+ as the result file and exits with an error.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ With both <option>--result-file</option> and
+ <option>--record</option>,
<command>mysqltest</command>
+ updates the given file by writing the actual test
+ results to it.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>server-arg option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>server-arg option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--server-arg=<replaceable>value</replaceable></option>,
+ <option>-A <replaceable>value</replaceable></option>
+ </para>
+
+ <para>
+ Pass the argument as an argument to the embedded server. For
+ example, <option>--server-arg=--tmpdir=/tmp</option> or
+ <option>--server-arg=--core</option>. Up to 64 arguments can
+ be given.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>server-file option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>server-file option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--server-file=<replaceable>file_name</replaceable></option>,
+ <option>-F
<replaceable>file_name</replaceable></option>
+ </para>
+
+ <para>
+ Read arguments for the embedded server from the given file.
+ The file should contain one argument per line.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>silent option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>silent option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--silent</option>, <option>-s</option>
+ </para>
+
+ <para>
+ Suppress all normal output.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>skip-safemalloc option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>skip-safemalloc option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--skip-safemalloc</option>
+ </para>
+
+ <para>
+ Do not use memory allocation checking.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>sleep option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>sleep option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--sleep=<replaceable>num</replaceable></option>,
+ <option>-T <replaceable>num</replaceable></option>
+ </para>
+
+ <para>
+ Cause all <literal>sleep</literal> commands in the test case
+ file to sleep <replaceable>num</replaceable> seconds. This
+ option does not affect <literal>real_sleep</literal>
+ commands.
+ </para>
+
+ <para>
+ As of MySQL 5.0.23, an option value of 0 can be used, which
+ effectively disables <literal>sleep</literal> commands in
+ the test case.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>socket option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>socket option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--socket=<replaceable>path</replaceable></option>,
+ <option>-S <replaceable>path</replaceable></option>
+ </para>
+
+ <para>
+ The socket file to use when connecting to
+ <literal>localhost</literal> (which is the default host).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>sp-protocol option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>sp-protocol option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--sp-protocol</option>
+ </para>
+
+ <para>
+ Execute DML statements within a stored procedure. For every
+ DML statement, <command>mysqltest</command> creates and
+ invokes a stored procedure that executes the statement
+ rather than executing the statement directly. This option
+ was added in MySQL 5.0.19.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>test-file option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>test-file option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--test-file=<replaceable>file_name</replaceable></option>,
+ <option>-x
<replaceable>file_name</replaceable></option>
+ </para>
+
+ <para>
+ Read test input from this file. The default is to read from
+ the standard input.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>timer-file option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>timer-file option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--timer-file=<replaceable>file_name</replaceable></option>,
+ <option>-m
<replaceable>file_name</replaceable></option>
+ </para>
+
+ <para>
+ The file where the timing in microseconds is written.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>tmpdir option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>tmpdir option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--tmpdir=<replaceable>dir_name</replaceable></option>,
+ <option>-t
<replaceable>dir_name</replaceable></option>
+ </para>
+
+ <remark role="todo">
+ "put" = "created"?
+ </remark>
+
+ <para>
+ The temporary directory where socket files are put.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>user option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>user option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+
<option>--user=<replaceable>user_name</replaceable></option>,
+ <option>-u
<replaceable>user_name</replaceable></option>
+ </para>
+
+ <para>
+ The MySQL user name to use when connecting to the server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>verbose option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>verbose option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--verbose</option>, <option>-v</option>
+ </para>
+
+ <para>
+ Verbose mode. Print out more information what the program
+ does.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>version option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>version option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--version</option>, <option>-V</option>
+ </para>
+
+ <para>
+ Display version information and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysqltest</primary>
+ <secondary>view-protocol option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>view-protocol option</primary>
+ <secondary>mysqltest</secondary>
+ </indexterm>
+
+ <option>--view-protocol</option>
+ </para>
+
+ <para>
+ Every <literal>SELECT</literal> statement is wrapped inside
+ a view. This option was added in MySQL 5.0.19.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </refsection>
+
+ </refentry>
+
+ <refentry id="mysql-client-test">
+
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>mysql_client_test_embedded</primary>
+ </indexterm>
+
+ <refmeta>
+
<refentrytitle><command>mysql_client_test</command></refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ <refmiscinfo class="manual">MySQL Database System</refmiscinfo>
+ <refmiscinfo class="source">MySQL</refmiscinfo>
+ <refmiscinfo class="refman">Test Client API</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>mysql_client_test</refname>
+
+ <refpurpose>test client API</refpurpose>
+ </refnamediv>
+
+ <refnamediv>
+ <refname>mysql_client_test_embedded</refname>
+
+ <refpurpose>test client API for embedded server</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>mysql_client_test [<replaceable>options</replaceable>]
[<replaceable>test_name</replaceable>] ...</command>
+ </cmdsynopsis>
+
+ <cmdsynopsis>
+ <command>mysql_client_test_embedded
[<replaceable>options</replaceable>]
[<replaceable>test_name</replaceable>] ...</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection id="mysql-client-test-description">
+
+ <title>Description</title>
+
+ <para>
+ The <command>mysql_client_test</command> program is used for
+ testing aspects of the MySQL client API that cannot be tested
+ using <command>mysqltest</command> and its test language.
+ <command>mysql_client_test_embedded</command> is similar but
+ used for testing the embedded server. Both programs are run as
+ part of the test suite.
+ </para>
+
+ <para>
+ The source code for the programs can be found in in
+ <filename>test/mysql_client_test.c</filename> in a source
+ distribution. The program serves as a good source of examples
+ illustrating how to use various features of the client API.
+ </para>
+
+ <para>
+ <command>mysql_client_test</command> supports the following
+ options:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>help option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>help option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+ <option>--help</option>, <option>-?</option>
+ </para>
+
+ <para>
+ Display a help message and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>-b
<replaceable>dir_name</replaceable></option>,
+
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>basedir option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>basedir option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+
<option>--basedir=<replaceable>dir_name</replaceable></option>
+ </para>
+
+ <para>
+ The base directory for the tests.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>-t <replaceable>count</replaceable></option>,
+
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>count option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>count option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+
<option>--count=<replaceable>count</replaceable></option>
+ </para>
+
+ <para>
+ The number of times to execute the tests.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>database option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>database option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+
<option>--database=<replaceable>db_name</replaceable></option>,
+ <option>-D
<replaceable>db_name</replaceable></option>
+ </para>
+
+ <para>
+ The database to use.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>debug option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>debug option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+
<option>--debug[=<replaceable>debug_options</replaceable>]</option>,
+
<option>-#[<replaceable>debug_options</replaceable>]</option>
+ </para>
+
+ <para>
+ Write a debugging log if MySQL is built with debugging
+ support. The default
+ <replaceable>debug_options</replaceable> value is
+ <literal>'d:t:o,/tmp/mysql_client_test.trace'</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>-g
<replaceable>option</replaceable></option>,
+
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>getopt-ll-test option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>getopt-ll-test option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+
<option>--getopt-ll-test=<replaceable>option</replaceable></option>
+ </para>
+
+ <para>
+ Option to use for testing bugs in the
+ <literal>getopt</literal> library.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>host option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>host option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+
<option>--host=<replaceable>host_name</replaceable></option>,
+ <option>-h
<replaceable>host_name</replaceable></option>
+ </para>
+
+ <para>
+ Connect to the MySQL server on the given host.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>password option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>password option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+
<option>--password[=<replaceable>password</replaceable>]</option>,
+
<option>-p[<replaceable>password</replaceable>]</option>
+ </para>
+
+ <para>
+ The password to use when connecting to the server. If you
+ use the short option form (<option>-p</option>), you
+ <emphasis>cannot</emphasis> have a space between the option
+ and the password. If you omit the
+ <replaceable>password</replaceable> value following the
+
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>password option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>password option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+ <option>--password</option> or <option>-p</option>
option on
+ the command line, you are prompted for one.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>port option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>port option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+
<option>--port=<replaceable>port_num</replaceable></option>,
+ <option>-P
<replaceable>port_num</replaceable></option>
+ </para>
+
+ <para>
+ The TCP/IP port number to use for the connection.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>-A <replaceable>arg</replaceable></option>,
+
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>server-arg option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>server-arg option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+
<option>--server-arg=<replaceable>arg</replaceable></option>
+ </para>
+
+ <para>
+ Argument to send to the embedded server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>-T</option>, <option>--show-tests</option>
+ </para>
+
+ <para>
+ Show all test names.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>silent option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>silent option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+ <option>--silent</option>, <option>-s</option>
+ </para>
+
+ <para>
+ Be more silent.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>socket option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>socket option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+
<option>--socket=<replaceable>path</replaceable></option>,
+ <option>-S <replaceable>path</replaceable></option>
+ </para>
+
+ <para>
+ The socket file to use when connecting to
+ <literal>localhost</literal> (which is the default host).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>-c</option>, <option>--testcase</option>
+ </para>
+
+ <para>
+ The option may disable some code when run as a
+ <command>mysql-test-run.pl</command> test case.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>user option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>user option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+
<option>--user=<replaceable>user_name</replaceable></option>,
+ <option>-u
<replaceable>user_name</replaceable></option>
+ </para>
+
+ <para>
+ The MySQL user name to use when connecting to the server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>-v
<replaceable>dir_name</replaceable></option>,
+
+ <indexterm>
+ <primary>mysql_client_test</primary>
+ <secondary>vardir option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>vardir option</primary>
+ <secondary>mysql_client_test</secondary>
+ </indexterm>
+
+
<option>--vardir=<replaceable>dir_name</replaceable></option>
+ </para>
+
+ <para>
+ The data directory for tests. The default is
+ <filename>mysql-test/var</filename>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </refsection>
+
+ </refentry>
+
+ <refentry id="mysql-test-run-pl">
+
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ </indexterm>
+
+ <refmeta>
+
<refentrytitle><command>mysql-test-run.pl</command></refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ <refmiscinfo class="manual">MySQL Database System</refmiscinfo>
+ <refmiscinfo class="source">MySQL</refmiscinfo>
+ <refmiscinfo class="refman">Run MySQL Test Suite</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>mysql-test-run.pl</refname>
+
+ <refpurpose>run MySQL test suite</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>mysql-test-run.pl
[<replaceable>options</replaceable>]</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection id="mysql-test-run-pl-description">
+
+ <title>Description</title>
+
+ <para>
+ The <command>mysql-test-run.pl</command> Perl script is the main
+ application used to run the MySQL test suite. It invokes
+ <command>mysqltest</command> to run individual test cases.
+ (Prior to MySQL 4.1, a similar shell script,
+ <command>mysql-test-run</command>, can be used instead.)
+ </para>
+
+ <para>
+ Invoke <command>mysql-test-run.pl</command> in the
+ <filename>mysql-test</filename> directory like this:
+ </para>
+
+<programlisting>
+shell> <userinput>mysql-test-run.pl
[<replaceable>options</replaceable>]
[<replaceable>test_name</replaceable>] ...</userinput>
+</programlisting>
+
+ <para>
+ Each <replaceable>test_name</replaceable> argument names a test
+ case. The test case file that corresponds to the test name is
+
<filename>t/<replaceable>test_name</replaceable>.test</filename>.
+ </para>
+
+ <para>
+ For each <replaceable>test_name</replaceable> argument,
+ <command>mysql-test-run.pl</command> runs the named test case.
+ With no <replaceable>test_name</replaceable> arguments,
+ <command>mysql-test-run.pl</command> runs all
+ <filename>.test</filename> files in the
<filename>t</filename>
+ subdirectory.
+ </para>
+
+ <para>
+ If no suffix is given for the test name, a suffix of
+ <filename>.test</filename> is assumed. Any leading path name is
+ ignored. These commands are equivalent:
+ </para>
+
+<programlisting>
+shell> <userinput>mysql-test-run.pl mytest</userinput>
+shell> <userinput>mysql-test-run.pl mytest.test</userinput>
+shell> <userinput>mysql-test-run.pl t/mytest.test</userinput>
+</programlisting>
+
+ <para>
+ As of MySQL 5.1.23, a suite name can be given as part of the
+ test name. That is, the syntax for naming a test is:
+ </para>
+
+<programlisting>
+[<replaceable>suite_name</replaceable>.]<replaceable>test_name</replaceable>[.<replaceable>suffix</replaceable>]
+</programlisting>
+
+ <para>
+ If a suite name is given, <command>mysql-test-run.pl</command>
+ looks in that suite for the test. With no suite name,
+ <command>mysql-test-run.pl</command> looks in the default list
+ of suites for a match and runs the test in any suites where it
+ finds the test. Suppose that the default suite list is
+ <literal>main</literal>, <literal>binlog</literal>,
+ <literal>rpl</literal>, and that a test
+ <filename>mytest.test</filename> exists in the
+ <literal>main</literal> and <literal>rpl</literal>
suites. With
+ an argument of <literal>mytest</literal> or
+ <literal>mytest.test</literal>,
+ <command>mysql-test-run.pl</command> will run
+ <filename>mytest.test</filename> from the
+ <literal>main</literal> and <literal>rpl</literal>
suites.
+ </para>
+
+ <para>
+ To run a family of test cases for which the names share a common
+ prefix, use the
+
<option>--do-test=<replaceable>prefix</replaceable></option>
+ option. For example, <option>--do-test=rpl</option> runs the
+ replication tests (test cases that have names beginning with
+ <literal>rpl</literal>). <option>--skip-test</option> has
the
+ opposite effect of skipping test cases for which the names share
+ a common prefix.
+ </para>
+
+ <para>
+ As of MySQL 5.0.54/5.1.23/6.0.5, the argument for the
+ <option>--do-test</option> and
<option>--skip-test</option>
+ options allows more flexible specification of which tests to
+ perform or skip. If the argument contains a pattern
+ metacharacter other than a lone period, it is interpreted as a
+ Perl regular expression and applies to test names that match the
+ pattern. If the argument contains a lone period or does not
+ contain any pattern metacharacters, it is interpreted the same
+ way as previously and matches test names that begin with the
+ argument value. For example, <option>--do-test=testa</option>
+ matches tests that begin with <literal>testa</literal>,
+ <option>--do-test=main.testa</option> matches tests in the
+ <literal>main</literal> test suite that begin with
+ <literal>testa</literal>, and
+ <option>--do-test=main.*testa</option> matches test names that
+ contain <literal>main</literal> followed by
+ <literal>testa</literal> with anything in between. In the latter
+ case, the pattern match is not anchored to the beginning of the
+ test name, so it also matches names such as
+ <literal>xmainytestz</literal>.
+ </para>
+
+ <para>
+ To perform setup prior to running tests,
+ <command>mysql-test-run.pl</command> needs to invoke
+ <command>mysqld</command> with the
<option>--bootstrap</option>
+ and <option>--skip-grant-tables</option> options (see
+ <xref linkend="configure-options"/>). If MySQL was configured
+ with the <option>--disable-grant-options</option> option,
+ <option>--bootstrap</option>,
+ <option>--skip-grant-tables</option>, and
+ <option>--init-file</option> will be disabled. To handle this,
+ set the <literal>MYSQLD_BOOTSTRAP</literal> environment variable
+ to the full path name of a server that has all options enabled.
+ <command>mysql-test-run.pl</command> will use that server to
+ perform setup; it is not used to run the tests.
+ </para>
+
+ <para>
+ The <literal>init_file</literal> test will fail if
+ <option>--init-file</option> is disabled. This is an expected
+ failure that can be handled as follows:
+ </para>
+
+<programlisting>
+shell> <userinput>export MYSQLD_BOOTSTRAP</userinput>
+shell> <userinput>MYSQLD_BOOTSTRAP=/full/path/to/mysqld</userinput>
+shell> <userinput>make test force="--skip-test=init_file"</userinput>
+</programlisting>
+
+ <para>
+ To run <command>mysql-test-run.pl</command> on Windows, you'll
+ need either Cygwin or ActiveState Perl to run it. You may also
+ need to install the modules required by the script. To run the
+ test script, change location into the
+ <filename>mysql-test</filename> directory, set the
+ <literal>MTR_VS_CONFIG</literal> environment variable to the
+ configuration you selected earlier (or use the
+ <option>--vs-config</option> option), and invoke
+ <command>mysql-test-run.pl</command>. For example (using Cygwin
+ and the <command>bash</command> shell):
+ </para>
+
+<programlisting>
+shell> <userinput>cd mysql-test</userinput>
+shell> <userinput>export MTR_VS_CONFIG=debug</userinput>
+shell> <userinput>./mysqltest-run.pl --force --timer</userinput>
+shell> <userinput>./mysqltest-run.pl --force --timer
--ps-protocol</userinput>
+</programlisting>
+
+ <para>
+ If you have a copy of <command>mysqld</command> running on the
+ machine where you want to run the test suite, you do not have to
+ stop it, as long as it is not using ports
+ <literal>9306</literal> or <literal>9307</literal>. If
either of
+ those ports is taken, you should set the
+ <literal>MTR_BUILD_THREAD</literal> environment variable to an
+ appropriate value, and the test suite will use a different set
+ of ports for master, slave, NDB, and Instance Manager). For
+ example:
+ </para>
+
+<programlisting>
+shell> <userinput>export MTR_BUILD_THREAD=31</userinput>
+shell> <userinput>./mysql-test-run.pl
[<replaceable>options</replaceable>]
[<replaceable>test_name</replaceable>]</userinput>
+</programlisting>
+
+ <para>
+ <command>mysql-test-run.pl</command> defines several environment
+ variables. Some of them are listed in the following table.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="30*"/>
+ <colspec colwidth="70*"/>
+ <tbody>
+ <row>
+ <entry><emphasis
role="bold">Variable</emphasis></entry>
+ <entry><emphasis
role="bold">Meaning</emphasis></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TEST</literal></entry>
+ <entry>Path name to <command>mysqltest</command>
binary</entry>
+ </row>
+ <row>
+ <entry><literal>MYSQLTEST_VARDIR</literal></entry>
+ <entry>Path name to the <filename>var</filename>
directory that is used for
+ logs, temporary files, and so forth</entry>
+ </row>
+ <row>
+ <entry><literal>MYSQLD_BOOTSTRAP</literal></entry>
+ <entry>Full path name to <command>mysqld</command> that
has all options enabled</entry>
+ </row>
+ <row>
+ <entry><literal>MASTER_MYPORT</literal></entry>
+ <entry>???</entry>
+ </row>
+ <row>
+ <entry><literal>MASTER_MYSOCK</literal></entry>
+ <entry>???</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ Tests sometimes rely on certain environment variables being
+ defined. For example, certain tests assume that
+ <literal>MYSQL_TEST</literal> is defined so that
+ <command>mysqltest</command> can invoke itself with
+ <literal>exec $MYSQL_TEST</literal>.
+ </para>
+
+ <para>
+ <command>mysql-test-run.pl</command> supports the options in the
+ following list. An argument of <option>--</option> tells
+ <command>mysql-test-run.pl</command> not to process any
+ following arguments as options. (A description of differences
+ between the options supported by
+ <command>mysql-test-run.pl</command> and
+ <command>mysql-test-run</command> appears following the list.)
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>help option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>help option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--help</option>, <option>-h</option>
+ </para>
+
+ <para>
+ Display a help message and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>bench option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>bench option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--bench</option>
+ </para>
+
+ <para>
+ Run the benchmark suite.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>benchdir option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>benchdir option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--benchdir=<replaceable>path</replaceable></option>
+ </para>
+
+ <para>
+ The directory where the benchmark suite is located. The
+ default path is <filename>../../mysql-bench</filename>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>big option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>big option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--big-test</option>
+ </para>
+
+ <para>
+ Pass the <option>--big-test</option> option to
+ <command>mysqltest</command>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>check-testcases option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>check-testcases option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--check-testcases</option>
+ </para>
+
+ <para>
+ Check test cases for side effects.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>client-bindir option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>client-bindir option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--client-bindir</option>
+ </para>
+
+ <para>
+ The path to the directory where client binaries are located.
+ This option was added in MySQL 5.0.66/5.1.27.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>client-ddd option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>client-ddd option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--client-ddd</option>
+ </para>
+
+ <para>
+ Start <command>mysqltest</command> in the
+ <command>ddd</command> debugger.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>client-debugger option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>client-debugger option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--client-debugger</option>
+ </para>
+
+ <para>
+ Start <command>mysqltest</command> in the named debugger.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>client-gdb option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>client-gdb option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--client-gdb</option>
+ </para>
+
+ <para>
+ Start <command>mysqltest</command> in the
+ <command>gdb</command> debugger.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>client-libdir option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>client-libdir option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--client-libdir</option>
+ </para>
+
+ <para>
+ The path to the directory where client libraries are
+ located. This option was added in MySQL 5.0.66/5.1.27.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>combination option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>combination option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--combination=<replaceable>value</replaceable></option>
+ </para>
+
+ <para>
+ Extra options to pass to <command>mysqld</command>. The
+ value should consist of one or more comma-separated
+ <command>mysqld</command> options. This option is similar to
+ <option>--mysqld</option> but should be given two or more
+ times. <command>mysql-test-run.pl</command> executes
+ multiple test runs, using the options for each instance of
+ <option>--combination</option> in successive runs. If
+ <option>--combination</option> is given only once, it has no
+ effect. For test runs specific to a given test suite, an
+ alternative to the use of <option>--combination</option> is
+ to create a <filename>combinations</filename> file in the
+ suite directory. The file should contain a section of
+ options for each test run. See
+ <xref linkend="writing-tests-server-options"/>.
+ </para>
+
+ <para>
+ This option was added in MySQL 5.1.23/6.0.4.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>comment option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>comment option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--comment=<replaceable>str</replaceable></option>
+ </para>
+
+ <para>
+ Write <replaceable>str</replaceable> to the output.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>compress option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>compress option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--compress</option>
+ </para>
+
+ <para>
+ Compress all information sent between the client and the
+ server if both support compression.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>cursor-protocol option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>cursor-protocol option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--cursor-protocol</option>
+ </para>
+
+ <para>
+ Pass the <option>--cursor-protocol</option> option to
+ <command>mysqltest</command> (implies
+ <option>--ps-protocol</option>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>ddd option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>ddd option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--ddd</option>
+ </para>
+
+ <para>
+ Start <command>mysqld</command> in the
+ <command>ddd</command> debugger.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>debug option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>debug option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--debug</option>
+ </para>
+
+ <para>
+ Dump trace output for all clients and servers.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>debugger option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>debugger option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--debugger</option>
+ </para>
+
+ <para>
+ Start <command>mysqld</command> using the named debugger.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>debug-sync-timeout option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>debug-sync-timeout option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--debug-sync-timeout=<replaceable>N</replaceable></option>
+ </para>
+
+ <para>
+ Controls whether the Debug Sync facility for testing and
+ debugging is enabled. The option value is a timeout in
+ seconds. The default value is 300. A value of 0 disables
+ Debug Sync. The value of this option also becomes the
+ default timeout for individual synchronization points.
+ </para>
+
+ <para>
+ <command>mysql-test-run.pl</command> passes
+
<option>--loose-debug-sync-timeout=<replaceable>N</replaceable></option>
+ to <command>mysqld</command>. The
<option>--loose</option>
+ prefix is used so that <command>mysqld</command> does not
+ fail if Debug Sync is not compiled in.
+ </para>
+
+ <para>
+ For information about using the Debug Sync facility for
+ testing, see
+ <xref linkend="writing-tests-thread-synchronization"/>.
+ </para>
+
+ <para>
+ This option was added in MySQL 5.4.4/6.0.6.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>do-test option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>do-test option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--do-test=<replaceable>prefix</replaceable></option>
+ </para>
+
+ <para>
+ Run all test cases having a name that begins with the given
+ <replaceable>prefix</replaceable> value. This option
+ provides a convenient way to run a family of similarly named
+ tests.
+ </para>
+
+ <para>
+ As of MySQL 5.0.54/5.1.23/6.0.5, the argument for the
+ <option>--do-test</option> option allows more flexible
+ specification of which tests to perform. If the argument
+ contains a pattern metacharacter other than a lone period,
+ it is interpreted as a Perl regular expression and applies
+ to test names that match the pattern. If the argument
+ contains a lone period or does not contain any pattern
+ metacharacters, it is interpreted the same way as previously
+ and matches test names that begin with the argument value.
+ For example, <option>--do-test=testa</option> matches tests
+ that begin with <literal>testa</literal>,
+ <option>--do-test=main.testa</option> matches tests in the
+ <literal>main</literal> test suite that begin with
+ <literal>testa</literal>, and
+ <option>--do-test=main.*testa</option> matches test names
+ that contain <literal>main</literal> followed by
+ <literal>testa</literal> with anything in between. In the
+ latter case, the pattern match is not anchored to the
+ beginning of the test name, so it also matches names such as
+ <literal>xmainytestz</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>embedded-server option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>embedded-server option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--embedded-server</option>
+ </para>
+
+ <para>
+ Use a version of <command>mysqltest</command> built with the
+ embedded server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>experimental option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>experimental option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--experimental=<replaceable>file_name</replaceable></option>
+ </para>
+
+ <para>
+ Specify a file that contains a list of test cases that
+ should be displayed with the <literal>[ exp-fail ]</literal>
+ code rather than <literal>[ fail ]</literal> if they fail.
+ This option was added in MySQL 5.1.33/6.0.11.
+ </para>
+
+ <para>
+ For an example of a file that might be specified via this
+ option, see
+ <filename>mysql-test/collections/default.experimental</filename>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>extern option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>extern option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--extern</option>
+ </para>
+
+ <para>
+ Use an already running server.
+ </para>
+
+ <para>
+ Note: If a test case has an <filename>.opt</filename> file
+ that requires the server to be restarted with specific
+ options, the file will not be used. The test case likely
+ will fail as a result.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>fast option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>fast option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--fast</option>
+ </para>
+
+ <para>
+ Do not clean up from earlier test runs.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>force option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>force option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--force</option>
+ </para>
+
+ <para>
+ Normally, <command>mysql-test-run.pl</command> exits if a
+ test case fails. <option>--force</option> causes execution
+ to continue regardless of test case failure.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>gcov option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>gcov option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--gcov</option>
+ </para>
+
+ <para>
+ Run tests with the <command>gcov</command> test coverage
+ tool.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>gdb option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>gdb option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--gdb</option>
+ </para>
+
+ <para>
+ Start <command>mysqld</command> in the
+ <command>gdb</command> debugger.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>gprof option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>gprof option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--gprof</option>
+ </para>
+
+ <para>
+ Run tests with the <command>gprof</command> profiling tool.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>im-mysqld1-port option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>im-mysqld1-port option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--im-mysqld1-port</option>
+ </para>
+
+ <para>
+ TCP/IP port number to use for the first
+ <command>mysqld</command>, controlled by Instance Manager.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>im-mysqld2-port option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>im-mysqld2-port option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--im-mysqld2-port</option>
+ </para>
+
+ <para>
+ TCP/IP port number to use for the second
+ <command>mysqld</command>, controlled by Instance Manager.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>im-port option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>im-port option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--im-port</option>
+ </para>
+
+ <para>
+ TCP/IP port number to use for <command>mysqld</command>,
+ controlled by Instance Manager.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>log-warnings option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>log-warnings option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--log-warnings</option>
+ </para>
+
+ <para>
+ Pass the <option>--log-warnings</option> option to
+ <command>mysqld</command>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>manual-debug option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>manual-debug option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--manual-debug</option>
+ </para>
+
+ <para>
+ Use a server that has already been started by the user in a
+ debugger.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>manual-gdb option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>manual-gdb option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--manual-gdb</option>
+ </para>
+
+ <para>
+ Use a server that has already been started by the user in
+ the <command>gdb</command> debugger.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>master-binary option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>master-binary option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--master-binary=<replaceable>path</replaceable></option>
+ </para>
+
+ <para>
+ Specify the path of the <command>mysqld</command> binary to
+ use for master servers.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>master_port option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>master_port option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--master_port=<replaceable>port_num</replaceable></option>
+ </para>
+
+ <para>
+ Specify the TCP/IP port number for the first master server
+ to use. Observe that the option name has an underscore and
+ not a dash.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>mem option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>mem option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--mem</option>
+ </para>
+
+ <para>
+ Run the test suite in memory, using tmpfs or ramdisk. This
+ can decrease test times significantly.
+ <command>mysql-test-run.pl</command> attempts to find a
+ suitable location using a built-in list of standard
+ locations for tmpfs and puts the <filename>var</filename>
+ directory there. This option also affects placement of
+ temporary files, which are created in
+ <filename>var/tmp</filename>.
+ </para>
+
+ <para>
+ The default list includes <filename>/dev/shm</filename>. You
+ can also enable this option by setting the environment
+ variable
+
<literal>MTR_MEM[=<replaceable>dir_name</replaceable>]</literal>.
+ If <replaceable>dir_name</replaceable> is given, it is added
+ to the beginning of the list of locations to search, so it
+ takes precedence over any built-in locations.
+ </para>
+
+ <para>
+ This option was added in MySQL 4.1.22, 5.0.30, and 5.1.13.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>mysqld option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>mysqld option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--mysqld=<replaceable>value</replaceable></option>
+ </para>
+
+ <para>
+ Extra options to pass to <command>mysqld</command>. The
+ value should consist of one or more comma-separated
+ <command>mysqld</command> options. See
+ <xref linkend="writing-tests-server-options"/>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>mysqltest option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>mysqltest option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--mysqltest=<replaceable>value</replaceable></option>
+ </para>
+
+ <para>
+ Extra options to pass to <command>mysqltest</command>. The
+ value should consist of one or more comma-separated
+ <command>mysqltest</command> options. See
+ <xref linkend="writing-tests-server-options"/>. This option
+ was added in MySQL 6.0.6.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>ndb-connectstring option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>ndb-connectstring option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--ndb-connectstring=<replaceable>str</replaceable></option>
+ </para>
+
+ <para>
+ Pass
+
<option>--ndb-connectstring=<replaceable>str</replaceable></option>
+ to the master MySQL server. This option also prevents
+ <command>mysql-test-run.pl</command> from starting a
+ cluster. It is assumed that there is already a cluster
+ running to which the server can connect with the given
+ connectstring.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>ndb-connectstring-slave option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>ndb-connectstring-slave option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--ndb-connectstring-slave=<replaceable>str</replaceable></option>
+ </para>
+
+ <para>
+ Pass
+
<option>--ndb-connectstring=<replaceable>str</replaceable></option>
+ to slave MySQL servers. This option also prevents
+ <command>mysql-test-run.pl</command> from starting a
+ cluster. It is assumed that there is already a cluster
+ running to which the server can connect with the given
+ connectstring.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>ndb-extra-test option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>ndb-extra-test option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--ndb-extra-test</option>
+ </para>
+
+ <para>
+ Unknown.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>ndbcluster-port option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>ndbcluster-port option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>ndbcluster_port option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>ndbcluster_port option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--ndbcluster-port=<replaceable>port_num</replaceable></option>,
+
<option>--ndbcluster_port=<replaceable>port_num</replaceable></option>
+ </para>
+
+ <para>
+ Specify the TCP/IP port number that NDB Cluster should use.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>ndbcluster-port-slave option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>ndbcluster-port-slave option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--ndbcluster-port-slave=<replaceable>port_num</replaceable></option>
+ </para>
+
+ <para>
+ Specify the TCP/IP port number that the slave NDB Cluster
+ should use.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>netware option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>netware option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--netware</option>
+ </para>
+
+ <para>
+ Run <command>mysqld</command> with options needed on
+ NetWare.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>notimer option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>notimer option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--notimer</option>
+ </para>
+
+ <para>
+ Cause <command>mysqltest</command> not to generate a timing
+ file.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>parallel option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>parallel option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--parallel={<replaceable>N</replaceable>|auto}</option>
+ </para>
+
+ <para>
+ Run tests using <replaceable>N</replaceable> parallel
+ threads. By default, 1 thread is used. Use
+ <option>--parallel=auto</option> for auto-setting of
+ <replaceable>N</replaceable>. This option was added in MySQL
+ 5.1.36.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>ps-protocol option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>ps-protocol option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--ps-protocol</option>
+ </para>
+
+ <para>
+ Pass the <option>--ps-protocol</option> option to
+ <command>mysqltest</command>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>record option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>record option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--record</option>
+ </para>
+
+ <para>
+ Pass the <option>--record</option> option to
+ <command>mysqltest</command>. This option requires a
+ specific test case to be named on the command line.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>reorder option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>reorder option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--reorder</option>
+ </para>
+
+ <para>
+ Reorder tests to minimize the number of server restarts
+ needed.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>report-features option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>report-features option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--report-features</option>
+ </para>
+
+ <para>
+ Display the output of <literal>SHOW ENGINES</literal> and
+ <literal>SHOW VARIABLES</literal>. This can be used to
+ verify that binaries are built with all required features.
+ </para>
+
+ <para>
+ This option was added in MySQL 4.1.23, 5.0.30, and 5.1.14.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>script-debug option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>script-debug option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--script-debug</option>
+ </para>
+
+ <para>
+ Enable debug output for <command>mysql-test-run.pl</command>
+ itself.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>skip-im option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>skip-im option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--skip-im</option>
+ </para>
+
+ <para>
+ Do not start Instance Manager; skip Instance Manager test
+ cases.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>skip-master-binlog option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>skip-master-binlog option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--skip-master-binlog</option>
+ </para>
+
+ <para>
+ Do not enable master server binary logging.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>skip-ndbcluster option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>skip-ndbcluster option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--skip-ndbcluster</option>,
+
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>skip-ndb option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>skip-ndb option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--skip-ndb</option>
+ </para>
+
+ <para>
+ Do not start NDB Cluster; skip Cluster test cases.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>skip-ndbcluster-slave option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>skip-ndbcluster-slave option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--skip-ndbcluster-slave</option>,
+
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>skip-ndb-slave option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>skip-ndb-slave option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--skip-ndb-slave</option>
+ </para>
+
+ <para>
+ Do not start an NDB Cluster slave.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>skip-rpl option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>skip-rpl option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--skip-rpl</option>
+ </para>
+
+ <para>
+ Skip replication test cases.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>skip-slave-binlog option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>skip-slave-binlog option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--skip-slave-binlog</option>
+ </para>
+
+ <para>
+ Do not enable master server binary logging.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>skip-ssl option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>skip-ssl option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--skip-ssl</option>
+ </para>
+
+ <para>
+ Do not start <command>mysqld</command> with support for SSL
+ connections.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>skip-test option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>skip-test option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--skip-test=<replaceable>regex</replaceable></option>
+ </para>
+
+ <para>
+ Specify a regular expression to be applied to test case
+ names. Cases with names that match the expression are
+ skipped. tests to skip.
+ </para>
+
+ <para>
+ As of MySQL 5.0.54/5.1.23/6.0.5, the argument for the
+ <option>--skip-test</option> option allows more flexible
+ specification of which tests to skip. If the argument
+ contains a pattern metacharacter other than a lone period,
+ it is interpreted as a Perl regular expression and applies
+ to test names that match the pattern. See the description of
+ the <option>--do-test</option> option for details.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <option>--skip-*</option>
+ </para>
+
+ <para>
+ <option>--skip-*</option> options not otherwise recognized
+ by <command>mysql-test-run.pl</command> are passed to the
+ master server.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>slave-binary option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>slave-binary option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--slave-binary=<replaceable>path</replaceable></option>
+ </para>
+
+ <para>
+ Specify the path of the <command>mysqld</command> binary to
+ use for slave servers.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>slave_port option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>slave_port option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--slave_port=<replaceable>port_num</replaceable></option>
+ </para>
+
+ <para>
+ Specify the TCP/IP port number for the first master server
+ to use. Observe that the option name has an underscore and
+ not a dash.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>sleep option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>sleep option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--sleep=<replaceable>N</replaceable></option>
+ </para>
+
+ <para>
+ Pass
<option>--sleep=<replaceable>N</replaceable></option>
+ to <command>mysqltest</command>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>small-bench option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>small-bench option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--small-bench</option>
+ </para>
+
+ <para>
+ Run the benchmarks with the <option>--small-tests</option>
+ and <option>--small-tables</option> options.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>socket option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>socket option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--socket=<replaceable>file_name</replaceable></option>
+ </para>
+
+ <para>
+ For connections to <literal>localhost</literal>, the Unix
+ socket file to use, or, on Windows, the name of the named
+ pipe to use.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>sp-protocol option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>sp-protocol option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--sp-protocol</option>
+ </para>
+
+ <para>
+ Pass the <option>--sp-protocol</option> option to
+ <command>mysqltest</command>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>ssl option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>ssl option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--ssl</option>
+ </para>
+
+ <para>
+ If <command>mysql-test-run.pl</command> is started with the
+ <option>--ssl</option> option, it sets up a secure conection
+ for all test cases. In this case, if
+ <command>mysqld</command> does not support SSL,
+ <command>mysql-test-run.pl</command> exits with an error
+ message: <literal>Couldn't find support for SSL</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>start option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>start option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--start</option>
+ </para>
+
+ <para>
+ Initialize and start servers with the startup settings for
+ the first specified test case. For example:
+ </para>
+
+<programlisting>
+shell> <userinput>cd mysql-test</userinput>
+shell> <userinput>./mysql-test-run.pl --start alias
&</userinput>
+</programlisting>
+
+ <para>
+ This option was added in MySQL 5.1.32/6.0.11.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>start-and-exit option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>start-and-exit option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--start-and-exit</option>
+ </para>
+
+ <para>
+ Initialize and start servers with the startup settings for
+ the specified test case or cases, if any, and then exit. You
+ can use this option to start a server to which you can
+ connect later. For example, after building a source
+ distribution you can start a server and connect to it with
+ the <command>mysql</command> client like this:
+ </para>
+
+<programlisting>
+shell> <userinput>cd mysql-test</userinput>
+shell> <userinput>./mysql-test-run.pl --start-and-exit</userinput>
+shell> <userinput>../mysql -S ./var/tmp/master.sock -h localhost -u
root</userinput>
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>start-dirty option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>start-dirty option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--start-dirty</option>
+ </para>
+
+ <para>
+ Start servers (without initialization) for the specified
+ test case or cases, if any, and then exit. You can then
+ manually run the test cases.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>start-from option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>start-from option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--start-from=<replaceable>test_name</replaceable></option>
+ </para>
+
+ <para>
+ <command>mysql-test-run.pl</command> sorts the list of names
+ of the test cases to be run, and then begins with
+ <replaceable>test_name</replaceable>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>strace-client option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>strace-client option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--strace-client</option>
+ </para>
+
+ <para>
+ Create <command>strace</command> output for
+ <command>mysqltest</command>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>stress option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>stress option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--stress</option>
+ </para>
+
+ <para>
+ Run the stress test. The other
+
<option>--stress-<replaceable>xxx</replaceable></option>
+ options apply in this case.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>stress-init-file option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>stress-init-file option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--stress-init-file=<replaceable>file_name</replaceable></option>
+ </para>
+
+ <para>
+ <replaceable>file_name</replaceable> is the location of the
+ file that contains the list of tests. The default file is
+ <filename>stress_init.txt</filename> in the test suite
+ directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>stress-loop-count option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>stress-loop-count option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--stress-loop-count=<replaceable>N</replaceable></option>
+ </para>
+
+ <para>
+ In sequential stress-test mode, the number of loops to
+ execute before exiting.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>stress-mode option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>stress-mode option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--stress-mode=<replaceable>mode</replaceable></option>
+ </para>
+
+ <para>
+ This option indicates the test order in stress-test mode.
+ The <replaceable>mode</replaceable> value is either
+ <literal>random</literal> to select tests in random order or
+ <literal>seq</literal> to run tests in each thread in the
+ order specified in the test list file. The default mode is
+ <literal>random</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>stress-suite option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>stress-suite option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--stress-suite=<replaceable>suite_name</replaceable></option>
+ </para>
+
+ <para>
+ The name of the test suite to use for stress testing. The
+ default suite name is <literal>main</literal> (the regular
+ test suite located in the <filename>mysql-test</filename>
+ directory).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>stress-test-count option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>stress-test-count option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--stress-test-count=<replaceable>N</replaceable></option>
+ </para>
+
+ <para>
+ For stress testing, the number of tests to execute before
+ exiting.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>stress-test-duration option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>stress-test-duration option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--stress-test-duration=<replaceable>N</replaceable></option>
+ </para>
+
+ <para>
+ For stress testing, the duration of stress testing in
+ seconds.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>stress-test-file option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>stress-test-file option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--stress-test-file=<replaceable>file_name</replaceable></option>
+ </para>
+
+ <para>
+ The file that contains the list of tests to use in stress
+ testing. The tests should be named without the
+ <filename>.test</filename> extension. The default file is
+ <filename>stress_tests.txt</filename> in the test suite
+ directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>stress-threads option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>stress-threads option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--stress-threads=<replaceable>N</replaceable></option>
+ </para>
+
+ <para>
+ The number of threads to use in stress testing. The default
+ is 5.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>suite option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>suite option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--suite=<replaceable>suite_name</replaceable></option>
+ </para>
+
+ <para>
+ Run the named test suite. The default name is
+ <literal>main</literal> (the regular test suite located in
+ the <filename>mysql-test</filename> directory).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>suite-timeout option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>suite-timeout option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--suite-timeout=<replaceable>minutes</replaceable></option>
+ </para>
+
+ <para>
+ Specify the maximum test suite runtime.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>testcase-timeout option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>testcase-timeout option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--testcase-timeout</option>
+ </para>
+
+ <para>
+ Specify the maximum test case runtime.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>timer option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>timer option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--timer</option>
+ </para>
+
+ <para>
+ Cause <command>mysqltest</command> to generate a timing
+ file. The default file is named
+ <filename>./var/log/timer</filename>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>tmpdir option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>tmpdir option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--tmpdir=<replaceable>path</replaceable></option>
+ </para>
+
+ <para>
+ The directory where temporary file are stored. The default
+ location is <filename>./var/tmp</filename>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>unified-diff option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>unified-diff option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--unified-diff</option>,
<option>--udiff</option>
+ </para>
+
+ <para>
+ Use unified diff format when presenting differences between
+ expected and actual test case results.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>use-old-data option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>use-old-data option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--use-old-data</option>
+ </para>
+
+ <para>
+ Do not install the test databases. (Use existing ones.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>user-test option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>user-test option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--user-test=<replaceable>val</replaceable></option>
+ </para>
+
+ <para>
+ Unused.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>user option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>user option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+
<option>--user=<replaceable>user_name</replaceable></option>
+ </para>
+
+ <para>
+ The MySQL user name to use when connecting to the server.
+ </para>
+ </listitem>
+
+ 