doc/testing

   1 * Testing
   2
   3         Testing is an important part of the Mono project: every one of its
   4         three major components has a test suite tailored for its needs.  This
   5         is very helpful, because in the course of developing the software it
   6         is very common to introduce bugs in existing code.  A test suite
   7         helps us fix the bugs as soon as they are introduced.
   8
   9 ** Class Library Tests
  10
  11         All classes in Mono libraries should have comprehensive unit test
  12         suites to go with them.  Unit testing is a software engineering
  13         methodology that makes it easier to build correct code.  Every
  14         method in every class should have a set of tests to verify
  15         that they work correctly.  Mono also needs a testing framework
  16         to make it easy to write and run lots of tests.
  17
  18
  19 ** Getting started
  20
  21         If you are new to writing NUnit tests, there is a template you may use
  22         to help get started. The file is:
  23
  24                 <b>mcs/class/doc/TemplateTest.cs</b>
  25
  26         Save a copy of this file in the appropriate test subdirecty
  27         (see below), and replace all the [text] markers with
  28         appropriate code. Comments in the template are there to guide
  29         you. You should also look at existing tests to see how other
  30         people have written them.
  31         mcs/class/corlib/Test/System.Collections/CollectionBaseTest.cs
  32         is a small one that might help.
  33
  34         The directory that will contain your new file depends on the
  35         assembly/namespace of the class for which you are creating the
  36         tests.  Under mcs/class there is a directory for each
  37         assembly. In each assembly there is a Test directory,
  38         e.g. mcs/class/corlib/Test. In the Test directory there are
  39         sub-directories for each namespace in the assembly,
  40         e.g. mcs/class/corlib/Test/Sytem. Put your new test file in
  41         the appropriate sub-directory under Test for the class you are
  42         testing.
  43
  44         Once your test class is complete, you need to add it to the
  45         AllTests.cs file in the same directory as your new test. Add a
  46         call to "suite.AddTest()" passing the name of your new test
  47         class's suite property as the parameter.  You will see
  48         examples in the AllTests.cs file, so just copy and paste
  49         inside there.
  50
  51         Once all of that is done, you can do a 'make test' from the top mcs
  52         directory.  Your test class will be automagically included in the
  53         build and the tests will be run along with all the others.
  54
  55 * Tips on writing Unit tests.
  56
  57         You should look at the NUnit documentation, as it is a
  58         fantastic product, and includes fantastic documentation, but
  59         here are some tips for those of you who are already reading
  60         this web page.
  61
  62
  63 ** Provide an unique error message for Assert()
  64
  65         Include an unique message for each Assert() so that when the assert
  66         fails, it is trivial to locate the failing one. Otherwise, it may be
  67         difficult to determine which part of the test is failing. A good way
  68         to ensure unique messages is to use something like #A01, #A02 etc.
  69
  70             Ok:
  71         <pre>
  72
  73                 AssertEquals("array match", compare[0], i1[0]);
  74                 AssertEquals("array match", compare[1], i1[1]);
  75                 AssertEquals("array match", compare[2], i1[2]);
  76                 AssertEquals("array match", compare[3], i1[3]);
  77         </pre>
  78
  79             Excellent:
  80         <pre>
  81                 AssertEquals("#A01", compare[0], i1[0]);
  82                 AssertEquals("#A02", compare[1], i1[1]);
  83                 AssertEquals("#A03", compare[2], i1[2]);
  84                 AssertEquals("#A04", compare[3], i1[3]);
  85         </pre>
  86
  87         Once you used such a number in an Assert(), don't change it later on -
  88         people might use it it identify the test in bug reports or in mailing
  89         lists.
  90
  91 ** Use AssertEquals() to compare things, not Assert().
  92
  93         Do not compare two values with Assert() - if the test fails,
  94         people have no idea what went wrong while AssertEquals()
  95         reports the failed value.
  96
  97         Ok:
  98         <pre>
  99                 Assert ("A01", myTicks[0] == t1.Ticks);
 100         </pre>
 101
 102         Excellent:
 103         <pre>
 104                 AssertEquals ("A01", myTicks[0], t1.Ticks);
 105         </pre>
 106
 107 ** Constructors
 108
 109         When writing your testcase, please make sure to provide a constructor
 110         which takes no arguments:
 111
 112         <pre>
 113         public class DateTimeTest : TestCase
 114         {
 115
 116                 public DateTimeTest() : base ("[MonoTests.System.DateTimeTest]") {}
 117                 public DateTimeTest (string name): base(name) {}
 118
 119                 public static ITest Suite
 120                 {
 121                         get {
 122                                 TestSuite suite = new TestSuite ();
 123                                 return suite;
 124                         }
 125                 }
 126         }
 127         </pre>
 128
 129 ** Namespace
 130
 131         Please keep the namespace within each test directory consistent - all
 132         tests which are referenced in the same AllTests.cs must be in the same
 133         namespace. Of course you can use subnamespaces as you like -
 134         especially for subdirectories of your testsuite.
 135
 136         For instance, if your AllTests.cs is in namespace "MonoTests" and you
 137         have a subdirectory called "System", you can put all the tests in that
 138         dir into namespace "MonoTests.System".
 139
 140 ** Test your test with the Microsoft runtime
 141
 142         If possible, try to run your testsuite with the Microsoft runtime on
 143         Windows and make sure all tests in it pass. This is especially
 144         important if you're writing a totally new testcase - without this
 145         check you can never be sure that your testcase contains no bugs ....
 146
 147         Don't worry if you're writing your test on Linux, other people can
 148         test it for you on Windows.
 149
 150         Sometimes you may discover that a test doesn't show the expected
 151         result when run with the Microsoft runtime - either because there is a
 152         bug in their runtime or something is misleading or wrong in their
 153         documentation. In this case, please put a detailed description of the
 154         problem to mcs/class/doc/API-notes and do also report it to the list -
 155         we'll forward this to the Microsoft people from time to time to help
 156         them fix their documentation and runtime.
 157
 158 ** Unit tests.
 159
 160         Why do unit testing? It becomes simple to run automated tests
 161         for the whole library. Unit tests are a safety net - you can
 162         change part of the code and verify that you haven't broken
 163         anything. Ideally, tests are written before the actual library
 164         code itself. And every time a bug is discovered, a test should
 165         be written to demonstrate the bug and its fix. Then, if
 166         you ever reintroduce the bug, you will know immediately. For
 167         more info, read <a
 168         href="http://junit.sourceforge.net/doc/testinfected/testing.htm">
 169         JUnit Test Infected: Programmers Love Writing Tests</a>.
 170
 171
 172 ** Getting Started
 173
 174         We welcome all contributions to the Class Libary Test Suite.
 175
 176         There is information to help you get started in CVS at
 177         mcs/class/doc/NUnitGuidelines. Once you have written your test, please
 178         post it to <a href="mailing-lists.html">mono-list</a>.
 179
 180         Someone will make sure to add the file or apply the patch as
 181         appropriate. If you plan to be an on-going contributor and
 182         would like to get cvs account, email <a href="mailto:miguel@ximian.com">miguel</a>.
 183
 184         Normally, after you send a couple of well-written new files
 185         and/or patches to the list, you will be given cvs access.
 186