######################################################################
#                                                                    #
#   This file is part of  JUnitDoclet, a project to generate basic   #
#   test cases  from source code and  helping to keep them in sync   #
#   during refactoring.                                              #
#                                                                    #
#   Copyright (C) 2002  ObjectFab GmbH  (http://www.objectfab.de/)   #
#                                                                    #
#   This library is  free software; you can redistribute it and/or   #
#   modify  it under the  terms of  the  GNU Lesser General Public   #
#   License as published  by the  Free Software Foundation; either   #
#   version 2.1  of the  License, or  (at your option)  any  later   #
#   version.                                                         #
#                                                                    #
#   This library is distributed in the hope that it will be useful,  #
#   but WITHOUT ANY WARRANTY; without even the implied warranty of   #
#   MERCHANTABILITY or  FITNESS FOR A PARTICULAR PURPOSE.  See the   #
#   GNU Lesser General Public License for more details.              #
#                                                                    #
#   You  should  have  received a  copy of the  GNU Lesser General   #
#   Public License along with this  library; if not, write  to the   #
#   Free  Software  Foundation, Inc.,  59 Temple Place,  Suite 330,  #
#   Boston, MA  02111-1307  USA                                      #
#                                                                    #
######################################################################



JUnitDoclet
===========

Test driven develpment is a hot topic. JUnit is a hot topic.

Testing seems to be a hot topic in general.

Is everyone writing enough tests? Why not? This should be a hot topic
as well. JUnitDoclet will help you to do write more tests.

This tool frees you from most of the routine work by generating
skeletons of TestCases and TestSuites. And when your application
changes during refactoring, JUnitDoclet supports you to keep the 
tests in sync. No test get's dropped by accident, no TestCase is 
forgotten to be included in a TestSuite.

Still interested? So before you expect to much, let's see what
JUnitDoclet is not. This tool does not take the fun of writing tests
from you. If you use it without implementing some of the test methods
generated, you've missed the idea behind JUnit and JUnitDoclet.

JUnitDoclet is not always generating compilable code. It may generate
code to instantiate an interface or an abstract class. But your
compiler will find you that few occations. You will easy understand
why there is no wizard to solve that. You are the better wizard, so
you do it. And once it's solved, JUnitDoclet keeps the solution.



How to install?
---------------

First download the zip file according to your Environment (JDK 1.3 or
JDK 1.4). Since you read this, you mastered this step already.

Extract the archive.

There is more than one option to install JUnitDoclet. You can install
it as a ANT target in your build.xml (the ANT script) or as external 
tool for your IDE / Editor or all of it.

To install JUnitDoclet as external tool for your IDE, please read
doc/ide/readme.txt. This file will refer to installation specifics
for IntelliJ IDEA (2.6 and 3.0) and for Eclipse.

The installation of  JUnitDoclet as ANT target is described in 
doc/ant_target/readme.txt .


How to execute?
---------------

To generate JUnitTests has to be easy. That's the whole point with 
JUnitDoclet. ;-) 

In IntelliJ IDEA click right, select "JUnitDoclet->Generate TestCase" 
from the context menu and enjoy.

In Eclipse select "Run->External Tools->JUnitDoclet: Generate TestCase"
and watch the magic happen.

If you installed it as ANT target change to the project home and call
> ant junitdoclet
where junitdoclet is the name of the target you defined.

If you need to call JUnitDoclet directly, make sure junitdoclet.jar
is in your classpath. Then pass the main class as doclet parameter to
javadoc. Define the output directory for JUnitDoclet (-d <dir>) and
the packages.

> javadoc -doclet com.objectfab.tools.junitdoclet.JUnitDoclet \
          -d ./junit <packages>

If you want to see all the parameter options of JUnitDoclet (usefull
for both ANT and command line) just type

> javadoc -doclet com.objectfab.tools.junitdoclet.JUnitDoclet -help


Can I use my own templates?
---------------------------

Yes. Make a copy of junitdoclet.properties and modify the templates
there to whatever you want them to look like. Then pass them to
JUnitDoclet by the -properties parameter.

> javadoc -doclet com.objectfab.tools.junitdoclet.JUnitDoclet \
          -properties my_junitdoclet.properties \
          -d ./junit <packages>

If you just want to generate and preserve javadoc comments even in
TestCases you can use junitdoclet_w_doc.properties that come with
JUnitDoclet.

In your templates you have access to all system properties as well
(like user.name, user.home, java.specification.version, ...). Use them
in the same manner as the properties provided by JUnitDoclet.

If your templates do recusion, JUnitDoclet will stop at an stack level
of 10. If you need more, please let us know.


Where do I get help?
--------------------

Just browse the FAQ at www.junitdoclet.org and if you don't find an
answer there, send an email to junitdoclet@objectfab.de .


What's next?
------------

Stop reading readme files and start to have fun with JUnitDoclet. ;-)


Regards,

Steffen Gemkow