Documents how to install and use JUnit for automated unit tests.
Besides the fact that I like unit tests, my Unicode conversion work is going to have to be thorougly tested. Other small improvements to the text were made.
This commit is contained in:
dchandler
parent
9024726a9d
commit
6064903cf9
1 changed files with 156 additions and 53 deletions
|
|
@ -2,7 +2,7 @@
|
||||||
<html>
|
<html>
|
||||||
|
|
||||||
<!-- @author David Chandler -->
|
<!-- @author David Chandler -->
|
||||||
<!-- @date October 20, 2002 -->
|
<!-- @date-created October 20, 2002 -->
|
||||||
<!-- @editor Emacs, baby! -->
|
<!-- @editor Emacs, baby! -->
|
||||||
|
|
||||||
<head>
|
<head>
|
||||||
|
|
@ -24,7 +24,9 @@
|
||||||
clear, repeatable procedures that software developers go by to
|
clear, repeatable procedures that software developers go by to
|
||||||
compile, run, test, create documentation, and cut releases. Our
|
compile, run, test, create documentation, and cut releases. Our
|
||||||
build systems are fully automated, which provides a good basis for
|
build systems are fully automated, which provides a good basis for
|
||||||
collaborative development.
|
collaborative development. Even for individual development, a good
|
||||||
|
build system gives you the confidence to make big organizational
|
||||||
|
changes and saves you time in the long run.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h3>Table of Contents</h3>
|
<h3>Table of Contents</h3>
|
||||||
|
|
@ -144,61 +146,112 @@
|
||||||
classpath-related headaches disappear (after clearing initial
|
classpath-related headaches disappear (after clearing initial
|
||||||
hurdles), and you can be sure that the build will work the same on
|
hurdles), and you can be sure that the build will work the same on
|
||||||
Linux and the Mac as it does on Windows XP, because Ant itself is
|
Linux and the Mac as it does on Windows XP, because Ant itself is
|
||||||
a Java program.
|
a Java program. I compile, test, run, and build releases using
|
||||||
|
Ant, and really like it.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Although Ant is for Java programs, it has enough features to make
|
Although Ant is mainly intended for building Java programs, it has
|
||||||
it a viable choice of build system for non-Java stuff like our
|
enough features to make it a viable choice of build system for
|
||||||
Tibetan Machine Web fonts.
|
things non-Java, things like the Tibetan Machine Web font.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
|
||||||
<h3>Installing Apache Ant<a name="installant"></a></h3>
|
<h3>Installing Apache Ant<a name="installant"></a></h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
To install Apache's Jakarta Ant (or "Apache Ant" or simply "Ant"),
|
To install Apache's Jakarta Ant (or "Apache Ant" or simply "Ant"),
|
||||||
see the <a href="http://jakarta.apache.org/ant/"> Apache Ant</a>
|
you'll first need a JDK installed. I recommend getting Sun's latest
|
||||||
website. Their instructions for installation are pretty good, but
|
1.4 JDK (yes, it's available for Linux too). Next, see the <a
|
||||||
you may have trouble if you're on Windows and you don't know how to
|
href="http://jakarta.apache.org/ant/"> Apache Ant</a> website.
|
||||||
set environment variables (try Control
|
Their instructions for installation are pretty good, but you may
|
||||||
Panel->System->Advanced->Environment Variables) and the like.
|
have trouble if you're on Windows and you don't know how to set
|
||||||
|
environment variables (try Control
|
||||||
|
Panel->System->Advanced->Environment Variables) and the
|
||||||
|
like. One thing they don't tell you is that their binary
|
||||||
|
distribution ships with a ton of documentation in
|
||||||
|
<code>$ANT_HOME/docs/</code> that can all safely be deleted if you
|
||||||
|
care about disk space.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
To test your installation, use cvs to checkout the
|
I recommend installing Ant yourself, and not using a package manager
|
||||||
<code>Fonts</code> module. It has a simpler Ant build file
|
such as apt-get or rpm. This is because the ordinary installation
|
||||||
|
has a well-known <code>$ANT_HOME/lib</code> directory in which we'll
|
||||||
|
wish to place a couple of JARs (<a href="#testingjskad">
|
||||||
|
<code>junit.jar</code></a> and Vamp), as described below. I've had
|
||||||
|
personal experience with an RPM that made it impossible for me to
|
||||||
|
make Ant aware of extra JARs, so stay away from RPMs and other
|
||||||
|
packages.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
To test your installation, use cvs to checkout either the
|
||||||
|
<code>Fonts</code> module or the <code>Jskad</code> module. The
|
||||||
|
<code>Fonts</code> module has a simpler Ant build file
|
||||||
(<code>Fonts/build.xml</code>) than the <code>Jskad</code> module
|
(<code>Fonts/build.xml</code>) than the <code>Jskad</code> module
|
||||||
has, so it's better for testing. Change directory to
|
has, so perhaps it's better for testing. The <code>Jskad</code>
|
||||||
<code>Fonts</code> and run the following command:
|
module should be good to go as well, though, because we have a
|
||||||
|
multi-buildfile system that delegates less common build activities
|
||||||
|
(ones that require tweaking of your Ant installation) to supporting
|
||||||
|
buildfiles and keeps the main buildfile,
|
||||||
|
<code>Jskad/build.xml</code>, free of nonstandard constructs.
|
||||||
|
Change directory to whichever module you choose and run the
|
||||||
|
following command:
|
||||||
</p>
|
</p>
|
||||||
<blockquote>
|
<blockquote>
|
||||||
<code>ant clean dist</code>
|
<code>ant clean</code>
|
||||||
</blockquote>
|
</blockquote>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
If you have any trouble, see Ant's FAQs and then e-mail David
|
The output shouldn't alarm you, and it should conclude with "BUILD
|
||||||
Chandler.
|
SUCCESSFUL". If you have any trouble, see Ant's FAQs and then
|
||||||
|
e-mail David Chandler.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Now that you have a good installation of Ant itself, you may want
|
Now that you have a good installation of Ant itself, you probably
|
||||||
to install the <a href="http://www.vamphq.com/ant.html"> Vamp Ant
|
will want to install both JUnit and Vamp. These steps can wait
|
||||||
task</a> provided by the <a href="http://www.vamphq.com/"> Venus
|
until later if you're not sure you'll be testing our software or
|
||||||
Application Publisher</a>. You need this to cut <a
|
packaging our software for release. Here are the steps to install
|
||||||
|
them:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li>
|
||||||
|
To install JUnit, first do a cvs checkout of the
|
||||||
|
<code>Jskad</code> module (see <a href="#cvs"> below</a> for info
|
||||||
|
on how to use CVS). Now, to make Ant aware of JUnit, simply copy
|
||||||
|
<code>Jskad/extensions/to-be-installed-with-ant/junit.jar</code>
|
||||||
|
to the <code>$ANT_HOME/lib/</code> directory (and, if you're on
|
||||||
|
UNIX/Linux, make the file world-readable).
|
||||||
|
</li>
|
||||||
|
|
||||||
|
<li>
|
||||||
|
It isn't much trouble to install the <a
|
||||||
|
href="http://www.vamphq.com/ant.html"> Vamp Ant task</a> provided
|
||||||
|
by the <a href="http://www.vamphq.com/"> Venus Application
|
||||||
|
Publisher</a>. You need this to cut <a
|
||||||
href="http://java.sun.com/products/javawebstart/"> Java Web
|
href="http://java.sun.com/products/javawebstart/"> Java Web
|
||||||
Start</a> releases of Jskad, Savant, QuillDriver, and the
|
Start</a> releases of Jskad, Savant, QuillDriver, and the
|
||||||
translation tool. You <b>do not</b> need it otherwise.
|
translation tool. You <b>do not</b> need it otherwise.
|
||||||
</p>
|
|
||||||
|
<p>
|
||||||
|
Installing Vamp's Ant task is simple enough, and is in fact
|
||||||
|
simpler than Vamp's web pages of October 1, 2002 imply. That
|
||||||
|
is, if you have installed Ant 1.5.1 or later, then you can
|
||||||
|
simply drop <code>vamp.jar</code> into Ant's <code>lib</code>
|
||||||
|
directory (i.e., <code>$ANT_HOME/lib/</code>) and forget about
|
||||||
|
changing your classpath (but do be sure, Linux/UNIX users, that
|
||||||
|
the file is world-readable).
|
||||||
|
</p>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Installing Vamp's Ant task is simple enough, and is in fact simpler
|
Your build environment is good to go!
|
||||||
than Vamp's web pages of October 1, 2002 imply. That is, if you
|
|
||||||
have installed Ant 1.5.1 or later, then you can simply drop
|
|
||||||
<code>vamp.jar</code> into Ant's <code>lib</code> directory and
|
|
||||||
forget about changing your classpath.
|
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
|
||||||
<h3>Setting things up to use CVS <a
|
<h3>Setting things up to use CVS <a
|
||||||
name="cvs"></a></h3>
|
name="cvs"></a></h3>
|
||||||
|
|
||||||
|
|
@ -301,14 +354,14 @@ name="buildingfonts"></a></h3>
|
||||||
</blockquote>
|
</blockquote>
|
||||||
</li>
|
</li>
|
||||||
<li>
|
<li>
|
||||||
after being sure that your Fonts directory is a mirror of the
|
after being sure that your <code>Fonts</code> directory is a
|
||||||
one in the repository, use cvs to tag this revision that you
|
mirror of the one in the repository, use cvs to tag this
|
||||||
wish to release with a name that another developer, years down
|
revision that you wish to release with a name that another
|
||||||
the road, will recognize as referring to this release. To do
|
developer, years down the road, will recognize as referring to
|
||||||
this, you can run <code>'cvs -f rtag <i>tag-name</i>
|
this release. To do this, you can run <code>'cvs -f rtag
|
||||||
Fonts'</code> or (and this is preferred) you can run <code>'cvs
|
<i>tag-name</i> Fonts'</code> or (and this is preferred) you can
|
||||||
-f tag -c <i>tag-name</i>'</code>. Good tag names are like the
|
run <code>'cvs -f tag -c <i>tag-name</i>'</code>. Good tag
|
||||||
following:
|
names are like the following:
|
||||||
<ul>
|
<ul>
|
||||||
<li>
|
<li>
|
||||||
<code>Fonts_1_0</code> (referring to the 1.0 release of the
|
<code>Fonts_1_0</code> (referring to the 1.0 release of the
|
||||||
|
|
@ -320,7 +373,7 @@ name="buildingfonts"></a></h3>
|
||||||
</li>
|
</li>
|
||||||
</ul>
|
</ul>
|
||||||
Note that tagging for a release of just the Tibetan Machine Web
|
Note that tagging for a release of just the Tibetan Machine Web
|
||||||
fonts and not the Tibetan Machine fonts is <i>no different</i>
|
font and not the Tibetan Machine font is <i>no different</i>
|
||||||
than tagging for a simulaneous release of both.
|
than tagging for a simulaneous release of both.
|
||||||
</li>
|
</li>
|
||||||
<li>
|
<li>
|
||||||
|
|
@ -564,7 +617,7 @@ module<a name="jskadsetup"></a></h4>
|
||||||
<p>
|
<p>
|
||||||
You'll also need to checkout the <code>Fonts</code> module
|
You'll also need to checkout the <code>Fonts</code> module
|
||||||
underneath the directory where you checked out the
|
underneath the directory where you checked out the
|
||||||
<code>Jskad</code> directory. We put the TMW fonts into some JAR
|
<code>Jskad</code> directory. We put the TMW font into some JAR
|
||||||
files, so the <code>'Jskad/Fonts/TibetanMachineWeb/'</code>
|
files, so the <code>'Jskad/Fonts/TibetanMachineWeb/'</code>
|
||||||
directory must exist.
|
directory must exist.
|
||||||
</p>
|
</p>
|
||||||
|
|
@ -726,22 +779,67 @@ module<a name="daytoday"></a></h4>
|
||||||
<h5>Testing<a name="testingjskad"></a></h5>
|
<h5>Testing<a name="testingjskad"></a></h5>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
We will soon use <a href="http://junit.org/"> JUnit</a> to provide
|
Testing is an underappreciated part of software development.
|
||||||
automated unit tests. Running them will be as simple as making Ant
|
Software without a good test suite costs more money and time to
|
||||||
aware of JUnit and then running <code>'ant check'</code>. <!-- DLC
|
maintain, and it can eventually become downright demoralizing when
|
||||||
FIXME -->
|
you can't seem to make a simple change without breaking part of the
|
||||||
|
code. If you see the break immediately, it's no big deal. When you
|
||||||
|
have a solid test suite, you're much more likely to make changes
|
||||||
|
with confidence.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
To make testing easy, you should use interfaces rather than
|
But testing isn't just for us, the developers. It's mainly to give
|
||||||
|
the user confidence (though hearing from us about our extensive,
|
||||||
|
automated test suite is the direct method whereby the user gains
|
||||||
|
this confidence). For key parts of our system, parts that we hope
|
||||||
|
others will trust with their most precious data, we need excellent
|
||||||
|
testing, design, and documentation. For other parts of the system,
|
||||||
|
where failure is obvious (like GUI interfaces), testing can slide
|
||||||
|
more easily.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The core modules dealing with Tibetan text are thus going to be
|
||||||
|
heavily tested, mainly by unit tests and end-to-end regression tests
|
||||||
|
that ensure that the software still does what we verified by hand it
|
||||||
|
should do. If we don't do this, can you imagine someone entrusting
|
||||||
|
us to convert their Kangyur, in its Roman transliteration, into
|
||||||
|
Unicode? Don't imagine they will just glance at the first and last
|
||||||
|
page of the converted text and sign off on our fine tool.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
In short, the test suite determines whether our software is
|
||||||
|
well-receieved or merely well-intentioned.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
We use <a href="http://junit.org/"> JUnit</a> to provide automated
|
||||||
|
unit tests. Running them is as simple as making Ant aware of JUnit
|
||||||
|
(see below) and then running <code>'ant clean check'</code>. If
|
||||||
|
there are any failures, you should examine the files
|
||||||
|
<code>Jskad/TEST-*</code> and track them down.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
To make Ant aware of JUnit, simply copy
|
||||||
|
<code>Jskad/extensions/to-be-installed-with-ant/junit.jar</code> to
|
||||||
|
the <code>$ANT_HOME/lib/</code> directory (and, if you're on
|
||||||
|
UNIX/Linux, make the file world-readable). More details are provide
|
||||||
|
<a href="#installant"> above</a>.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
To make future testing easy, you should use interfaces rather than
|
||||||
hard-wiring in calls to classes that are difficult to instantiate.
|
hard-wiring in calls to classes that are difficult to instantiate.
|
||||||
For example, if we were to make use of a database class in our
|
For example, if we were to make use of a database class in our
|
||||||
DuffPane class, doing so directly would mean that the database
|
DuffPane class, doing so directly would mean that the database
|
||||||
software would have to be properly installed and up and running in
|
software would have to be properly installed and up and running in
|
||||||
order to test DuffPane individually. If you create an interface and
|
order to test DuffPane individually. If you create an interface and
|
||||||
use the database only through that interface, then creating a <a
|
use the database only through that interface, then creating a <a
|
||||||
href="http://mockobjects.com"> mock object</a> that pretends to
|
href="http://mockobjects.com/"> mock object</a> that pretends to be
|
||||||
be that database but returns canned answers is a simple matter.
|
that database but returns canned answers is a simple matter.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -821,7 +919,9 @@ module<a name="daytoday"></a></h4>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
First, be sure you've installed Vamp's Ant task as described <a
|
First, be sure you've installed Vamp's Ant task as described <a
|
||||||
href="#installant"> above</a>.
|
href="#installant"> above</a>. You can do many day-to-day
|
||||||
|
development activities without performing this step, so don't assume
|
||||||
|
that you must have already done it.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
|
|
@ -850,8 +950,9 @@ module<a name="daytoday"></a></h4>
|
||||||
Jskad module)
|
Jskad module)
|
||||||
</li>
|
</li>
|
||||||
<li>
|
<li>
|
||||||
<code>September_23_2002_release</code> (referring to the
|
<code>September_23_2002_release</code> (referring to the release
|
||||||
release of all programs in Fonts module made on September 23, 2002
|
of all programs in <code>Fonts</code> module made on September 23,
|
||||||
|
2002
|
||||||
</li>
|
</li>
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
|
|
@ -940,8 +1041,10 @@ module<a name="daytoday"></a></h4>
|
||||||
QuillDriver, like Jskad, requires all-permissions security. That
|
QuillDriver, like Jskad, requires all-permissions security. That
|
||||||
means that <code>xalan.jar</code>, <code>xercesImpl.jar</code>, and
|
means that <code>xalan.jar</code>, <code>xercesImpl.jar</code>, and
|
||||||
<code>xml-apis.jar</code> need to be jar-signed by the same
|
<code>xml-apis.jar</code> need to be jar-signed by the same
|
||||||
certificate as Savant. We don't yet do this automatically <!-- DLC
|
certificate as QuillDriver. We do this automatically via <code>'ant
|
||||||
FIXME -->, but here's how to do this manually:
|
self-contained-dist'</code> or <code>'ant
|
||||||
|
web-start-releases'</code>, but here's how to do this manually:<!--
|
||||||
|
DLC FIXME: automate this further. -->
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<ol>
|
<ol>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue