Author: paul
Date: 2006-06-16 15:45:03 +0200 (Fri, 16 Jun 2006)
New Revision: 2400
Log:
r11370@frost: paul | 2006-06-16 08:43:22 -0500
Incorporate relevent material from refman.
Convert visible Q: (question), bug, and todo items to <remark>
elements so that they are visible only in the source, not formatted
output.
Modified:
trunk/
trunk/mysqltest/command-reference.xml
trunk/mysqltest/components.xml
trunk/mysqltest/mysqltest.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:10577
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:11349
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:11370
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:7663
Modified: trunk/mysqltest/command-reference.xml
===================================================================
--- trunk/mysqltest/command-reference.xml 2006-06-16 12:32:11 UTC (rev 2399)
+++ trunk/mysqltest/command-reference.xml 2006-06-16 13:45:03 UTC (rev 2400)
@@ -1201,11 +1201,11 @@
let $q = `select version()`;
</programlisting>
- <para>
- [Q: It appears that there can be no space between the variable
+ <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.)]
- </para>
+ 4.1.15? (Otherwise, the statement might assign no value.)
+ </remark>
</listitem>
<listitem>
@@ -1232,18 +1232,18 @@
Send the statement to the server to be executed.
</para>
- <para>
- [BUG#19890: <literal>query</literal> is broken. The entire
+ <remark role="todo">
+ BUG#19890: <literal>query</literal> is broken. The entire
command line, <emphasis>including</emphasis> the leading
<literal>query</literal> keyword, is sent to the server to be
executed as a SQL statement. That necessarily fails every
- time.]
- </para>
+ time.
+ </remark>
- <para>
- [Q: What happens if the optional statement is omitted? Same
- effect as for <literal>send</literal>?]
- </para>
+ <remark role="todo">
+ What happens if the optional statement is omitted? Same effect
+ as for <literal>send</literal>?
+ </remark>
</listitem>
<listitem>
@@ -1305,10 +1305,10 @@
the <literal>send</literal> command.
</para>
- <para>
- [BUG#20304: If no statement has yet been sent, you'll end up
- waiting a very long time for the result.]
- </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>
@@ -1440,8 +1440,8 @@
replace_result $MASTER_MYPORT MASTER_PORT;
</programlisting>
- <para>
- [Q: Inconsistencies: <literal>replace_column</literal> applies
+ <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.
@@ -1449,17 +1449,17 @@
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)]
- </para>
+ query)
+ </remark>
- <para>
- [BUG (?): The behavior for <literal>replace_result</literal>
+ <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?]
- </para>
+ found?
+ </remark>
</listitem>
<listitem>
@@ -1923,12 +1923,7 @@
<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. [Q:
- Variable names appear not to be case sensitive. Is that correct?
- If so, that leads to an ambiguity: If you refer to a variable
- named <literal>$path</literal>, is that a
- <command>mysqltest</command> variable, or the
- <literal>$PATH</literal> environment variable?]
+ case sensitive. Environment variable names are case sensitive.
</para>
</section>
@@ -1987,10 +1982,10 @@
line break).
</para>
- <para>
- [Q: No spaces allowed between parens and the expression within the
+ <remark role="todo">
+ No spaces allowed between parens and the expression within the
parens?
- </para>
+ </remark>
</section>
Modified: trunk/mysqltest/components.xml
===================================================================
--- trunk/mysqltest/components.xml 2006-06-16 12:32:11 UTC (rev 2399)
+++ trunk/mysqltest/components.xml 2006-06-16 13:45:03 UTC (rev 2400)
@@ -4,6 +4,9 @@
[
<!ENTITY % fixedchars.entities SYSTEM "fixedchars.ent">
%fixedchars.entities;
+ <!ENTITY base-url-generic-refman "http://dev.mysql.com/doc/mysql/en">
+ <!ENTITY base-url-downloads "http://dev.mysql.com/downloads/">
+ <!ENTITY base-url-uploads "ftp://ftp.mysql.com/pub/mysql/upload/">
]>
<chapter id="test-framework-components">
@@ -177,7 +180,7 @@
</para>
<programlisting>
-rpl_row_blob_innodb : BUG#18980 2006-04-10 kent Test fails randomly
+rpl_row_blob_innodb : BUG#18980 2006-04-10 kent Test fails randomly
</programlisting>
<para>
@@ -451,4 +454,128 @@
</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</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</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 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</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>
Modified: trunk/mysqltest/mysqltest.xml
===================================================================
--- trunk/mysqltest/mysqltest.xml 2006-06-16 12:32:11 UTC (rev 2399)
+++ trunk/mysqltest/mysqltest.xml 2006-06-16 13:45:03 UTC (rev 2400)
@@ -18,13 +18,6 @@
</para>
<para>
- <emphasis>Please be aware that this document is a work in
- progress.</emphasis> Unresolved questions are marked in the text
- as [Q: ...]. If you can contribute the answers to any of them,
- please do.
- </para>
-
- <para>
Document generated on:
<?dbtimestamp format="Y-m-d"?>
Modified: trunk/mysqltest/programs.xml
===================================================================
--- trunk/mysqltest/programs.xml 2006-06-16 12:32:11 UTC (rev 2399)
+++ trunk/mysqltest/programs.xml 2006-06-16 13:45:03 UTC (rev 2400)
@@ -1928,7 +1928,7 @@
</para>
<para>
- [Q: Unknown]
+ Unknown.
</para>
</listitem>
@@ -3229,7 +3229,7 @@
</para>
<para>
- [Q: Unknown]
+ Unknown.
</para>
</listitem>
@@ -3807,8 +3807,7 @@
</para>
<para>
- [Q: Unknown. (Assume the master server is already
- running?)]
+ Unknown. (Assume the master server is already running?)
</para>
</listitem>
@@ -3983,7 +3982,7 @@
</para>
<para>
- [Q: Unknown]
+ Unknown.
</para>
</listitem>
@@ -4003,7 +4002,7 @@
</para>
<para>
- [Q: Unknown]
+ Unknown.
</para>
</listitem>
@@ -5067,7 +5066,7 @@
</para>
<para>
- [Q: Unknown]
+ Unknown.
</para>
</listitem>
@@ -5208,7 +5207,7 @@
</para>
<para>
- [Q: Unknown]
+ Unknown.
</para>
</listitem>
@@ -5711,7 +5710,7 @@
</para>
<para>
- [Q: Unknown]
+ Unknown.
</para>
</listitem>
Modified: trunk/mysqltest/tutorial.xml
===================================================================
--- trunk/mysqltest/tutorial.xml 2006-06-16 12:32:11 UTC (rev 2399)
+++ trunk/mysqltest/tutorial.xml 2006-06-16 13:45:03 UTC (rev 2400)
@@ -742,12 +742,12 @@
The result is failure and an error:
</para>
- <para>
- [Q: word-police note: <literal>create table</literal> is a
+ <remark role="note">
+ Word-police note: <literal>create table</literal> is a
statement, not a query. <quote>statement</quote> would be a
better term here in the error message, because it applies to
- queries and non-queries.]
- </para>
+ queries and non-queries.
+ </remark>
<programlisting>
At line 21: query 'create table t1 (something smallint(4))'
@@ -794,14 +794,14 @@
--error S42S01
</programlisting>
- <para>
- [Q: It's inconsistent and confusing that
+ <remark role="todo">
+ It's inconsistent and confusing that
<command>mysqltest</command> displays numeric error codes in one
error-reporting context and SQLSTATE values in another
error-reporting context. Wouldn't it be better for
<command>mysqltest</command> to consistently display the same
- kind of information? (Now filed as Bug#20299)]
- </para>
+ kind of information? (Now filed as Bug#20299)
+ </remark>
<para>
It is also possible to specify errors by means of the symbolic
@@ -1127,6 +1127,64 @@
</section>
+ <section id="tutorial-other-tips">
+
+ <title>Other Test Case-Writing Tips</title>
+
+ <itemizedlist>
+
+ <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>
+
+ </itemizedlist>
+
+ </section>
+
</section>
</chapter>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2400 - in trunk: . mysqltest | paul | 16 Jun |
