Author: paul
Date: 2006-06-13 21:18:23 +0200 (Tue, 13 Jun 2006)
New Revision: 2368
Log:
r10496@polar: paul | 2006-06-13 14:18:13 -0500
Fill in more test program options.
Incorporate some feedback from Sanja.
Modified:
trunk/
trunk/mysqltest/command-reference.xml
trunk/mysqltest/introduction.xml
trunk/mysqltest/programs.xml
trunk/mysqltest/tutorial.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:10492
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:11231
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:7663
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:10496
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:11231
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:7663
Modified: trunk/mysqltest/command-reference.xml
===================================================================
--- trunk/mysqltest/command-reference.xml 2006-06-13 17:50:18 UTC (rev 2367)
+++ trunk/mysqltest/command-reference.xml 2006-06-13 19:18:23 UTC (rev 2368)
@@ -662,6 +662,12 @@
<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>
</listitem>
<listitem>
@@ -785,7 +791,7 @@
<para>
Specify one or more comma-separated error values that the next
command is expected to return. Each
- <replaceable>error_code</replaceable> value is either a
+ <replaceable>error_code</replaceable> value is a
MySQL-specific error number or a SQLSTATE value. (These are
the kinds of values returned by the
<literal>mysql_errno()</literal> and
@@ -808,6 +814,15 @@
</programlisting>
<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 theh error
@@ -1664,6 +1679,16 @@
</para>
<para>
+ The result from executing a query can be assigned to a variable by
+ enclosing the query within backtick
+ (‘<literal>`</literal>’) 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
Modified: trunk/mysqltest/introduction.xml
===================================================================
--- trunk/mysqltest/introduction.xml 2006-06-13 17:50:18 UTC (rev 2367)
+++ trunk/mysqltest/introduction.xml 2006-06-13 19:18:23 UTC (rev 2368)
@@ -103,7 +103,7 @@
</para>
<para>
- There are two ways a test case can fail:
+ There are several ways a test case can fail:
</para>
<itemizedlist>
@@ -118,6 +118,14 @@
<listitem>
<para>
+ A test case can fail if an error was expected but did not occur
+ (for example, if a 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
Modified: trunk/mysqltest/programs.xml
===================================================================
--- trunk/mysqltest/programs.xml 2006-06-13 17:50:18 UTC (rev 2367)
+++ trunk/mysqltest/programs.xml 2006-06-13 19:18:23 UTC (rev 2368)
@@ -1417,7 +1417,7 @@
</para>
<para>
- TCP/IP port number to use for first
+ TCP/IP port number to use for the first
<command>mysqld</command>, controlled by Instance Manager.
</para>
</listitem>
@@ -1438,7 +1438,7 @@
</para>
<para>
- TCP/IP port number to use for second
+ TCP/IP port number to use for the second
<command>mysqld</command>, controlled by Instance Manager.
</para>
</listitem>
@@ -1564,8 +1564,8 @@
</para>
<para>
- Do not start Instance Manager and skip Instance Manager
- test cases.
+ Do not start Instance Manager; skip Instance Manager test
+ cases.
</para>
</listitem>
@@ -1650,7 +1650,8 @@
<para>
Run the named test suite. The default name is
- <literal>main</literal>.
+ <literal>main</literal> (the regular test suite located in
+ the <filename>mysql-test</filename> directory).
</para>
</listitem>
@@ -1932,11 +1933,11 @@
</row>
<row>
<entry><literal>MASTER_MYPORT</literal></entry>
- <entry>???</entry>
+ <entry>Master server TCP/IP port number</entry>
</row>
<row>
<entry><literal>MASTER_MYSOCK</literal></entry>
- <entry>???</entry>
+ <entry>Master server Unix socket file</entry>
</row>
</tbody>
</tgroup>
@@ -2245,6 +2246,11 @@
<option>--gcov</option>
</para>
+
+ <para>
+ Run tests with the <command>gcov</command> test coverage
+ tool.
+ </para>
</listitem>
<listitem>
@@ -2282,6 +2288,11 @@
<option>--gprof</option>
</para>
+
+ <para>
+ Run tests with the <command>gprof</command> profiling
+ tool.
+ </para>
</listitem>
<listitem>
@@ -2325,6 +2336,11 @@
<option>--local-master</option>
</para>
+
+ <para>
+ [Q: Unknown. (Assume the master server is already
+ running?)]
+ </para>
</listitem>
<listitem>
@@ -2382,6 +2398,11 @@
<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>
@@ -2400,8 +2421,9 @@
</para>
<para>
- Observe that the option name has an underscore and not a
- dash.
+ 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>
@@ -2417,40 +2439,52 @@
<secondary>mysql-test-run</secondary>
</indexterm>
- <option>--mysqld=<replaceable>path</replaceable></option>
+ <option>--mysqld=<replaceable>str</replaceable></option>
</para>
+
+ <para>
+ Extra options to pass to <command>mysqld</command>.
+ </para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>mysql-test-run</primary>
- <secondary>ndb-connectstring-slave option</secondary>
+ <secondary>ndb-connectstring option</secondary>
</indexterm>
<indexterm>
- <primary>ndb-connectstring-slave option</primary>
+ <primary>ndb-connectstring option</primary>
<secondary>mysql-test-run</secondary>
</indexterm>
- <option>--ndb-connectstring-slave=<replaceable>str</replaceable></option>
+ <option>--ndb-connectstring=<replaceable>str</replaceable></option>
</para>
+
+ <para>
+ [Q: Unknown]
+ </para>
</listitem>
<listitem>
<para>
<indexterm>
<primary>mysql-test-run</primary>
- <secondary>ndb-connectstring option</secondary>
+ <secondary>ndb-connectstring-slave option</secondary>
</indexterm>
<indexterm>
- <primary>ndb-connectstring option</primary>
+ <primary>ndb-connectstring-slave option</primary>
<secondary>mysql-test-run</secondary>
</indexterm>
- <option>--ndb-connectstring=<replaceable>str</replaceable></option>
+ <option>--ndb-connectstring-slave=<replaceable>str</replaceable></option>
</para>
+
+ <para>
+ [Q: Unknown]
+ </para>
</listitem>
<listitem>
@@ -2467,6 +2501,10 @@
<option>--ndb-extra-test</option>
</para>
+
+ <para>
+ [Q: Unknown]
+ </para>
</listitem>
<listitem>
@@ -2483,6 +2521,10 @@
<option>--ndb-verbose</option>
</para>
+
+ <para>
+ [Q: Unknown]
+ </para>
</listitem>
<listitem>
@@ -2501,6 +2543,7 @@
</para>
<para>
+ Extra options to pass to <command>ndb_mgm</command>.
Observe that the option name contains an underscore.
</para>
</listitem>
@@ -2521,6 +2564,7 @@
</para>
<para>
+ Extra options to pass to <command>ndb_mgmd</command>.
Observe that the option name contains an underscore.
</para>
</listitem>
@@ -2550,6 +2594,11 @@
<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>
@@ -2566,6 +2615,11 @@
<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>
@@ -2582,6 +2636,10 @@
<option>--ndbd-extra-opts=<replaceable>str</replaceable></option>
</para>
+
+ <para>
+ Extra options to pass to <command>ndbd</command>.
+ </para>
</listitem>
<listitem>
@@ -2598,6 +2656,10 @@
<option>--old-master</option>
</para>
+
+ <para>
+ [Q: Unknown]
+ </para>
</listitem>
<listitem>
@@ -2614,6 +2676,11 @@
<option>--ps-protocol</option>
</para>
+
+ <para>
+ Pass the <option>--ps-protocol</option> option to
+ <command>mysqltest</command>.
+ </para>
</listitem>
<listitem>
@@ -2650,6 +2717,12 @@
<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>
@@ -2666,6 +2739,10 @@
<option>--skip-master-binlog</option>
</para>
+
+ <para>
+ Do not enable master server binary logging.
+ </para>
</listitem>
<listitem>
@@ -2694,6 +2771,10 @@
<option>--skip-ndb</option>
</para>
+
+ <para>
+ Do not start NDB Cluster; skip Cluster test cases.
+ </para>
</listitem>
<listitem>
@@ -2722,6 +2803,10 @@
<option>--skip-ndb-slave</option>
</para>
+
+ <para>
+ [Q: Unknown]
+ </para>
</listitem>
<listitem>
@@ -2738,6 +2823,10 @@
<option>--skip-rpl</option>
</para>
+
+ <para>
+ Skip replication test cases.
+ </para>
</listitem>
<listitem>
@@ -2754,6 +2843,10 @@
<option>--skip-slave-binlog</option>
</para>
+
+ <para>
+ Do not enable master server binary logging.
+ </para>
</listitem>
<listitem>
@@ -2804,6 +2897,11 @@
<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>
@@ -2822,8 +2920,9 @@
</para>
<para>
- Observe that the option name has an underscore and not a
- dash.
+ 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>
@@ -2948,6 +3047,11 @@
<option>--strace-client</option>
</para>
+
+ <para>
+ Create <command>strace</command> output for
+ <command>mysqltest</command>.
+ </para>
</listitem>
<listitem>
@@ -2988,13 +3092,10 @@
</para>
<para>
- This option enables initialization of the stress database
- by execution of test files.
<replaceable>file_name</replaceable> is the location of
- the file that contains the list of tests. If
- <replaceable>file_name</replaceable> is omitted, the
- default file is <filename>stress-init.txt</filename> in
- the stress suite base directory. [Q: Is that correct?]
+ the file that contains the list of tests. The default file
+ is <filename>stress_init.txt</filename> in the test suite
+ directory.
</para>
</listitem>
@@ -3012,6 +3113,11 @@
<option>--stress-loop-count=<replaceable>N</replaceable></option>
</para>
+
+ <para>
+ In sequential test mode, the number of loops to execute
+ before exiting.
+ </para>
</listitem>
<listitem>
@@ -3056,7 +3162,9 @@
<para>
The name of the test suite to use for stress testing. The
- default suite name is <literal>main</literal>.
+ default suite name is <literal>main</literal> (the regular
+ test suite located in the <filename>mysql-test</filename>
+ directory).
</para>
</listitem>
@@ -3075,9 +3183,9 @@
<option>--stress-test-count=<replaceable>N</replaceable></option>
</para>
- <remark role="note">
- Default is 0
- </remark>
+ <para>
+ The number of tests to execute before exiting.
+ </para>
</listitem>
<listitem>
@@ -3095,9 +3203,9 @@
<option>--stress-test-duration=<replaceable>N</replaceable></option>
</para>
- <remark role="note">
- Default is 0
- </remark>
+ <para>
+ The duration of stress testing in seconds.
+ </para>
</listitem>
<listitem>
@@ -3115,9 +3223,13 @@
<option>--stress-test-file=<replaceable>file_name</replaceable></option>
</para>
- <remark role="note">
- Default is empty
- </remark>
+ <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>
@@ -3135,9 +3247,10 @@
<option>--stress-threads=<replaceable>N</replaceable></option>
</para>
- <remark role="note">
- Default is 5
- </remark>
+ <para>
+ The number of threads to use in stress testing. The
+ default is 5.
+ </para>
</listitem>
<listitem>
@@ -3154,6 +3267,16 @@
<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>
+
+ <para>
+ [TODO: .pl appears to support --notimer as well]
+ </para>
</listitem>
<listitem>
@@ -3170,6 +3293,11 @@
<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>
@@ -3186,6 +3314,10 @@
<option>--use-old-data</option>
</para>
+
+ <para>
+ Do not install the test databases. (Use existing ones.)
+ </para>
</listitem>
<listitem>
@@ -3204,7 +3336,7 @@
</para>
<para>
- Unused, apparently.
+ Unused.
</para>
</listitem>
@@ -3222,6 +3354,10 @@
<option>--user=<replaceable>user_name</replaceable></option>
</para>
+
+ <para>
+ The MySQL username to use when connecting to the server.
+ </para>
</listitem>
<listitem>
@@ -3347,6 +3483,10 @@
<option>--wait-timeout=<replaceable>N</replaceable></option>
</para>
+
+ <para>
+ Unused?
+ </para>
</listitem>
<listitem>
@@ -3363,6 +3503,11 @@
<option>--warnings</option>
</para>
+
+ <para>
+ Pass the <option>--log-warnings</option> option to
+ <command>mysqld</command>.
+ </para>
</listitem>
<listitem>
@@ -3379,6 +3524,10 @@
<option>--with-ndbcluster</option>
</para>
+
+ <para>
+ Use NDB Cluster and enable test cases that require it.
+ </para>
</listitem>
<listitem>
@@ -3395,6 +3544,10 @@
<option>--with-ndbcluster-all</option>
</para>
+
+ <para>
+ Use NDB Cluster in all tests.
+ </para>
</listitem>
<listitem>
@@ -3411,6 +3564,11 @@
<option>--with-ndbcluster-only</option>
</para>
+
+ <para>
+ Run only test cases that have <literal>ndb</literal> in
+ their name.
+ </para>
</listitem>
<listitem>
@@ -3427,6 +3585,10 @@
<option>--with-ndbcluster-slave</option>
</para>
+
+ <para>
+ [Q: Unknown]
+ </para>
</listitem>
<listitem>
@@ -3510,8 +3672,7 @@
</para>
<para>
- Invoke <command>mysql-stress-test.pl</command> like this: [Q:
- In the <filename>mysql-test</filename> directory?]
+ Invoke <command>mysql-stress-test.pl</command> like this:
</para>
<programlisting>
@@ -3570,6 +3731,10 @@
<option>--abort-on-error</option>
</para>
+
+ <para>
+ [Q: Unknown]
+ </para>
</listitem>
<listitem>
@@ -3588,8 +3753,10 @@
</para>
<para>
- [Q: I don't understand what the <option>--help</option>
- text means]
+ Periodically check the file that lists the tests to be
+ run. If it has been modified, reread the file. This can be
+ useful if you update the list of tests to be run during a
+ stress test.
</para>
</listitem>
@@ -3629,8 +3796,7 @@
</para>
<para>
- Log error details in the global error log file. [Q: Which
- is named what?]
+ Log error details in the global error log file.
</para>
</listitem>
@@ -3689,6 +3855,10 @@
<option>--server-database=<replaceable>db_name</replaceable></option>
</para>
+
+ <para>
+ The database to use for the tests.
+ </para>
</listitem>
<listitem>
@@ -3705,6 +3875,13 @@
<option>--server-host=<replaceable>host_name</replaceable></option>
</para>
+
+ <para>
+ The hostname of the local host to use for making a TCP/IP
+ connection to the local server. By default, the connection
+ is made to <literal>localhost</literal> using a Unix
+ socket file.
+ </para>
</listitem>
<listitem>
@@ -3744,6 +3921,10 @@
<option>--server-password=<replaceable>password</replaceable></option>
</para>
+
+ <para>
+ The password to use when connecting to the server.
+ </para>
</listitem>
<listitem>
@@ -3760,6 +3941,11 @@
<option>--server-port=<replaceable>port_num</replaceable></option>
</para>
+
+ <para>
+ The TCP/IP port number to use for connecting to the
+ server. The default is 3306.
+ </para>
</listitem>
<listitem>
@@ -3776,6 +3962,13 @@
<option>--server-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. The default if
+ <filename>/tmp/mysql.sock</filename>.
+ </para>
</listitem>
<listitem>
@@ -3792,6 +3985,11 @@
<option>--server-user=<replaceable>user_name</replaceable></option>
</para>
+
+ <para>
+ The MySQL username to use when connecting to the server.
+ The default is <literal>root</literal>.
+ </para>
</listitem>
<listitem>
@@ -3873,6 +4071,13 @@
<option>--stress-init-file[=<replaceable>path</replaceable>]</option>
</para>
+
+ <para>
+ <replaceable>file_name</replaceable> is the location of
+ the file that contains the list of tests. If missing, the
+ default file is <filename>stress_init.txt</filename> in
+ the test suite directory.
+ </para>
</listitem>
<listitem>
@@ -3889,6 +4094,15 @@
<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>
@@ -3939,8 +4153,8 @@
the file that contains the list of tests. If
<replaceable>file_name</replaceable> is omitted, the
default file is <filename>stress-test.txt</filename> in
- the stress suite base directory. [Q: Is that correct?]
- (See <option>--stress-suite-basedir</option>.)
+ the stress suite directory. (See
+ <option>--stress-suite-basedir</option>.)
</para>
</listitem>
@@ -3958,6 +4172,12 @@
<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>
@@ -3994,6 +4214,10 @@
<option>--test-duration=<replaceable>N</replaceable></option>
</para>
+
+ <para>
+ The duration of stress testing in seconds.
+ </para>
</listitem>
<listitem>
@@ -4010,6 +4234,10 @@
<option>--test-suffix=<replaceable>str</replaceable></option>
</para>
+
+ <para>
+ [Q: Unknown]
+ </para>
</listitem>
<listitem>
@@ -4028,7 +4256,7 @@
</para>
<para>
- The number of threads.
+ The number of threads. The default is 1.
</para>
</listitem>
@@ -4046,6 +4274,11 @@
<option>--verbose</option>
</para>
+
+ <para>
+ Verbose mode. Print more information about what the
+ program does.
+ </para>
</listitem>
</itemizedlist>
Modified: trunk/mysqltest/tutorial.xml
===================================================================
--- trunk/mysqltest/tutorial.xml 2006-06-13 17:50:18 UTC (rev 2367)
+++ trunk/mysqltest/tutorial.xml 2006-06-13 19:18:23 UTC (rev 2368)
@@ -803,6 +803,15 @@
kind of information? (Now filed as Bug#20299)]
</para>
+ <para>
+ It is also possible to specify errors by means of the symbolic
+ name from <filename>mysqld_error.h</filename>:
+ </para>
+
+<programlisting>
+--error ER_TABLE_EXISTS_ERROR
+</programlisting>
+
</section>
<section id="tutorial-controlling-information">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2368 - in trunk: . mysqltest | paul | 13 Jun |
