Author: paul
Date: 2007-11-12 16:32:50 +0100 (Mon, 12 Nov 2007)
New Revision: 8659
Log:
r26906@frost: paul | 2007-11-12 09:24:14 -0600
Test case coding guideline information.
Modified:
trunk/mysqltest/command-reference.xml
trunk/mysqltest/tutorial.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:32620
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:26904
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:21581
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:32620
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:26906
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:21581
Modified: trunk/mysqltest/command-reference.xml
===================================================================
--- trunk/mysqltest/command-reference.xml 2007-11-12 14:53:01 UTC (rev 8658)
+++ trunk/mysqltest/command-reference.xml 2007-11-12 15:32:50 UTC (rev 8659)
Changed blocks: 1, Lines Added: 1, Lines Deleted: 1; 410 bytes
@@ -183,7 +183,7 @@
<programlisting>
echo issue a select statement
-select 1
+select 1;
echo done issuing the select statement
</programlisting>
Modified: trunk/mysqltest/tutorial.xml
===================================================================
--- trunk/mysqltest/tutorial.xml 2007-11-12 14:53:01 UTC (rev 8658)
+++ trunk/mysqltest/tutorial.xml 2007-11-12 15:32:50 UTC (rev 8659)
Changed blocks: 3, Lines Added: 200, Lines Deleted: 6; 7773 bytes
@@ -528,9 +528,11 @@
<listitem>
<para>
- Database names: For tests that need to operate outside the
- <literal>test</literal> database, database names should
- contain <quote>test</quote> and/or begin with
+ Database names: Unless you have a special reason not to, use
+ the default database named <literal>test</literal> that is
+ already created for you. For tests that need to operate
+ outside the <literal>test</literal> database, database names
+ should contain <quote>test</quote> and/or begin with
<quote>mysql</quote> (for example,
<literal>mysqltest1</literal>,
<literal>mysqltest2</literal>)
@@ -559,12 +561,196 @@
tables as you wish.
</para>
+ </section>
+
+ <section id="tutorial-coding-guidelines">
+
+ <title>Coding Guidelines</title>
+
<para>
- Unless you have a special reason not to, use the default
- database named <literal>test</literal> that is already created
- for you.
+ When you write a test case, please keep in mind the following
+ general guidelines.
</para>
+ <para>
+ There are C/C++ coding guidelines here; please apply them when
+ it makes sense to do so:
+ </para>
+
+<programlisting>
+<ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Coding_Guidelines"/>
+</programlisting>
+
+ <para>
+ Other guidelines may be found in this page, which discusses
+ general principles of test-case writing:
+ </para>
+
+<programlisting>
+<ulink url="http://forge.mysql.com/wiki/How_to_Create_Good_Tests"/>
+</programlisting>
+
+ <para>
+ The following guidelines are particularly applicable to
+ writing test cases:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Avoid lines longer than 80 characters unless there is no
+ other choice.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Comment lines should start with
+ <quote><literal>#</literal></quote> and not with
+ <quote><literal>--</literal></quote>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Use spaces and not tabs.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Write SQL statements using the same style as our manual:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Use uppercase for SQL keywords.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Use lowercase for identifiers (names of objects such as
+ databases, tables, columns, and so forth).
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Ignore this guidline if your intent is to test lettercase
+ processing, of course.
+ </para>
+
+ <para>
+ You will notice that the majority of existing test cases
+ currently do not follow the lettercase guideline and are
+ written entirely in lowercase. Please use the guideline for
+ new tests. Lettercase for older tests can be left as is,
+ unless perhaps you need to revise them significantly.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Break a long SQL statement into multiple lines to make it
+ more readable. This means that you will need to write it
+ using a <quote><literal>;</literal></quote> delimiter at the
+ end of the statement rather than using
+ <quote><literal>--</literal></quote> at the beginning
+ because the latter style works only for single-line
+ statements.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Include comments. They save the time of others. In
+ particular:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Please include a header in test files that indicates the
+ purpose of the test and references the corresponding
+ worklog task, if any.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Comments for a test that is related to a bug report
+ should include the bug number and title.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Worklog and bug numbers are useful because they enable
+ people who are interested in additional background related
+ to the test case to know which worklog entries or bug
+ reports to read.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Example SQL statement:
+ </para>
+
+<programlisting>
+SELECT f1 AS "my_column", f10 ....
+FROM mysqltest1.t5
+WHERE (f2 BETWEEN 17 AND 25 OR f2 = 61)
+ AND f3 IN (SELECT ....
+ FROM mysqltest1.t4
+ WHERE .....)
+ORDER BY ... ;
+</programlisting>
+
+ <para>
+ Example test file header:
+ </para>
+
+<programlisting>
+########### suite/funcs_1/t/a_processlist_val_no_prot.test #############
+# #
+# Testing of values within INFORMATION_SCHEMA.PROCESSLIST #
+# #
+# The prepared statement variant of this test is #
+# suite/funcs_1/t/b_processlist_val_ps.test. #
+# #
+# There is important documentation within #
+# suite/funcs_1/datadict/processlist_val.inc #
+# #
+# Note(mleich): #
+# The name "a_process..." with the unusual prefix "a_" is #
+# caused by the fact that this test should run as second test, that #
+# means direct after server startup and a_processlist_priv_no_prot. #
+# Otherwise the connection IDs within the processlist would differ. #
+# #
+# Creation: #
+# 2007-08-09 mleich Implement this test as part of #
+# WL#3982 Test information_schema.processlist #
+# #
+########################################################################
+</programlisting>
+
+ <para>
+ Example test reference to bug report:
+ </para>
+
+<programlisting>
+# Bug#3671 Stored procedure crash if function has "set @variable=param"
+</programlisting>
+
</section>
<section id="tutorial-cleaning-up">
@@ -835,6 +1021,14 @@
--error ER_TABLE_EXISTS_ERROR
</programlisting>
+ <para>
+ Symbolic names are more stable than error numbers because the
+ numbers sometimes change, particularly for those created during
+ recent development. For such errors, use of numbers rather than
+ the names in a test case will require test to be revised should
+ the numbers change.
+ </para>
+
</section>
<section id="tutorial-controlling-information">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r8659 - in trunk: . mysqltest | paul | 12 Nov |
