XTest Installation Guide
Last update: June 7, 2006
Abstract: This document describes all steps necessary to
install XTest framework.
- Contents:
- 1. Installation
- 1.1 Install binary version
- 1.2 Build your own version
- 2. Configuration
- 3. Dependencies
- 4. Installation verification
- 5. Trouble shooting
The XTest framework is built on the top of several tools like
Ant, JUnit, Xalan. It is comprised from extensions of those tools
and scripts making everything work together. All external tools except
Ant are bundled with XTest and thus it is not necessary to download and
install them individually. Ant isn't bundled with XTest, because the
necessity of its installation depends on the way you will launch your
XTest's tests. For the list of bundled tools see Dependencies section below.
Generally, two ways of XTest installation are possible -
installation
from binaries or building your own version from sources.
If you are not familiar with building NetBeans or you don't want to use
the latest functionality available in CVS, you just need to download
binary version of XTest and unpack it to the right place.
Installation to the common directory structure:
- Be sure you have directory structure as described in Quick Start
with Ant
- In repository nb_all create directory xtest
- Download XTest binary direrctly from download
page.
- Unpack xtest-distribution.zip to nb_all/xtest
directory
Installation to non standard directory structure:
If you don't use NetBeans directory structure you can only
download
xtest distribution from
download page
and unpack it to any directory you want. In this case the chosen
directory is your XTest home and you need to run your tests with set
xtest.home property from command line. For example: XTest is unpacked
to directory
/space/xtest
and you need run tests from
/space/mywork/mytests. In
this case go to
/space/mywork/mytests and type '
ant
-Dxtest.home=/space/xtest' to run
your tests.
Installation as IDE module:
You can also install XTest module into your NetBeans IDE from Update
Center. It installs XTest testing library to <your_userdir>/xtest-distribution,
adds template to create tests infrastructure and adds XTest actions to
project root node. For more details see this document.
This way of installation is convenient for Netbeans developers
or anybody else who works directly with the Netbeans source code
repository, it uses XTest checked out directly from Netbeans CVS. Test
applications together with tested code are expected to be checked out
from CVS and built by their build scripts, this installation relies on
the NetBeans' specific CVS structure and it is supposed to be
used by developers to run validity checks before they commit changes
into CVS repository or by automated tests managed by QE & RE
people. To build XTest just type 'ant'
in xtest directory. If
you want to created zipped distribution, use target makedist.
Build XTest against NetBeans IDE sources:
- Checkout NetBeans
IDE modules
from CVS repository (cvs co
standard_nowww)
- build XTest distribution by typing 'ant
makedist' in nb_all/xtest/ directory.
Build XTest against NetBeans Platform
sources:
- Checkout NetBeans Platform sources: apisupport, autoupdate,
core, libs, nbbuild, openide,
projects and xtest
- Checkout junit/external
- Build platform using 'ant build-platform' in nbbuild directory
- Build XTest distribution using 'ant makedist'
in xtest directory
Build XTest against binary
distribution of NetBeans IDE:
- Checkout core/external, nbbuild, junit/external, xtest from CVS
- build XTest distribution by typing 'ant makedist-simple
-Dnetbeans.dest.dir=<NetBeans_installation>' in nb_all/xtest
directory
Additionally, you may want to configure the file-diff extension
of JUnit framework. The file-diff extension allows you to use
assertFile
functions in your tests to compare test-produced file with the golden
file, the assertFile function fails in case these files differ. The
XTest includes this extension thus you can use it easily, but it reads
some configuration parameters from the junit.properties file, which
must
be placed in users home directory (this is the directory known in JVM
as 'users.home' system property). In junit.properties file you
should
specify the diff-like facility implementation and its properties. See
this document
for detailed description.
The XTest framework depends on several tools, besides Java all of
them are open source products. Their versions used in XTest are listed
in table below.
Please
follow links for product specific information.
XTest installation can be verified by following steps:
- Switch to 'example/MyModule'
sub-directory of XTest's home
directory.
- Type 'ant' to
compile MyModule sources.
- Switch to 'test'
sub-directory
- Type 'ant' to
compile and run tests or 'ant
-Dnetbeans.dest.dir=<NetBeans_installation>'.
- You should see test results in 'results' sub-directory of
MyModule/test directory. There should be summary report
in XML, HTML.
- You can also experiment with different test
bags of test to be run. Try to run 'ant -Dxtest.attributes=stable'
or
'ant -Dxtestr.attributes=failing'.
This section contains list of obvious problems one can be facing
with when installing XTest. If you have a trouble, which is not listed
here, please ask on users@xtest.netbeans.org
mailing list, you might
find bug or you have done something wrong. In both cases we can help
you!
CVS Access problems
In case you have a troubles with either getting the source codes
from the Netbeans CVS repository or building, please take a minute
to see following pages:
I don't know how to run Netbeans tests
First, you should use Developers Installation of XTest and be
sure that your XTest installation works. Usually, the testing consists
from following steps:
- Update module you want to test and its tests you want to run.
- Build tested module (compile its sources), do it by typing 'ant'
in module's directory.
- Build and run tests by typing 'ant' in
their directory.
- View test results in 'results' sub-directory of test's directory.
Generally, each test script should provide three main targets
you can run, they are:
- buildtests - build tests
- runtest - execute tests
- cleantests - clean tests
- cleanresults - clean results
- realclean - clean up test results and built files (.class
files and jars for instance)
Default target of test script starts both 'buildtests' and
'runtests' targets.
