web/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         There are various kinds of tests in Mono:
  10         <ul>
  11                 <li><a href="#unit"><b>Class Library Unit
  12                 Tests:</b></a> These are used to test the class
  13                 libraries.
  14
  15                 <li><a href="#compiler"><b>Compiler tests</b></a>: Both
  16                 tests that should pass and tests that should fail are included.
  17
  18                 <li><a href="#runtime"><b>Runtime tests</b></a>: Tests for
  19                 the virtual machine.
  20         </ul>
  21
  22 <a name="unit"></a>
  23 * Class Library Tests
  24
  25         All classes in Mono libraries should have comprehensive unit test
  26         suites to go with them.  Unit testing is a software engineering
  27         methodology that makes it easier to build correct code.  Every
  28         method in every class should have a set of tests to verify
  29         that they work correctly.  Mono also needs a testing framework
  30         to make it easy to write and run lots of tests.
  31
  32         In some classes, we might also provide standalone tests because of
  33         some reasons such as too huge testcases, another downloading and so on.
  34         (For example, managed XSLT has standalone test which downloads and
  35         expands some megabytes of OASIS test suite.)
  36
  37         Here I list them up as long as I know. If you are going to add another
  38         standalone tests, please add one line here. It is also recommended that
  39         you add some notes on how to build and run tests.
  40
  41         - Mono.Data/test/
  42         - System.Web/Test/TestMonoWeb : see README
  43         - System.Web.Services/Test/standalone : see README
  44         - System.Windows.Forms/SWFTest/
  45         - System.XML/System.Xml.Serialization/standalone_tests/
  46         - System.XML/Tests/System.Xml.Xsl/standalone_tests : see README
  47
  48 ** Getting started
  49
  50         If you are new to writing NUnit tests, there is a template you may use
  51         to help get started. The file is:
  52
  53                 <b>mcs/class/doc/TemplateTest.cs</b>
  54
  55         Save a copy of this file in the appropriate test subdirecty
  56         (see below), and replace all the {text} markers with
  57         appropriate code. Comments in the template are there to guide
  58         you. You should also look at existing tests to see how other
  59         people have written them.
  60         mcs/class/corlib/Test/System.Collections/CollectionBaseTest.cs
  61         is a small one that might help.
  62
  63         The directory that will contain your new file depends on the
  64         assembly/namespace of the class for which you are creating the
  65         tests.  Under mcs/class there is a directory for each
  66         assembly. In each assembly there is a Test directory,
  67         e.g. mcs/class/corlib/Test. In the Test directory there are
  68         sub-directories for each namespace in the assembly,
  69         e.g. mcs/class/corlib/Test/Sytem. Put your new test file in
  70         the appropriate sub-directory under Test for the class you are
  71         testing.
  72
  73         Once all of that is done, you can do a 'make test' from the top mcs
  74         directory.  Your test class will be automagically included in the
  75         build and the tests will be run along with all the others.
  76
  77 * Tips on writing Unit tests.
  78
  79         You should look at the <a href="http://nunit.org">NUnit documentation</a>,
  80         as it is a fantastic product, and includes fantastic documentation,
  81         but here are some tips for those of you who are already reading
  82         this web page.
  83
  84
  85 ** Provide an unique error message for Assert()
  86
  87         Include an unique message for each Assert() so that when the assert
  88         fails, it is trivial to locate it in the source. Otherwise, it may be
  89         difficult to determine which part of the test is failing. A good way
  90         to ensure unique messages is to use something like #A01, #A02 etc.
  91
  92             Ok:
  93         <pre>
  94
  95                 AssertEquals("array match", compare[0], i1[0]);
  96                 AssertEquals("array match", compare[1], i1[1]);
  97                 AssertEquals("array match", compare[2], i1[2]);
  98                 AssertEquals("array match", compare[3], i1[3]);
  99         </pre>
 100
 101             Excellent:
 102         <pre>
 103                 AssertEquals("#A01", compare[0], i1[0]);
 104                 AssertEquals("#A02", compare[1], i1[1]);
 105                 AssertEquals("#A03", compare[2], i1[2]);
 106                 AssertEquals("#A04", compare[3], i1[3]);
 107         </pre>
 108
 109         Once you used such a number in an Assert(), don't change it later on -
 110         people might use it it identify the test in bug reports or in mailing
 111         lists.
 112
 113 ** Use AssertEquals() to compare things, not Assert().
 114
 115         Do not compare two values with Assert() - if the test fails,
 116         people have no idea what went wrong while AssertEquals()
 117         reports the failed value.
 118
 119         Ok:
 120         <pre>
 121                 Assert ("A01", myTicks[0] == t1.Ticks);
 122         </pre>
 123
 124         Excellent:
 125         <pre>
 126                 AssertEquals ("A01", myTicks[0], t1.Ticks);
 127         </pre>
 128
 129 ** Test your test with the Microsoft runtime
 130
 131         If possible, try to run your testsuite with the Microsoft runtime on
 132         .NET on Windows and make sure all tests in it pass. This is especially
 133         important if you're writing a totally new testcase - without this
 134         check you can never be sure that your testcase contains no bugs ....
 135
 136         Don't worry if you're writing your test on Linux, other people can
 137         test it for you on Windows.
 138
 139         Sometimes you may discover that a test doesn't show the expected
 140         result when run with the Microsoft runtime - either because there is a
 141         bug in their runtime or something is misleading or wrong in their
 142         documentation. In this case, please put a detailed description of the
 143         problem to mcs/class/doc/API-notes and do also report it to the
 144         <a href="mailing-lists">mailing list</a> - we'll forward this to the
 145         Microsoft people from time to time to help them fix their documentation
 146         and runtime.
 147
 148 ** Unit tests.
 149
 150         Why do unit testing? It becomes simple to run automated tests
 151         for the whole library. Unit tests are a safety net - you can
 152         change part of the code and verify that you haven't broken
 153         anything. Ideally, tests are written before the actual library
 154         code itself. And every time a bug is discovered, a test should
 155         be written to demonstrate the bug and its fix. Then, if
 156         you ever reintroduce the bug, you will know immediately. For
 157         more info, read <a
 158         href="http://junit.sourceforge.net/doc/testinfected/testing.htm">
 159         JUnit Test Infected: Programmers Love Writing Tests</a>.
 160
 161
 162 ** Getting Started
 163
 164         We welcome all contributions to the Class Libary Test Suite.
 165
 166         There is information to help you get started in CVS at
 167         mcs/class/doc/NUnitGuidelines. Once you have written your test, please
 168         post it to <a href="mailing-lists.html">mono-list</a>.
 169
 170         Someone will make sure to add the file or apply the patch as
 171         appropriate. If you plan to be an on-going contributor and
 172         would like to get cvs account, email <a href="mailto:miguel@ximian.com">miguel</a>.
 173
 174         Normally, after you send a couple of well-written new files
 175         and/or patches to the list, you will be given cvs access.
 176
 177 <a name="compiler"></a>
 178 * Compiler tests
 179
 180         Mono ships with three compilers: C#, VB.NET and JScript.  The
 181         tests are ran by running the makefile target `make
 182         run-test-local' in the appropriate directory.
 183
 184         The C# compilation tests live in mcs/tests, and the C# error
 185         tests live in mcs/errors.
 186
 187         The VB.NET compilation tests live in mcs/btests.
 188
 189 <a name="runtime"></a>
 190 * Runtime Tests
 191
 192         These tests verify the virtual machine, to run these tests, do:
 193
 194 <pre>
 195         cd mono/mono/tests
 196         make test
 197 </pre>