[Mono-list] Initial draft of document for beginning testers..

RG rgoodwin@nucentrix.net
Wed, 17 Oct 2001 13:51:54 -0500

This is a multi-part message in MIME format.

Content-Type: multipart/alternative;

Content-Type: text/plain;
Content-Transfer-Encoding: quoted-printable

Here's something I whipped up guys.. Comments welcome!

Content-Type: text/html;
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<META http-equiv=3DContent-Type content=3D"text/html; =
<META content=3D"MSHTML 6.00.2600.0" name=3DGENERATOR>
<BODY bgColor=3D#ffffff>
<DIV><FONT face=3DArial size=3D2>Here's something I whipped up guys.. =


Content-Type: application/octet-stream;
Content-Transfer-Encoding: quoted-printable
Content-Disposition: attachment;

set0 Times New Roman;}{\f1\fnil\fprq2\fcharset2 =
Wingdings;}{\f2\fswiss\fcharset0 Arial;}}
{\colortbl ;\red0\green0\blue255;}
{\stylesheet{ Normal;}{\s1 heading 1;}}
\viewkind4\uc1\pard\keepn\s1\b\f0\fs28 So you want to be a Mono =
Perhaps one of the most important pieces that will help the Mono =
movement is the authoring of test cases. When there is a successful test =
suite in place (a suite being a group of tests), the developers have the =
freedom to make changes and implement new code at a more rapid pace. =
They are able to do this because they can find out quickly if they have =
broken previous code by simply running the test suite.\par
You don\rquote t need to be an ace programmer to write test cases. Most =
of you should be able to go out and read some C# tutorials on the web =
and get started shortly thereafter. Once you pick a class to write cases =
against, you can then refine your knowledge of that class specifically =
and code tests that will be helpful and, usually, quite simple.\par
\pard\keepn\s1\b\fs28 Getting Started\par
First things first, you need to get some basic items installed. All of =
this work must currently be done in Windows.\par
\pard\fi-360\li720\tx720 1)\tab The Microsoft \'99  .NET Framework SDK: =
(\cf1\ul =
rl=3D/msdn-files/027/000/976/msdncompositedoc.xml>\cf0\ulnone )\par
\pard\li720 You need this installed for a couple of reasons. First it =
has the MSDN documentation including a C# reference and tutorial section =
which is invaluable. Second, the compiler for Mono isn\rquote t ready =
yet, so in order to compile the Mono class libraries and test cases you =
currently need the .NET SDK (more on this later)\par
\pard\fi-360\li720\tx720 2)\tab Cygwin: (\cf1\ul =
<http://www.cygwin.com/setup.exe>\cf0\ulnone )\par
\pard\li720 This is going to give you the tools you need to use the =
\ldblquote make files\rdblquote  and other shell utilities that assist =
in compiling Mono\par
\pard\fi-360\li720\tx720 3)\tab The latest Mono snapshot: (\cf1\ul =
<http://www.go-mono.com/download.html>\cf0\ulnone )\par
\pard\li720 Thanks to diligent work by the developers (and test case =
authors \f1 J\f0  ) the snapshots are usually very stable and =
Follow the instructions on that page under the heading \ldblquote To =
install and work on the compiler and class libraries\rdblquote . This =
will build mcs and the class libraries (more on these later). \par
\pard\fi-360\li720\tx720 4)\tab Nunit: =
\pard\li360 This is the software you use to execute test cases. It is =
also included in the Mono distribution but it is useful to install it =
separately so that you get the excellent NUnit documentation. There is =
research under way to determine what it would take to get the console =
version of NUnit running under Linux, but for now it\rquote s only going =
to run on Windows.\par
\pard\keepn\s1\b\fs28 The components of Mono\par
This is where some people get lost, trying to figure out what\rquote s =
what and how the directory structure works. Some basics:\par
\b\ldblquote Mono\rdblquote\b0  refers to the entire project including =
the compiler, runtime, and class libraries. However, currently the =
compiler, \ldblquote\b mcs\rdblquote ,\b0  is located in a separate =
directory structure. This will change at some point in the future, so =
keep an eye out.\par
So after a default compile, you will have the following: \par
\b /gtk-sharp\par
\pard\fi-360\li720\tx720\b0 -\tab This contains the bindings for C# to =
the GTK libraries. I won\rquote t go into it because I haven\rquote t =
done anything with it myself\par
\pard\b /mono\par
\pard\fi-360\li720\tx720\b0 -\tab This contains the files for building =
the runtime. You don\rquote t know what the runtime is? Go read some =
more about C# \f1 J\f0\par
\pard\b /mcs\par
\pard\fi-360\li720\tx720\b0 -\tab This is where the compiler and class =
libraries reside. \par
\b /mcs/nunit \par
\pard\fi-360\li720\tx720\b0 -\tab Contains the NUnit program, which =
you\rquote ll use to execute test cases.\par
\b /mcs/class/corlib\par
\pard\fi-360\li720\tx720\b0 -\tab - This holds the source and tests for =
the core class libraries needed for C# compilation. Most of your work =
will be done in here.\par
Under the \b /mcs/class/corlib\b0  directory you will find the source =
code for all of the class libraries that have been--at least =
partially-implemented. You will also find a directory called Test which =
should contain-eventually-a corresponding directory for each class =
contained in the corlib directory. For example:\par
\b corlib/System.Collections\b0    -  will contain the actual source =
code for the System.Collections class library\par
\b corlib/Test/System.Collections\b0    -  will contain tests written =
for System.Collections\par
\b corlib/lib\b0   -   contains the actual compiled .dll\rquote s that =
tests will be run against\par
Tests that you create will reside in the appropriate directory under \b =
corlib/Test\b0 /. So if you were creating a test against =
System.Collections, you\rquote d put the test in \b =
corlib/Test/System.Collections\b0 . This keeps everything neat and =
ensures the tests you write get built properly. \par
\pard\keepn\s1\b\fs28 What am I actually testing?\par
You will be writing tests against the Mono versions of the C# class =
libraries. Don\rquote t know what class libraries are? Go read a quick =
tutorial on OOP \f1 J\f0\par
What libraries should I write tests for?\par
\b0\fs24 Many factors come into play here including experience, desire, =
need. \par
Experience - Are you particularly adept with a certain class or =
mechanism of C#, for example Collections or Diagnostics? \par
Desire - Do you have an interest in a certain area of the language?\par
Need - Are there holes in the test suite so far? (empty or non-existent =
directories in the CVS indicate that test have not likely been written =
yet). This is true of almost all the classes, and will continue to be =
for the near future.\par
In all cases, look up the maintainer of the class library (\cf1\ul =
<http://www.go-mono.com/class-status/index.html>\cf0\ulnone ) and drop =
them an email to make sure you\rquote re not duplicating something =
they\rquote ve implemented but maybe haven\rquote t checked into CVS =
yet. In addition they may have specific tests they\rquote d like to see, =
or hints on where you might be able to find holes in the code.\par
\pard\keepn\s1\b\fs28 How do I write and execute a test?\par
\b0\fs24 Rather than repeat something that\rquote s already been =
described wonderfully, I\rquote ll ask you to reference the \ldblquote =
Test Infected\rdblquote  document included with the NUnit distribution, =
and also available at nunit.sourceforge.net. Then, when it is time to =
write the case, include the class library you are going to test by =
utilizing the \ldblquote\b using\rdblquote\b0  statement as describe in =
the C# documentation.  For example:\par
using System;\par
using NUnit.Framework;\par
\{\'85..test code here as described in the NUnit docs\'85.\}\par
\b0 Save the test as a .cs file in the proper subfolder under test. =
Then, make sure that you have nant in your PATH environment variable. =
Nant is located in \b <where you built mono>/mcs/nant . \b0 Switch to =
the \b corlib/Test \b0 directory and run: \b nant build\b0 . This will =
compile all the test cases (including yours) into the \b =
corlib_test.dll\b0  in the \b corlib/Test \b0 directory. Open NUnit and =
browse to the \b corlib_test.dll\b0 . Choose your test from the Type =
Name dropdown box. \par
Then go run the test and note your output.\par
\fs28 I\rquote ve written a test and it seems to: work great/break =
something/reinvent the wheel/turn water to wine\'85\par
\b0\fs24 Great! You\rquote ve just made a much appreciated contribution =
to the Mono project. If you think you\rquote ve exposed an error, double =
check your work to make sure that you don\rquote t have bugs of your =
own. Check the MSDN documentation to verify you are trying to do =
something that is legal in the language. Once you\rquote re certain your =
test case is valid, it\rquote s time to send it off to the class =
maintainer. Clean up the code spacing and be sure to comment if you =
think it might not be clear what you are testing. Use an informative =
filename as well, not something like \ldblquote test.cs\rdblquote .\par