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
  23                 <li><a href="#ws"><b>Web Services tests</b></a>: Web Services
  24                 client/server tests.
  25         </ul>
  26
  27 <a name="unit"></a>
  28 * Class Library Tests
  29
  30         All classes in Mono libraries should have comprehensive unit test
  31         suites to go with them.  Unit testing is a software engineering
  32         methodology that makes it easier to build correct code.  Every
  33         method in every class should have a set of tests to verify
  34         that they work correctly.  Mono also needs a testing framework
  35         to make it easy to write and run lots of tests.
  36
  37         In some classes, we might also provide standalone tests because of
  38         some reasons such as too huge testcases, another downloading and so on.
  39         (For example, managed XSLT has standalone test which downloads and
  40         expands some megabytes of OASIS test suite.)
  41
  42         Here I list them up as long as I know. If you are going to add another
  43         standalone tests, please add one line here. It is also recommended that
  44         you add some notes on how to build and run tests.
  45
  46         <ul>
  47
  48                 * Mono.Data/test/
  49                 * System.Data/Test, and some individual ADO.NET libraries:
  50                   there are some standalone tests. See the bottom of <a href="ado-net.html">
  51                   ADO.NET page</a> for detail.
  52                 * System.Web/Test/TestMonoWeb : see README
  53                 * System.Web.Services/Test/standalone : see README
  54                 * System.Windows.Forms/SWFTest/
  55                 * System.XML/Test/System.Xml/standalone_tests : see README
  56                 * System.XML/Test/System.Xml.Schema/standalone_tests : see README
  57                 * System.XML/System.Xml.Serialization/standalone_tests/
  58                 * System.XML/Test/System.Xml.Xsl/standalone_tests : see README
  59                 * Commons.Xml.Relaxng/Test/standalone_tests : see README
  60
  61         </ul>
  62
  63 ** Getting started
  64
  65         If you are new to writing NUnit tests, there is a template you may use
  66         to help get started. The file is:
  67
  68                 <b>mcs/class/doc/TemplateTest.cs</b>
  69
  70         Save a copy of this file in the appropriate test subdirecty
  71         (see below), and replace all the {text} markers with
  72         appropriate code. Comments in the template are there to guide
  73         you. You should also look at existing tests to see how other
  74         people have written them.
  75         mcs/class/corlib/Test/System.Collections/CollectionBaseTest.cs
  76         is a small one that might help.
  77
  78         The directory that will contain your new file depends on the
  79         assembly/namespace of the class for which you are creating the
  80         tests.  Under mcs/class there is a directory for each
  81         assembly. In each assembly there is a Test directory,
  82         e.g. mcs/class/corlib/Test. In the Test directory there are
  83         sub-directories for each namespace in the assembly,
  84         e.g. mcs/class/corlib/Test/Sytem. Put your new test file in
  85         the appropriate sub-directory under Test for the class you are
  86         testing.
  87
  88         Once all of that is done, you can do a 'make test' from the top mcs
  89         directory.  Your test class needs also to be listed in the
  90         .sources file at the top of the Test directory.
  91
  92 * Tips on writing Unit tests.
  93
  94         You should look at the <a href="http://nunit.org">NUnit documentation</a>,
  95         as it is a fantastic product, and includes fantastic documentation,
  96         but here are some tips for those of you who are already reading
  97         this web page.
  98
  99
 100 ** Provide an unique error message for Assert()
 101
 102         Include an unique message for each Assert() so that when the assert
 103         fails, it is trivial to locate it in the source. Otherwise, it may be
 104         difficult to determine which part of the test is failing. A good way
 105         to ensure unique messages is to use something like #A01, #A02 etc.
 106
 107             Ok:
 108         <pre>
 109
 110                 AssertEquals("array match", compare[0], i1[0]);
 111                 AssertEquals("array match", compare[1], i1[1]);
 112                 AssertEquals("array match", compare[2], i1[2]);
 113                 AssertEquals("array match", compare[3], i1[3]);
 114         </pre>
 115
 116             Excellent:
 117         <pre>
 118                 AssertEquals("#A01", compare[0], i1[0]);
 119                 AssertEquals("#A02", compare[1], i1[1]);
 120                 AssertEquals("#A03", compare[2], i1[2]);
 121                 AssertEquals("#A04", compare[3], i1[3]);
 122         </pre>
 123
 124         Once you used such a number in an Assert(), don't change it later on -
 125         people might use it it identify the test in bug reports or in mailing
 126         lists.
 127
 128 ** Use AssertEquals() to compare things, not Assert().
 129
 130         Do not compare two values with Assert() - if the test fails,
 131         people have no idea what went wrong while AssertEquals()
 132         reports the failed value.
 133
 134         Ok:
 135         <pre>
 136                 Assert ("A01", myTicks[0] == t1.Ticks);
 137         </pre>
 138
 139         Excellent:
 140         <pre>
 141                 AssertEquals ("A01", myTicks[0], t1.Ticks);
 142         </pre>
 143
 144 ** Test your test with the Microsoft runtime
 145
 146         If possible, try to run your testsuite with the Microsoft runtime on
 147         .NET on Windows and make sure all tests in it pass. This is especially
 148         important if you're writing a totally new testcase - without this
 149         check you can never be sure that your testcase contains no bugs ....
 150
 151         Don't worry if you're writing your test on Linux, other people can
 152         test it for you on Windows.
 153
 154         Sometimes you may discover that a test doesn't show the expected
 155         result when run with the Microsoft runtime - either because there is a
 156         bug in their runtime or something is misleading or wrong in their
 157         documentation. In this case, please put a detailed description of the
 158         problem to mcs/class/doc/API-notes and do also report it to the
 159         <a href="mailing-lists.html">mailing list</a> - we'll forward this to the
 160         Microsoft people from time to time to help them fix their documentation
 161         and runtime.
 162
 163 ** Unit tests.
 164
 165         Why do unit testing? It becomes simple to run automated tests
 166         for the whole library. Unit tests are a safety net - you can
 167         change part of the code and verify that you haven't broken
 168         anything. Ideally, tests are written before the actual library
 169         code itself. And every time a bug is discovered, a test should
 170         be written to demonstrate the bug and its fix. Then, if
 171         you ever reintroduce the bug, you will know immediately. For
 172         more info, read <a
 173         href="http://junit.sourceforge.net/doc/testinfected/testing.htm">
 174         JUnit Test Infected: Programmers Love Writing Tests</a>.
 175
 176
 177 ** Getting Started
 178
 179         We welcome all contributions to the Class Libary Test Suite.
 180
 181         There is information to help you get started in CVS at
 182         mcs/class/doc/NUnitGuidelines. Once you have written your test, please
 183         post it to <a href="mailing-lists.html">mono-list</a>.
 184
 185         Someone will make sure to add the file or apply the patch as
 186         appropriate. If you plan to be an on-going contributor and
 187         would like to get cvs account, email <a href="mailto:miguel@ximian.com">miguel</a>.
 188
 189         Normally, after you send a couple of well-written new files
 190         and/or patches to the list, you will be given cvs access.
 191
 192 <a name="compiler"></a>
 193 * Compiler tests
 194
 195         Mono ships with three compilers: C#, VB.NET and JScript.  The
 196         tests are ran by running the makefile target `make
 197         run-test-local' in the appropriate directory.
 198
 199         The C# compilation tests live in mcs/tests, and the C# error
 200         tests live in mcs/errors.
 201
 202         The VB.NET compilation tests live in mcs/btests.
 203
 204 <a name="runtime"></a>
 205 * Runtime Tests
 206
 207         These tests verify the virtual machine, to run these tests, do:
 208
 209 <pre>
 210         cd mono/mono/tests
 211         make test
 212 </pre>
 213
 214 <a name="aspnet"></a>
 215 * ASP.NET tests
 216
 217         XSP, the Mono ASP.NET server has tests for ASP.NET pages. It uses
 218         <a href="http://nunitasp.sourceforge.net">NUnitAsp</a>. Right now
 219         it only has standalone tests, ie., tests that do not need their own
 220         global.asax or web.config files.
 221
 222         If you want to run them, get the xsp CVS module and install it. Then:
 223 <pre>
 224         cd xsp/nunit-tests
 225         make
 226         cd standalone
 227         xsp
 228 </pre>
 229
 230         And from another terminal:
 231 <pre>
 232         cd xsp/nunit-tests/standalone
 233         nunit-console standalone-tests.dll
 234 </pre>
 235
 236 <a name="ws"></a>
 237 * Web Services tests
 238
 239         The Test directory for the System.Web.Services assembly contains a
 240         standalone test suite for testing web services. It tests:
 241
 242         <ul>
 243         <li>Proxy generation using the wsdl tool</li>
 244         <li>Access to web services using the generated client proxies</li>
 245         <li>Execution of web services in the server</li>
 246         </ul>
 247
 248         This suite not only tests web services running on XSP, but it can also test
 249         services running on other platforms and that are available in internet. This
 250         will help track down interoperability issues.
 251
 252         To build the test suite, just run:
 253
 254 <pre>
 255         cd mcs/class/System.Web.Services/Test/standalone
 256         xsp --root server
 257 </pre>
 258
 259         And from another terminal:
 260 <pre>
 261         cd mcs/class/System.Web.Services/Test/standalone
 262         make
 263         nunit-console testclient.dll
 264 </pre>
 265
 266         This will download the wsdl documents, generate the proxies, build a dll with
 267         the proxies, and build the nunit tests. Then you can use nunit-console or
 268         gnunit to run the tests (the nunit dll is testclient.dll).
 269
 270         Read the README file in mcs/class/System.Web.Services/Test/standalone for
 271         more info.