class/doc/NUnitGuidelines

   1 Mono NUnit Test Guidelines and Best Practices
   2
   3 Authors: Nick Drochak  <ndrochak@@gol.com>
   4          Martin Baulig  <martin@@gnome.org>
   5 Last Update: 2003-05-11
   6 Rev: 0.5
   7
   8 * Purpose
   9
  10 This document captures all the good ideas people have had about
  11 writing NUnit tests for the mono project. This document will be useful
  12 for anyone who writes or maintains unit tests.
  13
  14 * Other resources
  15         - mcs/class/README has an explanation of the build process and
  16           how it relates to the tests.
  17         - http://nunit.org is the place to find out about NUnit
  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         mcs/class/doc/TemplateTest.cs
  25
  26 Save a copy of this file in the appropriate test subdirecty (see
  27 below), and replace all the {text} markers with appropriate
  28 code. Comments in the template are there to guide you. You should also
  29 look at existing tests to see how other people have written them.
  30 mcs/class/corlib/Test/System.Collections/CollectionBaseTest.cs is a
  31 small one that might help.
  32
  33 The directory that will contain your new file depends on the
  34 assembly/namespace of the class for which you are creating the
  35 tests. Under mcs/class there is a directory for each assembly. In each
  36 assembly there is a Test directory, e.g. mcs/class/corlib/Test. In the
  37 Test directory there are sub-directories for each namespace in the
  38 assembly, e.g. mcs/class/corlib/Test/Sytem. Put your new test file in
  39 the appropriate sub-directory under Test for the class you are
  40 testing.
  41
  42 Once all of that is done, you can do a 'make test' from the top mcs
  43 directory.  Your test class will be automagically included in the
  44 build and the tests will be run along with all the others.
  45
  46 * Tips
  47
  48 -- Provide an unique error message for Assertion.Assert ()
  49
  50 Include an unique message for each Assertion.Assert () so that when the assert
  51 fails, it is trivial to locate the failing one. Otherwise, it may be
  52 difficult to determine which part of the test is failing. A good way
  53 to ensure unique messages is to use something like #A01, #A02 etc.
  54
  55     Bad:
  56
  57         Assertion.AssertEquals ("array match", compare[0], i1[0]);
  58         Assertion.AssertEquals ("array match", compare[1], i1[1]);
  59         Assertion.AssertEquals ("array match", compare[2], i1[2]);
  60         Assertion.AssertEquals ("array match", compare[3], i1[3]);
  61
  62     Good:
  63
  64         Assertion.AssertEquals ("#A01", compare[0], i1[0]);
  65         Assertion.AssertEquals ("#A02", compare[1], i1[1]);
  66         Assertion.AssertEquals ("#A03", compare[2], i1[2]);
  67         Assertion.AssertEquals ("#A04", compare[3], i1[3]);
  68
  69 Once you used such a number in an Assertion.Assert (), don't change it later on -
  70 people might use it it identify the test in bug reports or in mailing
  71 lists.
  72
  73 -- Use Assertion.AssertEquals () to compare things, not Assertion.Assert ().
  74
  75 Never compare two values with Assertion.Assert () - if the test fails, people
  76 have no idea what went wrong while Assertion.AssertEquals () reports the failed
  77 value. Also, make sure the second paramter is the expected value, and the third
  78 parameter is the actual value.
  79
  80     Bad:
  81
  82         Assertion.Assert ("A01", myTicks[0] == t1.Ticks);
  83
  84     Good:
  85
  86         Assertion.AssertEquals ("A01", myTicks[0], t1.Ticks);
  87
  88 -- Namespace
  89
  90 Please keep the namespace within each test directory consistent. Of course
  91 you can use subnamespaces as you like - especially for subdirectories of
  92 your testsuite.
  93
  94 -- Test your test with the microsoft runtime
  95
  96 If possible, try to run your testsuite with the Microsoft runtime on
  97 Windows and make sure all tests in it pass. This is especially
  98 important if you're writing a totally new testcase - without this
  99 check you can never be sure that your testcase contains no bugs ....
 100
 101 Don't worry if you're writing your test on Linux, other people can
 102 test it for you on Windows.
 103
 104 Sometimes you may discover that a test doesn't show the expected
 105 result when run with the Microsoft runtime - either because there is a
 106 bug in their runtime or something is misleading or wrong in their
 107 documentation. In this case, please put a detailed description of the
 108 problem to mcs/class/doc/API-notes and do also report it to the list -
 109 we'll forward this to the Microsoft people from time to time to help
 110 them fix their documentation and runtime.