List:Commits« Previous MessageNext Message »
From:paul Date:June 16 2006 1:45pm
Subject:svn commit - mysqldoc@docsrva: r2400 - in trunk: . mysqltest
View as plain text  
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&gt; <userinput>cd mysql-test</userinput>
+shell&gt; <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: . mysqltestpaul16 Jun