Author: paul
Date: 2008-08-26 20:23:24 +0200 (Tue, 26 Aug 2008)
New Revision: 11607
Log:
r33516@frost: paul | 2008-08-26 12:21:18 -0500
mysqltest manual: Add section on using --mysqld/--combination/--mysqltest
for passing arguments from mysql-test-run.pl to other programs.
Modified:
trunk/mysqltest/programs.xml
trunk/mysqltest/writing-tests.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:35828
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:33514
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:32819
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:35828
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:33516
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:32819
Modified: trunk/mysqltest/programs.xml
===================================================================
--- trunk/mysqltest/programs.xml 2008-08-25 20:22:46 UTC (rev 11606)
+++ trunk/mysqltest/programs.xml 2008-08-26 18:23:24 UTC (rev 11607)
Changed blocks: 3, Lines Added: 6, Lines Deleted: 7; 1434 bytes
@@ -1924,7 +1924,7 @@
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.
+ effect. See <xref linkend="writing-tests-server-options"/>.
</para>
<para>
@@ -2480,10 +2480,8 @@
</para>
<para>
- Extra options to pass to <command>mysqld</command>. See also
- the description for the <option>--combination</option>
- option, which can be use to pass options for multiple test
- runs.
+ Extra options to pass to <command>mysqld</command>. See
+ <xref linkend="writing-tests-server-options"/>.
</para>
</listitem>
@@ -2503,8 +2501,9 @@
</para>
<para>
- Extra options to pass to <command>mysqltest</command>. This
- option was added in MySQL 6.0.6.
+ Extra options to pass to <command>mysqltest</command>. See
+ <xref linkend="writing-tests-server-options"/>. This option
+ was added in MySQL 6.0.6.
</para>
</listitem>
Modified: trunk/mysqltest/writing-tests.xml
===================================================================
--- trunk/mysqltest/writing-tests.xml 2008-08-25 20:22:46 UTC (rev 11606)
+++ trunk/mysqltest/writing-tests.xml 2008-08-26 18:23:24 UTC (rev 11607)
Changed blocks: 10, Lines Added: 230, Lines Deleted: 107; 17157 bytes
@@ -700,7 +700,7 @@
<para>
If a test case creates other objects such as stored programs or
- user accounts, it should take case to also clean those up at the
+ user accounts, it should take care to also clean those up at the
beginning and end of the test.
</para>
@@ -1226,6 +1226,104 @@
<section id="writing-tests-server-options">
+ <title>Passing Options from <command>mysql-test-run.pl</command> to
+ <command>mysqld</command> or <command>mysqltest</command></title>
+
+ <indexterm>
+ <primary>--combination option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>combinations file</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>--mysqld option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>--mysqltest option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <para>
+ <command>mysql-test-run.pl</command> supports several options that
+ enable you to pass options to <command>mysqld</command> or
+ <command>mysqltest</command>. Each of these options takes a value
+ consisting of one or more comma-separated options.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The <option>--mysqld</option> option tells
+ <command>mysql-test-run.pl</command> to start the
+ <command>mysqld</command> server with the named options.
+ </para>
+
+<programlisting>
+shell> <userinput>mysql-test-run.pl --mysqld=<replaceable>opt1</replaceable>,<replaceable>opt2</replaceable>,...</userinput>
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <option>--combination</option> option is similar to
+ <option>--mysqld</option>, but should be specified 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.
+ </para>
+
+<programlisting>
+shell> <userinput>mysql-test-run.pl --combination=<replaceable>opt1</replaceable>,<replaceable>opt2</replaceable>,... --combination=<replaceable>opt1</replaceable>,<replaceable>opt2</replaceable>,...</userinput>
+</programlisting>
+
+ <para>
+ 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. For an example, see
+ <xref linkend="writing-tests-binlog-control-global"/>.
+ </para>
+
+ <para>
+ The <option>--combination</option> option and
+ <filename>combinations</filename> file can be used as of MySQL
+ 5.1.23/6.0.4.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <option>--mysqltest</option> option tells
+ <command>mysql-test-run.pl</command> to start
+ <command>mysqltest</command> with the named options.
+ </para>
+
+<programlisting>
+shell> <userinput>mysql-test-run.pl --mysqltest=<replaceable>opt1</replaceable>,<replaceable>opt2</replaceable>,...</userinput>
+</programlisting>
+
+ <para>
+ The <option>--mysqltest</option> option can be used as of
+ MySQL 6.0.6.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ <section id="writing-tests-server-options-test-specific">
+
<title>Specifying Test Case-Specific Server Options</title>
<para>
@@ -1283,8 +1381,8 @@
<para>
These include files serve many purposes, but in general, they
- encapsulate operations of varying complexity into a single file so
- that you can perform the operations in a single step. Include
+ encapsulate operations of varying complexity into single files so
+ that you can perform each operation in a single step. Include
files are available for operations such as these:
</para>
@@ -1302,13 +1400,11 @@
<para>
Storage engine tests: These files have names of the form
<filename>have_<replaceable>engine_name</replaceable>.inc</filename>,
- such as <filename>have_innodb.inc</filename>. These files
- have names of the form
- <filename>have_<replaceable>engine_name</replaceable>.inc</filename>
- or <filename>have_falcon.inc</filename>.
+ such as <filename>have_innodb.inc</filename> or
+ <filename>have_falcon.inc</filename>. The
<literal>MyISAM</literal>, <literal>MERGE</literal>, and
- <literal>MEMORY</literal> are always supported and need
- not be checked.
+ <literal>MEMORY</literal> storage engines are always
+ supported and need not be checked.
</para>
</listitem>
@@ -1351,35 +1447,24 @@
<secondary>controlling</secondary>
</indexterm>
- <indexterm>
- <primary>--combination option</primary>
- </indexterm>
-
- <indexterm>
- <primary>combinations file</primary>
- </indexterm>
-
<para>
- Some tests require the use of a particular binary logging format.
- This section describes how to control the format for testing
- purposes.
- </para>
-
- <para>
Before MySQL 5.1, the server does all binary logging using
statement-based logging (SBL), which logs events as statements
that produce data changes. As of MySQL 5.1, the server also
supports row-based logging (RBL), which logs events as changes to
individual rows, and mixed logging, which switches between SBL and
- RBL automatically as necessary.
+ RBL automatically as necessary. Some tests require the use of a
+ particular binary logging format. This section describes how to
+ control the format for testing purposes.
</para>
<para>
- The global <literal>binlog_format</literal> system variable
- indicates which logging format is in effect. It has possible
- values of <literal>STATEMENT</literal>, <literal>ROW</literal>,
- and <literal>MIXED</literal> (not case sensitive). This system
- variable can be set at server startup by specifying
+ The server's global <literal>binlog_format</literal> system
+ variable indicates which logging format is in effect. It has
+ possible values of <literal>STATEMENT</literal>,
+ <literal>ROW</literal>, and <literal>MIXED</literal> (not case
+ sensitive). This system variable can be set at server startup by
+ specifying
<option>--binlog_format=<replaceable>value</replaceable></option>
on the command line or in an option file. A user who has the
<literal>SUPER</literal> privilege can change the logging format
@@ -1391,7 +1476,7 @@
</programlisting>
<para>
- At test time, you can exercise control over the binary logging
+ For tests, you can exercise control over the binary logging
format:
</para>
@@ -1399,43 +1484,60 @@
<listitem>
<para>
- To control which format the server uses, you can pass options
- to <command>mysql-test-run.pl</command>.
+ To control the format the server uses for an entire test run,
+ you can pass options to <command>mysql-test-run.pl</command>.
</para>
</listitem>
<listitem>
<para>
- To verify that a particular format is in effect for a test
- case, you can use an appropriate include file that checks the
- current format and exits if the format is other than what is
- required.
+ To verify that a particular format is in effect for a specific
+ test case, you can use an appropriate include file that checks
+ the current format and exits if the format is other than what
+ is required.
</para>
</listitem>
</itemizedlist>
- <para>
- To set the binary logging format for a test run, you can use the
- <option>--mysqld</option> option to tell
- <command>mysql-test-run.pl</command> to pass a logging option to
- <command>mysqld</command>. For example, to use statement-based
- logging, do this:
- </para>
+ <section id="writing-tests-binlog-control-global">
+ <title>Controlling the Binary Log Format Used for an Entire Test Run</title>
+
+ <indexterm>
+ <primary>--combination option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>combinations file</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <para>
+ To specify the binary log format for a test run, you can use the
+ <option>--mysqld</option> or <option>--combination</option>
+ option to tell <command>mysql-test-run.pl</command> to pass a
+ logging option to <command>mysqld</command>. For example, the
+ following command runs the tests from the <literal>rpl</literal>
+ suite that have names that begin with
+ <literal>rpl_row</literal>. The tests are run once with the
+ binary log format set to <literal>STATEMENT</literal>:
+ </para>
+
<programlisting>
-shell> <userinput>mysql-test-run.pl --mysqld=--binlog_format=statement [<replaceable>option</replaceable>] ...</userinput>
+shell> <userinput>mysql-test-run.pl --suite=rpl --do-test=rpl_row</userinput>
+ <userinput>--mysqld=--binlog_format=statement</userinput>
</programlisting>
- <para>
- Alternatively, to run tests under multiple log formats, use two or
- more instances of the <option>--combination</option> option. For
- example, the following command runs those tests from the
- <literal>rpl</literal> suite that have names that begin with
- <literal>rpl_row</literal>. The tests are run once with the binary
- log format set to <literal>ROW</literal> and a second time with
- the format set to <literal>MIXED</literal>:
- </para>
+ <para>
+ To run tests under multiple log formats, use two or more
+ instances of the <option>--combination</option> option. The
+ following command runs the same tests as the preceding command,
+ but runs them once with the binary log format set to
+ <literal>ROW</literal> and a second time with the format set to
+ <literal>MIXED</literal>:
+ </para>
<programlisting>
shell> <userinput>mysql-test-run.pl --suite=rpl --do-test=rpl_row</userinput>
@@ -1443,21 +1545,22 @@
<userinput>--combination=--binlog_format=mixed</userinput>
</programlisting>
- <para>
- The <option>--combination</option> option must be given at least
- two times or it has no effect.
- </para>
+ <para>
+ The <option>--combination</option> option must be given at least
+ two times or it has no effect.
+ </para>
- <para>
- As an alternative to using the <option>--combination</option>
- option, you can create a file named
- <filename>combinations</filename> in the test suite directory and
- list the arguments that you would specify via
- <option>--combination</option>, one line per argument. For the
- preceding <command>mysql-test-run.pl</command> command, the suite
- name is <literal>rpl</literal>, so you would create a file named
- <filename>suite/rpt/combinations</filename> with these contents:
- </para>
+ <para>
+ As an alternative to using the <option>--combination</option>
+ option, you can create a file named
+ <filename>combinations</filename> in the test suite directory
+ and list the arguments that you would specify via
+ <option>--combination</option>, one line per argument. For the
+ preceding <command>mysql-test-run.pl</command> command, the
+ suite name is <literal>rpl</literal>, so you would create a file
+ named <filename>suite/rpt/combinations</filename> with these
+ contents:
+ </para>
<programlisting>
[row]
@@ -1467,45 +1570,63 @@
--binlog_format=mixed
</programlisting>
- <para>
- Then invoke <command>mysql-test-run.pl</command> like this:
- </para>
+ <para>
+ Then invoke <command>mysql-test-run.pl</command> like this:
+ </para>
<programlisting>
shell> <userinput>mysql-test-run.pl --suite=rpl --do-test=row</userinput>
</programlisting>
- <para>
- <option>--combination</option> options specified on the command
- line override those found in the combinations file if both are
- used.
- </para>
+ <para>
+ The format of the <filename>combinations</filename> file is
+ similar to that of <filename>my.cnf</filename> files (section
+ names followed by options for each section), but options are
+ given with the leading dashes.
+ </para>
- <para>
- The <option>--combination</option> option and the
- <filename>combinations</filename> file have different scope. The
- <option>--combination</option> applies globally to all tests run
- by a given invocation of <command>mysql-test-run.pl</command>. The
- <filename>combinations</filename> file is placed in a test suite
- directory and applies only to tests in that suite.
- </para>
+ <para>
+ Any <option>--combination</option> options specified on the
+ command line override those found in a
+ <filename>combinations</filename> file.
+ </para>
- <para>
- To specify within a test case that a particular binary log format
- is required, include one of the following lines to indicate the
- format:
- </para>
+ <para>
+ The <option>--combination</option> option and the
+ <filename>combinations</filename> file have different scope. The
+ <option>--combination</option> option applies globally to all
+ tests run by a given invocation of
+ <command>mysql-test-run.pl</command>. The
+ <filename>combinations</filename> file is placed in a test suite
+ directory and applies only to tests in that suite.
+ </para>
+ </section>
+
+ <section id="writing-tests-binlog-control-test-specific">
+
+ <title>Specifying the Required Binary Log Format for Individual Test Cases</title>
+
+ <indexterm>
+ <primary>have_binlog_format_*.inc include files</primary>
+ </indexterm>
+
+ <para>
+ To specify within a test case that a particular binary log
+ format is required, include one of the following lines to
+ indicate the format:
+ </para>
+
<programlisting>
--source include/have_binlog_format_row.inc
--source include/have_binlog_format_statement.inc
--source include/have_binlog_format_mixed.inc
</programlisting>
- <para>
- The following files can be used for tests that support two logging
- formats:
- </para>
+ <para>
+ The following files can be used for tests that support two
+ logging formats:
+ </para>
<programlisting>
--source include/have_binlog_format_mixed_or_row.inc
@@ -1513,23 +1634,25 @@
--source include/have_binlog_format_row_or_statement.inc
</programlisting>
- <para>
- Before <command>mysql-test-run.pl</command> runs the test case, it
- checks whether the value that it is using for the
- <literal>binlog_format</literal> system variable matches what the
- test requires, based on whether the test sources one of the
- preceding include files. If <literal>binlog_format</literal> does
- not have an appropriate value,
- <command>mysql-test-run.pl</command> skips the test.
- </para>
+ <para>
+ Before <command>mysql-test-run.pl</command> runs the test case,
+ it checks whether the value that it is using for the
+ <literal>binlog_format</literal> system variable matches what
+ the test requires, based on whether the test refers to one of
+ the preceding include files. If <literal>binlog_format</literal>
+ does not have an appropriate value,
+ <command>mysql-test-run.pl</command> skips the test.
+ </para>
- <para>
- If a test supports all binary logging formats, none of the
- preceding include files should be used in the test file. A test
- that includes no <filename>have_binlog_format_*.inc</filename>
- file is assumed to support all formats.
- </para>
+ <para>
+ If a test supports all binary logging formats, none of the
+ preceding include files should be used in the test file. A test
+ that includes no <filename>have_binlog_format_*.inc</filename>
+ file is assumed to support all formats.
+ </para>
+ </section>
+
</section>
<section id="writing-tests-replication-tests">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r11607 - in trunk: . mysqltest | paul.dubois | 26 Aug |
