Author: paul
Date: 2006-06-16 19:38:01 +0200 (Fri, 16 Jun 2006)
New Revision: 2402
Log:
r11388@frost: paul | 2006-06-16 12:37:07 -0500
Update mysqltest info in Reference Manual.
(Point out existence of separate mysqltest manual, remove
stuff that's been moved to that manual.)
Modified:
trunk/
trunk/mysqltest/tutorial.xml
trunk/refman-4.1/extending-mysql.xml
trunk/refman-4.1/renamed-nodes.txt
trunk/refman-5.0/extending-mysql.xml
trunk/refman-5.0/renamed-nodes.txt
trunk/refman-5.1/extending-mysql.xml
trunk/refman-5.1/renamed-nodes.txt
trunk/refman-common/titles.en.ent
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:10577
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:11373
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:7663
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:10577
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:11388
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:7663
Modified: trunk/mysqltest/tutorial.xml
===================================================================
--- trunk/mysqltest/tutorial.xml 2006-06-16 14:03:41 UTC (rev 2401)
+++ trunk/mysqltest/tutorial.xml 2006-06-16 17:38:01 UTC (rev 2402)
@@ -1156,7 +1156,7 @@
let $1=1000;
while ($1)
{
- # do your queries here
+ # execute your statements here
dec $1;
}
</programlisting>
Modified: trunk/refman-4.1/extending-mysql.xml
===================================================================
--- trunk/refman-4.1/extending-mysql.xml 2006-06-16 14:03:41 UTC (rev 2401)
+++ trunk/refman-4.1/extending-mysql.xml 2006-06-16 17:38:01 UTC (rev 2402)
@@ -158,8 +158,7 @@
The test system that is included in Unix source and binary
distributions makes it possible for users and developers to
perform regression tests on the MySQL code. These tests can be
- run on Unix. They cannot currently be run in a native Windows
- environment.
+ run on Unix.
</para>
<para>
@@ -183,18 +182,28 @@
tests (<command>mysql-test-run</command>), the actual test
cases written in a special test language, and their expected
results. To run the test suite on your system after a build,
- type <command>make test</command> or
- <command>mysql-test/mysql-test-run</command> from the source
- root directory. If you have installed a binary distribution,
- change location to the installation root directory (for
- example, <filename>/usr/local/mysql</filename>), and run
- <command>mysql-test/mysql-test-run</command>. All tests should
- succeed. If any do not, you should try to find out why and
- report the problem if it indicates a bug in MySQL. See
- <xref linkend="reporting-mysqltest-bugs"/>.
+ type <command>make test</command> from the source root
+ directory, or change location to the
+ <filename>mysql-test</filename> directory and type
+ <command>./mysql-test-run</command>. If you have installed a
+ binary distribution, change location to the
+ <filename>mysql-test</filename> directory under the
+ installation root directory (for example,
+ <filename>/usr/local/mysql/mysql-test</filename>), and run
+ <command>./mysql-test-run</command>. All tests should succeed.
+ If any do not, you should try to find out why and report the
+ problem if it indicates a bug in MySQL. See
+ <xref linkend="bug-reports"/>.
</para>
<para>
+ If one test fails, you should run
+ <command>mysql-test-run</command> with the
+ <option>--force</option> option to check whether any other
+ tests fail.
+ </para>
+
+ <para>
From MySQL 4.1 on, 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
@@ -214,293 +223,26 @@
</para>
<para>
- You can run one individual test case with
- <command>mysql-test/mysql-test-run
+ In the <filename>mysql-test</filename> directory, you can run
+ an individual test case with <command>./mysql-test-run
<replaceable>test_name</replaceable></command>.
</para>
<para>
- If one test fails, you should run
- <command>mysql-test-run</command> with the
- <option>--force</option> option to check whether any other
- tests fail.
- </para>
-
- </section>
-
- <section id="extending-mysqltest">
-
- <title>&title-extending-mysqltest;</title>
-
- <para>
You can use the <command>mysqltest</command> language to write
- your own test cases. Unfortunately, we have not yet written
- full documentation for it. You can, however, look at our
- current test cases and use them as an example. The following
- points should help you get started:
+ your own test cases. This is documented in the MySQL Test
+ Framework manual, available at <ulink url="&base-url-docs;"/>.
</para>
- <itemizedlist>
-
- <listitem>
- <para>
- The tests are located in
- <filename>mysql-test/t/*.test</filename>
- </para>
- </listitem>
-
- <listitem>
- <para>
- A test case consists of statements terminated by
- <literal>;</literal> and is similar to the input of
- <command>mysql</command> command-line client. A statement
- by default is an SQL statement to be sent to MySQL server,
- unless it is recognized as an internal
- <command>mysqltest</command> command (for example,
- <command>sleep</command>).
- </para>
- </listitem>
-
- <listitem>
- <para>
- All statements that produce results—for example,
- <literal>SELECT</literal>, <literal>SHOW</literal>, or
- <literal>EXPLAIN</literal>—must be preceded with
- <replaceable>@/path/to/result/file</replaceable>. The file
- must contain the expected results. An easy way to generate
- the result file is to run <command>mysqltest -r <
- t/<replaceable>test_name</replaceable>.test</command> from
- the <filename>mysql-test</filename> directory, and then
- edit the generated result files, if needed, to adjust them
- to the expected output. In that case, be very careful
- about not adding or deleting any invisible characters.
- Make sure to only change the text or delete lines. If you
- have to insert a line, make sure that the fields are
- separated by a hard tab, and that there is a hard tab at
- the end. You may want to use <command>od -c</command> to
- make sure that your text editor has not messed up anything
- during editing. We hope that you never have to edit the
- output of <command>mysqltest -r</command> because this
- should be necessary only when you find a bug.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To be consistent with our setup, you should put your
- result files in the <filename>mysql-test/r</filename>
- directory and name them
- <filename><replaceable>test_name</replaceable>.result</filename>.
- If the test produces more than one result, you should use
- <filename><replaceable>test_name</replaceable>.a.result</filename>,
- <filename><replaceable>test_name</replaceable>.b.result</filename>,
- and so forth.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If a statement is expected to return an error, you should
- specify it with <option>--error
- <replaceable>error_number</replaceable></option> on the
- line before the statement. You can specify more than one
- error number, separated by commas.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If you are writing a replication test case, the first line
- of the test file should be <literal>source
- include/master-slave.inc;</literal>. To switch between
- master and slave, use <literal>connection
- master;</literal> and <literal>connection
- slave;</literal>. If you need to do something on an
- alternative connection, you can do <literal>connection
- master1;</literal> for the master, and <literal>connection
- slave1;</literal> for the slave.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If you need to do something in a loop, you can use
- something like this:
- </para>
-
-<programlisting>
-let $1=1000;
-while ($1)
-{
- # do your queries here
- dec $1;
-}
-</programlisting>
- </listitem>
-
- <listitem>
- <para>
- To sleep between statements, use the
- <command>sleep</command> command. It supports fractions of
- a second. For example, <command>sleep 1.3;</command>
- sleeps 1.3 seconds.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To run the slave with additional options for your test
- case, put them in the command-line format in
- <filename>mysql-test/t/<replaceable>test_name</replaceable>-slave.opt</filename>.
- For the master, put them in
- <filename>mysql-test/t/<replaceable>test_name</replaceable>-master.opt</filename>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If you have a question about the test suite, or have a
- test case to contribute, send an email message to the
- MySQL <literal>internals</literal> mailing list. See
- <xref linkend="mailing-lists"/>. This list does not accept
- attachments, so you should FTP all the relevant files to:
- <ulink url="&base-url-uploads;"/>
- </para>
- </listitem>
-
- </itemizedlist>
-
- </section>
-
- <section id="reporting-mysqltest-bugs">
-
- <title>&title-reporting-mysqltest-bugs;</title>
-
<para>
- If test cases from the test suite fail, you should do the
- following:
+ If you have a question about the test suite, or have a test
+ case to contribute, send an email message to the MySQL
+ <literal>internals</literal> mailing list. See
+ <xref linkend="mailing-lists"/>. This list does not accept
+ attachments, so you should FTP all the relevant files to:
+ <ulink url="&base-url-uploads;"/>
</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
- <xref linkend="bug-reports"/>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Make sure to include the output of
- <command>mysql-test-run</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>
-cd mysql-test
-mysql-test-run --local <replaceable>test_name</replaceable>
-</programlisting>
-
- <para>
- If this fails, you should configure MySQL with
- <option>--with-debug</option> and run
- <command>mysql-test-run</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</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 our manual to
- see whether there are any platform-specific issues for
- your system (see
- <xref linkend="operating-system-specific-notes"/>). 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</command> with either or both of
- the <option>--gdb</option> and <option>--debug</option>
- options. See <xref linkend="making-trace-files"/>.
- </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>. See
- <xref linkend="configure-options"/>.
- </para>
- </listitem>
-
- </itemizedlist>
-
</section>
</section>
Modified: trunk/refman-4.1/renamed-nodes.txt
===================================================================
--- trunk/refman-4.1/renamed-nodes.txt 2006-06-16 14:03:41 UTC (rev 2401)
+++ trunk/refman-4.1/renamed-nodes.txt 2006-06-16 17:38:01 UTC (rev 2402)
@@ -219,3 +219,5 @@
odbc-net-op-c-sharp-cp myodbc-examples-programming-net-csharp
odbc-net-op-vb-cp myodbc-examples-programming-net-vb
myodbc-credits myodbc-support-credits
+extending-mysqltest mysql-test-suite
+reporting-mysqltest-bugs mysql-test-suite
Modified: trunk/refman-5.0/extending-mysql.xml
===================================================================
--- trunk/refman-5.0/extending-mysql.xml 2006-06-16 14:03:41 UTC (rev 2401)
+++ trunk/refman-5.0/extending-mysql.xml 2006-06-16 17:38:01 UTC (rev 2402)
@@ -158,8 +158,7 @@
The test system that is included in Unix source and binary
distributions makes it possible for users and developers to
perform regression tests on the MySQL code. These tests can be
- run on Unix. They cannot currently be run in a native Windows
- environment.
+ run on Unix.
</para>
<para>
@@ -183,18 +182,28 @@
tests (<command>mysql-test-run</command>), the actual test
cases written in a special test language, and their expected
results. To run the test suite on your system after a build,
- type <command>make test</command> or
- <command>mysql-test/mysql-test-run</command> from the source
- root directory. If you have installed a binary distribution,
- change location to the installation root directory (for
- example, <filename>/usr/local/mysql</filename>), and run
- <command>mysql-test/mysql-test-run</command>. All tests should
- succeed. If any do not, you should try to find out why and
- report the problem if it indicates a bug in MySQL. See
- <xref linkend="reporting-mysqltest-bugs"/>.
+ type <command>make test</command> from the source root
+ directory, or change location to the
+ <filename>mysql-test</filename> directory and type
+ <command>./mysql-test-run</command>. If you have installed a
+ binary distribution, change location to the
+ <filename>mysql-test</filename> directory under the
+ installation root directory (for example,
+ <filename>/usr/local/mysql/mysql-test</filename>), and run
+ <command>./mysql-test-run</command>. All tests should succeed.
+ If any do not, you should try to find out why and report the
+ problem if it indicates a bug in MySQL. See
+ <xref linkend="bug-reports"/>.
</para>
<para>
+ If one test fails, you should run
+ <command>mysql-test-run</command> with the
+ <option>--force</option> option to check whether any other
+ tests fail.
+ </para>
+
+ <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
@@ -205,293 +214,26 @@
</para>
<para>
- You can run one individual test case with
- <command>mysql-test/mysql-test-run
+ In the <filename>mysql-test</filename> directory, you can run
+ an individual test case with <command>./mysql-test-run
<replaceable>test_name</replaceable></command>.
</para>
<para>
- If one test fails, you should run
- <command>mysql-test-run</command> with the
- <option>--force</option> option to check whether any other
- tests fail.
- </para>
-
- </section>
-
- <section id="extending-mysqltest">
-
- <title>&title-extending-mysqltest;</title>
-
- <para>
You can use the <command>mysqltest</command> language to write
- your own test cases. Unfortunately, we have not yet written
- full documentation for it. You can, however, look at our
- current test cases and use them as an example. The following
- points should help you get started:
+ your own test cases. This is documented in the MySQL Test
+ Framework manual, available at <ulink url="&base-url-docs;"/>.
</para>
- <itemizedlist>
-
- <listitem>
- <para>
- The tests are located in
- <filename>mysql-test/t/*.test</filename>
- </para>
- </listitem>
-
- <listitem>
- <para>
- A test case consists of statements terminated by
- <literal>;</literal> and is similar to the input of
- <command>mysql</command> command-line client. A statement
- by default is an SQL statement to be sent to MySQL server,
- unless it is recognized as an internal
- <command>mysqltest</command> command (for example,
- <command>sleep</command>).
- </para>
- </listitem>
-
- <listitem>
- <para>
- All statements that produce results—for example,
- <literal>SELECT</literal>, <literal>SHOW</literal>, or
- <literal>EXPLAIN</literal>—must be preceded with
- <replaceable>@/path/to/result/file</replaceable>. The file
- must contain the expected results. An easy way to generate
- the result file is to run <command>mysqltest -r <
- t/<replaceable>test_name</replaceable>.test</command> from
- the <filename>mysql-test</filename> directory, and then
- edit the generated result files, if needed, to adjust them
- to the expected output. In that case, be very careful
- about not adding or deleting any invisible characters.
- Make sure to only change the text or delete lines. If you
- have to insert a line, make sure that the fields are
- separated by a hard tab, and that there is a hard tab at
- the end. You may want to use <command>od -c</command> to
- make sure that your text editor has not messed up anything
- during editing. We hope that you never have to edit the
- output of <command>mysqltest -r</command> because this
- should be necessary only when you find a bug.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To be consistent with our setup, you should put your
- result files in the <filename>mysql-test/r</filename>
- directory and name them
- <filename><replaceable>test_name</replaceable>.result</filename>.
- If the test produces more than one result, you should use
- <filename><replaceable>test_name</replaceable>.a.result</filename>,
- <filename><replaceable>test_name</replaceable>.b.result</filename>,
- and so forth.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If a statement is expected to return an error, you should
- specify it with <option>--error
- <replaceable>error_number</replaceable></option> on the
- line before the statement. You can specify more than one
- error number, separated by commas.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If you are writing a replication test case, the first line
- of the test file should be <literal>source
- include/master-slave.inc;</literal>. To switch between
- master and slave, use <literal>connection
- master;</literal> and <literal>connection
- slave;</literal>. If you need to do something on an
- alternative connection, you can do <literal>connection
- master1;</literal> for the master, and <literal>connection
- slave1;</literal> for the slave.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If you need to do something in a loop, you can use
- something like this:
- </para>
-
-<programlisting>
-let $1=1000;
-while ($1)
-{
- # do your queries here
- dec $1;
-}
-</programlisting>
- </listitem>
-
- <listitem>
- <para>
- To sleep between statements, use the
- <command>sleep</command> command. It supports fractions of
- a second. For example, <command>sleep 1.3;</command>
- sleeps 1.3 seconds.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To run the slave with additional options for your test
- case, put them in the command-line format in
- <filename>mysql-test/t/<replaceable>test_name</replaceable>-slave.opt</filename>.
- For the master, put them in
- <filename>mysql-test/t/<replaceable>test_name</replaceable>-master.opt</filename>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If you have a question about the test suite, or have a
- test case to contribute, send an email message to the
- MySQL <literal>internals</literal> mailing list. See
- <xref linkend="mailing-lists"/>. This list does not accept
- attachments, so you should FTP all the relevant files to:
- <ulink url="&base-url-uploads;"/>
- </para>
- </listitem>
-
- </itemizedlist>
-
- </section>
-
- <section id="reporting-mysqltest-bugs">
-
- <title>&title-reporting-mysqltest-bugs;</title>
-
<para>
- If test cases from the test suite fail, you should do the
- following:
+ If you have a question about the test suite, or have a test
+ case to contribute, send an email message to the MySQL
+ <literal>internals</literal> mailing list. See
+ <xref linkend="mailing-lists"/>. This list does not accept
+ attachments, so you should FTP all the relevant files to:
+ <ulink url="&base-url-uploads;"/>
</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
- <xref linkend="bug-reports"/>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Make sure to include the output of
- <command>mysql-test-run</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>
-cd mysql-test
-mysql-test-run --local <replaceable>test_name</replaceable>
-</programlisting>
-
- <para>
- If this fails, you should configure MySQL with
- <option>--with-debug</option> and run
- <command>mysql-test-run</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</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 our manual to
- see whether there are any platform-specific issues for
- your system (see
- <xref linkend="operating-system-specific-notes"/>). 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</command> with either or both of
- the <option>--gdb</option> and <option>--debug</option>
- options. See <xref linkend="making-trace-files"/>.
- </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>. See
- <xref linkend="configure-options"/>.
- </para>
- </listitem>
-
- </itemizedlist>
-
</section>
</section>
Modified: trunk/refman-5.0/renamed-nodes.txt
===================================================================
--- trunk/refman-5.0/renamed-nodes.txt 2006-06-16 14:03:41 UTC (rev 2401)
+++ trunk/refman-5.0/renamed-nodes.txt 2006-06-16 17:38:01 UTC (rev 2402)
@@ -519,4 +519,5 @@
odbc-net-op-c-sharp-cp myodbc-examples-programming-net-csharp
odbc-net-op-vb-cp myodbc-examples-programming-net-vb
myodbc-credits myodbc-support-credits
-
+extending-mysqltest mysql-test-suite
+reporting-mysqltest-bugs mysql-test-suite
Modified: trunk/refman-5.1/extending-mysql.xml
===================================================================
--- trunk/refman-5.1/extending-mysql.xml 2006-06-16 14:03:41 UTC (rev 2401)
+++ trunk/refman-5.1/extending-mysql.xml 2006-06-16 17:38:01 UTC (rev 2402)
@@ -166,8 +166,7 @@
The test system that is included in Unix source and binary
distributions makes it possible for users and developers to
perform regression tests on the MySQL code. These tests can be
- run on Unix. They cannot currently be run in a native Windows
- environment.
+ run on Unix.
</para>
<para>
@@ -188,318 +187,61 @@
<para>
The test system consists of a test language interpreter
(<command>mysqltest</command>), a shell script to run all
- tests (<command>mysql-test-run</command>), the actual test
+ tests (<command>mysql-test-run.pl</command>), the actual test
cases written in a special test language, and their expected
results. To run the test suite on your system after a build,
- type <command>make test</command> or
- <command>mysql-test/mysql-test-run</command> from the source
- root directory. If you have installed a binary distribution,
- change location to the installation root directory (for
- example, <filename>/usr/local/mysql</filename>), and run
- <command>mysql-test/mysql-test-run</command>. All tests should
- succeed. If any do not, you should try to find out why and
- report the problem if it indicates a bug in MySQL. See
- <xref linkend="reporting-mysqltest-bugs"/>.
+ type <command>make test</command> from the source root
+ directory, or change location to the
+ <filename>mysql-test</filename> directory and type
+ <command>./mysql-test-run.pl</command>. If you have installed a
+ binary distribution, change location to the
+ <filename>mysql-test</filename> directory under the
+ installation root directory (for example,
+ <filename>/usr/local/mysql/mysql-test</filename>), and run
+ <command>./mysql-test-run.pl</command>. All tests should succeed.
+ If any do not, you should try to find out why and report the
+ problem if it indicates a bug in MySQL. See
+ <xref linkend="bug-reports"/>.
</para>
<para>
+ If one test fails, you should run
+ <command>mysql-test-run.pl</command> with the
+ <option>--force</option> option to check whether any other
+ tests fail.
+ </para>
+
+ <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 edit
- <command>mysql-test-run</command> and change the values of the
+ <command>mysql-test-run.pl</command> and change the values of the
master or slave port to one that is available.
</para>
<para>
- You can run one individual test case with
- <command>mysql-test/mysql-test-run
+ In the <filename>mysql-test</filename> directory, you can run
+ an individual test case with <command>./mysql-test-run
<replaceable>test_name</replaceable></command>.
</para>
<para>
- If one test fails, you should run
- <command>mysql-test-run</command> with the
- <option>--force</option> option to check whether any other
- tests fail.
- </para>
-
- </section>
-
- <section id="extending-mysqltest">
-
- <title>&title-extending-mysqltest;</title>
-
- <para>
You can use the <command>mysqltest</command> language to write
- your own test cases. Unfortunately, we have not yet written
- full documentation for it. You can, however, look at our
- current test cases and use them as an example. The following
- points should help you get started:
+ your own test cases. This is documented in the MySQL Test
+ Framework manual, available at <ulink url="&base-url-docs;"/>.
</para>
- <itemizedlist>
-
- <listitem>
- <para>
- The tests are located in
- <filename>mysql-test/t/*.test</filename>
- </para>
- </listitem>
-
- <listitem>
- <para>
- A test case consists of statements terminated by
- <literal>;</literal> and is similar to the input of
- <command>mysql</command> command-line client. A statement
- by default is an SQL statement to be sent to MySQL server,
- unless it is recognized as an internal
- <command>mysqltest</command> command (for example,
- <command>sleep</command>).
- </para>
- </listitem>
-
- <listitem>
- <para>
- All statements that produce results—for example,
- <literal>SELECT</literal>, <literal>SHOW</literal>, or
- <literal>EXPLAIN</literal>—must be preceded with
- <replaceable>@/path/to/result/file</replaceable>. The file
- must contain the expected results. An easy way to generate
- the result file is to run <command>mysqltest -r <
- t/<replaceable>test_name</replaceable>.test</command> from
- the <filename>mysql-test</filename> directory, and then
- edit the generated result files, if needed, to adjust them
- to the expected output. In that case, be very careful
- about not adding or deleting any invisible characters.
- Make sure to only change the text or delete lines. If you
- have to insert a line, make sure that the fields are
- separated by a hard tab, and that there is a hard tab at
- the end. You may want to use <command>od -c</command> to
- make sure that your text editor has not messed up anything
- during editing. We hope that you never have to edit the
- output of <command>mysqltest -r</command> because this
- should be necessary only when you find a bug.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To be consistent with our setup, you should put your
- result files in the <filename>mysql-test/r</filename>
- directory and name them
- <filename><replaceable>test_name</replaceable>.result</filename>.
- If the test produces more than one result, you should use
- <filename><replaceable>test_name</replaceable>.a.result</filename>,
- <filename><replaceable>test_name</replaceable>.b.result</filename>,
- and so forth.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If a statement is expected to return an error, you should
- specify it with <option>--error
- <replaceable>error_number</replaceable></option> on the
- line before the statement. You can specify more than one
- error number, separated by commas.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If you are writing a replication test case, the first line
- of the test file should be <literal>source
- include/master-slave.inc;</literal>. To switch between
- master and slave, use <literal>connection
- master;</literal> and <literal>connection
- slave;</literal>. If you need to do something on an
- alternative connection, you can do <literal>connection
- master1;</literal> for the master, and <literal>connection
- slave1;</literal> for the slave.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If you need to do something in a loop, you can use
- something like this:
- </para>
-
-<programlisting>
-let $1=1000;
-while ($1)
-{
- # do your queries here
- dec $1;
-}
-</programlisting>
- </listitem>
-
- <listitem>
- <para>
- To sleep between statements, use the
- <command>sleep</command> command. It supports fractions of
- a second. For example, <command>sleep 1.3;</command>
- sleeps 1.3 seconds.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To run the slave with additional options for your test
- case, put them in the command-line format in
- <filename>mysql-test/t/<replaceable>test_name</replaceable>-slave.opt</filename>.
- For the master, put them in
- <filename>mysql-test/t/<replaceable>test_name</replaceable>-master.opt</filename>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If you have a question about the test suite, or have a
- test case to contribute, send an email message to the
- MySQL <literal>internals</literal> mailing list. See
- <xref linkend="mailing-lists"/>. This list does not accept
- attachments, so you should FTP all the relevant files to:
- <ulink url="&base-url-uploads;"/>
- </para>
- </listitem>
-
- </itemizedlist>
-
- </section>
-
- <section id="reporting-mysqltest-bugs">
-
- <title>&title-reporting-mysqltest-bugs;</title>
-
<para>
- If test cases from the test suite fail, you should do the
- following:
+ If you have a question about the test suite, or have a test
+ case to contribute, send an email message to the MySQL
+ <literal>internals</literal> mailing list. See
+ <xref linkend="mailing-lists"/>. This list does not accept
+ attachments, so you should FTP all the relevant files to:
+ <ulink url="&base-url-uploads;"/>
</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
- <xref linkend="bug-reports"/>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Make sure to include the output of
- <command>mysql-test-run</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>
-cd mysql-test
-mysql-test-run --local <replaceable>test_name</replaceable>
-</programlisting>
-
- <para>
- If this fails, you should configure MySQL with
- <option>--with-debug</option> and run
- <command>mysql-test-run</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</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 our manual to
- see whether there are any platform-specific issues for
- your system (see
- <xref linkend="operating-system-specific-notes"/>). 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</command> with either or both of
- the <option>--gdb</option> and <option>--debug</option>
- options. See <xref linkend="making-trace-files"/>.
- </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>. See
- <xref linkend="configure-options"/>.
- </para>
- </listitem>
-
- </itemizedlist>
-
</section>
</section>
Modified: trunk/refman-5.1/renamed-nodes.txt
===================================================================
--- trunk/refman-5.1/renamed-nodes.txt 2006-06-16 14:03:41 UTC (rev 2401)
+++ trunk/refman-5.1/renamed-nodes.txt 2006-06-16 17:38:01 UTC (rev 2402)
@@ -232,3 +232,5 @@
odbc-net-op-c-sharp-cp myodbc-examples-programming-net-csharp
odbc-net-op-vb-cp myodbc-examples-programming-net-vb
myodbc-credits myodbc-support-credits
+extending-mysqltest mysql-test-suite
+reporting-mysqltest-bugs mysql-test-suite
Modified: trunk/refman-common/titles.en.ent
===================================================================
--- trunk/refman-common/titles.en.ent 2006-06-16 14:03:41 UTC (rev 2401)
+++ trunk/refman-common/titles.en.ent 2006-06-16 17:38:01 UTC (rev 2402)
@@ -454,7 +454,6 @@
<!ENTITY title-export-of-data "How to Export a Table or Query from Access to MySQL?">
<!ENTITY title-extended-show "Extensions to <literal>SHOW</literal> Statements">
<!ENTITY title-extending-mysql "Extending MySQL">
-<!ENTITY title-extending-mysqltest "Extending the MySQL Test Suite">
<!ENTITY title-extensions-to-ansi "MySQL Extensions to Standard SQL">
<!ENTITY title-features "The Main Features of MySQL">
<!ENTITY title-federated-description "Description of the <literal>FEDERATED</literal> Storage Engine">
@@ -1721,7 +1720,6 @@
<!ENTITY title-replication-upgrade "Upgrading a Replication Setup">
<!ENTITY title-replication-upgrade-4-0 "Upgrading Replication to 4.0 or 4.1">
<!ENTITY title-replication-upgrade-5-0 "Upgrading Replication to 5.0">
-<!ENTITY title-reporting-mysqltest-bugs "How to Report Bugs in the MySQL Test Suite">
<!ENTITY title-reproducible-test-case "Making a Test Case If You Experience Table Corruption">
<!ENTITY title-request-access "Access Control, Stage 2: Request Verification">
<!ENTITY title-reserved-words "Treatment of Reserved Words in MySQL">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2402 - in trunk: . mysqltest refman-4.1 refman-5.0 refman-5.1 refman-common | paul | 16 Jun |
