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
  21                 <li><a href="#aspnet"><b>ASP.NET tests</b></a>: ASP.NET tests.
  22         </ul>
  23
  24 <a name="unit"></a>
  25 * Class Library Tests
  26
  27         All classes in Mono libraries should have comprehensive unit test
  28         suites to go with them.  Unit testing is a software engineering
  29         methodology that makes it easier to build correct code.  Every
  30         method in every class should have a set of tests to verify
  31         that they work correctly.  Mono also needs a testing framework
  32         to make it easy to write and run lots of tests.
  33
  34         In some classes, we might also provide standalone tests because of
  35         some reasons such as too huge testcases, another downloading and so on.
  36         (For example, managed XSLT has standalone test which downloads and
  37         expands some megabytes of OASIS test suite.)
  38
  39         Here I list them up as long as I know. If you are going to add another
  40         standalone tests, please add one line here. It is also recommended that
  41         you add some notes on how to build and run tests.
  42
  43         <ul>
  44
  45                 * Mono.Data/test/
  46                 * System.Data/Test, and some individual ADO.NET libraries:
  47                   there are some standalone tests. See the bottom of <a href="ado-net.html">
  48                   ADO.NET page</a> for detail.
  49                 * System.Web/Test/TestMonoWeb : see README
  50                 * System.Web.Services/Test/standalone : see README
  51                 * System.Windows.Forms/SWFTest/
  52                 * System.XML/Tests/System.Xml.Schema/standalone_tests : see README
  53                 * System.XML/System.Xml.Serialization/standalone_tests/
  54                 * System.XML/Tests/System.Xml.Xsl/standalone_tests : see README
  55
  56         </ul>
  57
  58 ** Getting started
  59
  60         If you are new to writing NUnit tests, there is a template you may use
  61         to help get started. The file is:
  62
  63                 <b>mcs/class/doc/TemplateTest.cs</b>
  64
  65         Save a copy of this file in the appropriate test subdirecty
  66         (see below), and replace all the {text} markers with
  67         appropriate code. Comments in the template are there to guide
  68         you. You should also look at existing tests to see how other
  69         people have written them.
  70         mcs/class/corlib/Test/System.Collections/CollectionBaseTest.cs
  71         is a small one that might help.
  72
  73         The directory that will contain your new file depends on the
  74         assembly/namespace of the class for which you are creating the
  75         tests.  Under mcs/class there is a directory for each
  76         assembly. In each assembly there is a Test directory,
  77         e.g. mcs/class/corlib/Test. In the Test directory there are
  78         sub-directories for each namespace in the assembly,
  79         e.g. mcs/class/corlib/Test/Sytem. Put your new test file in
  80         the appropriate sub-directory under Test for the class you are
  81         testing.
  82
  83         Once all of that is done, you can do a 'make test' from the top mcs
  84         directory.  Your test class will be automagically included in the
  85         build and the tests will be run along with all the others.
  86
  87 * Tips on writing Unit tests.
  88
  89         You should look at the <a href="http://nunit.org">NUnit documentation</a>,
  90         as it is a fantastic product, and includes fantastic documentation,
  91         but here are some tips for those of you who are already reading
  92         this web page.
  93
  94
  95 ** Provide an unique error message for Assert()
  96
  97         Include an unique message for each Assert() so that when the assert
  98         fails, it is trivial to locate it in the source. Otherwise, it may be
  99         difficult to determine which part of the test is failing. A good way
 100         to ensure unique messages is to use something like #A01, #A02 etc.
 101
 102             Ok:
 103         <pre>
 104
 105                 AssertEquals("array match", compare[0], i1[0]);
 106                 AssertEquals("array match", compare[1], i1[1]);
 107                 AssertEquals("array match", compare[2], i1[2]);
 108                 AssertEquals("array match", compare[3], i1[3]);
 109         </pre>
 110
 111             Excellent:
 112         <pre>
 113                 AssertEquals("#A01", compare[0], i1[0]);
 114                 AssertEquals("#A02", compare[1], i1[1]);
 115                 AssertEquals("#A03", compare[2], i1[2]);
 116                 AssertEquals("#A04", compare[3], i1[3]);
 117         </pre>
 118
 119         Once you used such a number in an Assert(), don't change it later on -
 120         people might use it it identify the test in bug reports or in mailing
 121         lists.
 122
 123 ** Use AssertEquals() to compare things, not Assert().
 124
 125         Do not compare two values with Assert() - if the test fails,
 126         people have no idea what went wrong while AssertEquals()
 127         reports the failed value.
 128
 129         Ok:
 130         <pre>
 131                 Assert ("A01", myTicks[0] == t1.Ticks);
 132         </pre>
 133
 134         Excellent:
 135         <pre>
 136                 AssertEquals ("A01", myTicks[0], t1.Ticks);
 137         </pre>
 138
 139 ** Test your test with the Microsoft runtime
 140
 141         If possible, try to run your testsuite with the Microsoft runtime on
 142         .NET on Windows and make sure all tests in it pass. This is especially
 143         important if you're writing a totally new testcase - without this
 144         check you can never be sure that your testcase contains no bugs ....
 145
 146         Don't worry if you're writing your test on Linux, other people can
 147         test it for you on Windows.
 148
 149         Sometimes you may discover that a test doesn't show the expected
 150         result when run with the Microsoft runtime - either because there is a
 151         bug in their runtime or something is misleading or wrong in their
 152         documentation. In this case, please put a detailed description of the
 153         problem to mcs/class/doc/API-notes and do also report it to the
 154         <a href="mailing-lists">mailing list</a> - we'll forward this to the
 155         Microsoft people from time to time to help them fix their documentation
 156         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
 187 <a name="compiler"></a>
 188 * Compiler tests
 189
 190         Mono ships with three compilers: C#, VB.NET and JScript.  The
 191         tests are ran by running the makefile target `make
 192         run-test-local' in the appropriate directory.
 193
 194         The C# compilation tests live in mcs/tests, and the C# error
 195         tests live in mcs/errors.
 196
 197         The VB.NET compilation tests live in mcs/btests.
 198
 199 <a name="runtime"></a>
 200 * Runtime Tests
 201
 202         These tests verify the virtual machine, to run these tests, do:
 203
 204 <pre>
 205         cd mono/mono/tests
 206         make test
 207 </pre>
 208
 209 <a name="aspnet"></a>
 210 * ASP.NET tests
 211
 212         XSP, the Mono ASP.NET server has tests for ASP.NET pages. It uses
 213         <a href="http://nunitasp.sourceforge.net">NUnitAsp</a>. Right now
 214         it only has standalone tests, ie., tests that do not need their own
 215         global.asax or web.config files.
 216
 217         If you want to run them, get the xsp CVS module and install it. Then:
 218 <pre>
 219         cd xsp/nunit-tests
 220         make
 221         cd standalone
 222         xsp
 223 </pre>
 224
 225         And from another terminal:
 226 <pre>
 227         cd xsp/nunit-tests/standalone
 228         nunit-console standalone-tests.dll
 229 </pre>
 230