XTest Supplied Plugins
Version: 1.0
Author: Martin
Brehovsky
Abstract: This document describes plugins supplied with
standard XTest distribution
- Document History:
- 12 Feb. 2004 : version 1, created
- 28 Jan. 2005 : updated
- 3 Mar. 2005 : updated
- Contents:
- Introduction
- Plugins
- Base Plugin
JVM Plugin
IDE Plugin
Deprecated Plugin
As written in the
plugin description
document, standard distriution of XTest contains several plugins,
which are used to compile,package,execute tests and provides processing
of generated results. In this document are these plugins described, so
you can use their functionality.
Plugins available in standard XTest distribution are:
- base - abstract plugin
used as a base plugin for all other plugins (except deprecated). It
implements basic actions of compilation, packaging and result
processing. The more detailed description of this plugin is here.
- jvm - plugin for running
tests in plain JVM. It implements execution action for running tests in
plain JVM. The user's description of this plugin is here.
- ide - plugin for running
tests in NetBeans IDE (including platform). It implements execution
action for running tests in NetBeans IDE. The mode detailed description
is available here.
- deprecated - plugin used
to run tests created to be run with the old 'monolithic' version of the
XTest. Basically it behaves in such a way, that the tests should not
notice any difference when running with plugin-enabled XTest and
monolithic XTest.
This plugin serves as a base for all other plugins. You should never
use this plugin explicitly, but use ts functionality plugins which
extends this base plugin. Currently 'base' plugin provides the
following actions:
- default compiler for tests with id 'compiler' - this compiler
basically performs compilation of test sources in a specified
directory. You can supply your own classpath (to which is always added
JUnit and NbJUnit classes), as well as whether classes should be
compiler with debug option and/or messages for usage of deprecated
classes/methods. This compiler does not use any extra property, just
the ones which can be specified directly in the compileTests
(buildTests) tasks provided by XTest. Please see tasks documentation
to get mode details.
- default packager for tests with id 'packager' - similarly as with
compiler, this action performs packaging of compiled test classes to an
archive, which is then used when tests are running. All the
specificable properties can be set directly in packageTests
(buildTests) tasks provided by XTest. Please see tasks documentation to get
mode details.
- default result processor for processing test results with id
'result_processor' - this action is not supposed to be used by users,
it is used by XTest automatically after test execution.
This plugin provides an executor which runs tests in plain Java Virtual
Machine. The plugin extends the 'base' plugin, so it inherits
all compilers/packagers/result_processors from it. The supplied
executor is called 'jvm_execution' and is set as default when using JVM
plugin (for details see executeTests task in this
documentation).
Besides the basic properties supplied directly by executeTests task,
you can use the following advanced properties to influence the test
execution (ideally you would like to use the embedded 'property'
element in the executeTests task):
Property Name
|
Description
|
coverage.lib.path
|
used by tests when running with coverage
tool to pass required libraries path
|
junit.properties.file
|
Can specify alternate
junit.properties file for test execution (for details see this document). If not
set, then junit.properties file is searched as junit.properties file in
user's home dir
|
xtest.timeout
|
timeout for virtual machine when
running tests (please note the timeout is applied to each testbag)
|
jdkhome
|
Path to JDK(JRE) which should be
for tests execution
|
xtest.jvm.args
|
Additional arguments for JVM
|
xtest.enable.assertions
|
whether JVM should be started
with enabled assertions (-ea) switch. Default value is true.
|
xtest.debug.port
|
debug port to be used when
running tests in debugger mode. By default not set, therefore tests are
not running in debugger
|
xtest.debug.suspend
|
when running in debugger and set
to true (default), the debugging is susppended until user orders
otherwise
|
xtest.testrunner.mode
|
which mode should be used to run
the tests. Available modes are 'testsuite' (default) - each testsuite
runs in its own JVM and 'testbag' - the whole testbag runs in the
single JVM.
|
xtest.jvm.coverage.args
|
additional arguments required by coverage framework
|
This plugin provides and executor, which is able to run tests in
NetBeans IDE (including NetBeans Platform and other derived products).
Similarly as with JVM plugin, the IDE plugin extends 'base' plugin, so
copmilers/packagers/result_processors are inherited from it.
IDE plugin executes tests in the follwing way: the IDE is started and
the tests and the supplied libraries are loaded by IDE's system
classloader (user might specify other classloader by setting an
appropriate property). The tests are then run in a separate thread in
the IDE. When finished, the XTest quits the IDE.
The following properties can be supplied to the the IDE plugin
executor, so you can influence the test execution in IDE specific way:
Property Name
|
Description
|
coverage.lib.path
|
used by tests when running with coverage
tool to pass required libraries path
|
junit.properties.file
|
Can specify alternate
junit.properties file for test execution (for details see this document).
If not
set, then junit.properties file is searched as junit.properties file in
user's home dir
|
xtest.timeout
|
timeout for IDE when
running tests (please note the timeout is applied to each testbag)
|
jdkhome
|
Path to JDK(JRE) which should be
for tests execution |
xtest.enable.assertions
|
whether JVM should be started
with enabled assertions (-ea) switch. Default value is true.
|
xtest.debug.port
|
debug port to be used when
running tests in debugger mode. By default not set, therefore tests are
not running in debugger
|
xtest.debug.suspend
|
when running in debugger and set
to true (default), the debugging is susppended until user orders
otherwise
|
xtest.testrunner.mode
|
which mode should be used to run
the tests. Available modes are 'testbag' (default) - the whole testbag
runs in in single IDE session (each testbag has its own userdir),
and 'testsuite' - each testsuite is started in its own IDE
session (userdir is reused for the whole testbag)
|
xtest.ide.commandline.suffix
|
suffix to IDE command line
|
xtest.ide.jvmargs
|
Additional arguments for JVM
running IDE
|
xtest.ide.reuse.userdir
|
If the IDE should rather reuse
than create a new userdir for each testbag, this property is usuallt
used with testbag
priority |
xtest.ide.exit
|
If set to true (default), XTest
quits IDE when tests are finished. If set to false, the IDE remains
running until the user manually exits
|
xtest.ide.use.classloader
|
If set to a name of a module,
tests will be loaded by the classloader of the given module (e.g.
'org.netbeans.modules.java'). This is
needed when testing package private methods for the given module. If
you need to use openide/core classloader, specify 'openide' value.
|
xtest.ide.error.manager
|
XTest error manager is installed to IDE and when an exception or
error is thrown, then the test is marked as error and exception
stack trace appears in results. Default value is true.
|
xtest.ide.handler
|
XTestIDEHandler is added to IDE and when an exception is thrown,
then the test is marked as error and exception
stack trace appears in results. Default value is true.
|
xtest.ide.mdrstorage
|
Use prebuilt JDK mdr storage at specified location. By default it tries
to use storage in directory ${jdkhome}/mdrstorage. You can set your
own directory or disable using prebuilt mdr storage by setting this
property to false/no. In fact it sets -J-Dprebuilt.storage.dir IDE option.
|
xtest.ide.launcher
|
Use given launcher to run IDE for testing. Default value for Windows
is 'nb.exe' (or 'netbeans.exe' if 'nb.exe'
is not available), for other operating systems 'netbeans'.
If none of above is found, it tries to find other suitable launcher in bin
directory.
Command for running IDE is then put together as follows:
'${netbeans.dest.dir}/bin/${xtest.ide.launcher}'.
|
xtest.ide.branding
|
This property is automatically defined when we run tests against
branded application. Value is then
--branding ${branding.token} --clusters ${run.platform.clusters}.
These parameters are added to command-line.
|
xtest.ide.coverage.args
|
additional arguments required by coverage framework
|
This plugins provides backward compatibility to tests written for XTest
versions older than 1.5. Basically its purpose is to provide such an
environment, that the tests does not notice any difference that they
are run in a completely different environment than they were written
for.
Please note, since IDE is evolving quite rapidly these days, it will
not contain several features used by this plugin to run the tests (e.g.
ExecutionEngine). It is highly recommened that you migrate to either
JVM plugin (if you used 'code' executor) or IDE plugin (if you used
'ide' executor) soon, otherwise your tests might stop working one day.
You can look at the migration guide to get more help on this topic.
The following properties are used by deprecated plugin to compile/run
the tests:
Properties used either for executor and compiler
- xtest.extra.jars - jars or zips (and directories too)
which will be added to classpath for compilation and execution (both
code and ide execution). These jars or zips will be mounted in ide
execution. You can write absolute (never recommended) or relative (also
not recommended) path, but the best solution is just write name (e.g.
jemmy.jar) and this jar will be searched in directories from property xtest.extra.jars.path.
- xtest.extra.jars.ide - these jars will be copied into
${netbeans.home}/lib/ext in ide execution. You can again write absolute
(never recommended) or relative (also not recommended) path, but the
best solution is just write name (e.g. jdbcdriver.jar) and this jar
will be searched in
directories from property xtest.extra.jars.path.
- xtest.extra.jars.path - this property is used when
properties xtest.extra.jars or xtest.extra.jars.ide
are defined. It contains list of directories which will be searched for
jars given in above property. This property should not be defined here,
but e.g. in driver or passed as parameter in commandline (ant
-Dxtest.extra.jars.path=c:\jdbcdrivers;c:\jemmy )
Properties used only for executor
- codetest.classpath - additional classpath used for
execution code tests. In advanced template it's created in target
prepare-codetest-classpath and depends on property
xtest.source.location which classpath will be used.
xtest.extra.ide.mounts - additional directories to
be mounted in repository. They are just mounted, not used in a
classpath
when compiling tests.
- xtest.jvmargs - argumets for java virtual machine. Added
to java command line for code tests or to IDE command line with
-J prefix for ide tests.
- xtest.ide.commandline.suffix - can contain other
parameters which will be added to IDE command line.
xtest.ide.reuse.userdir - If you set this property to true,
IDE userdir from previous run will be used. Useful with combination
with testbag
priority.
Properties used only for compiler
- compile.srcdir - directories which should be compiled.
Can contain more directories. They will be compiled separately.
- compile.excludes - files which should be excluded for
compilation
- compiletest.classpath - additional classpath used for
compilation. In advanced template it's created in target
prepare-compile-classpath and depends on property xtest.source.location
which classpath will be used.
- jartests.includes - specifies additional includes
(besides
${xtest.home}/standard-test-includes.txt) when making jar with tests
- jartests.excludes - specifies additional excludes
(besides
${xtest.home}/standard-test-excludes.txt) when making jar with tests
Advanced properties
This property is set earlier in xtest instance or driver and affect
behavior of module's build.xml
- xtest.source.location - Used only in advanced template.
Allowed values: "src", "jar" or "ide". This property
says which resource should be used during compilation and execution.
Possible values are "src", "jar" or "ide".
