web/testing

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