XTest Plugins Description

Version: 1.0
Author: Martin Brehovsky

Abstract: This document describes the design and functionality of XTest plugins.

Document History:

12 Feb. 2004 : version 1, created

 Contents:

Introduction

Design

Included Plugins

How to write a plugin
Plugin Properties
Properties Required to be Understood
Future Tasks

---

Introduction

This document describes design and usage (from XTest developer point of view) of XTest plugins. XTest introduced plugins with version 1.5.0 to decouple the harness part and product specific parts. This change was required by XTest users who desired to use XTest as a harness for other products than NetBeans IDE.

Design

General Concept

Plugins in XTest are simple modules (modulelets :-)), which provide actions for compiling, packaging, executing and for result processing. These actions are called when tests needs to be compiled, packaged, run and their results processed. All the actions are described by plugin descriptor (more about this is available below) and plugin provides the particular implementations. Currently, the actions must be implemented as targets in ant scripts, but there is no reason to enhance it to other options.

Plugins utilize simple inheritance concept known from object oriented programming. Each plugin can extend another one, so it can provide another implementations of already defined actions. This feature is quite useful when tests for one product (e.g. NetBeans IDE) needs to be run on NetBeans ide itself (XTest provides plugin 'ide') and later they need to be run on some product, which uses NetBeans IDE as a platform (e.g. product named XIDE). Obviously, the test developer cannot know anything of such a product, so his tests are happily running on NetBeans IDE (using the ide plugin). Nevertheless, the developers would like to run the tests also on their XIDE product, because they use the same platform as the NetBeans IDE, but unfortunately their product is launched in a completely different way than NetBeans. All they need to do is to write a plugin (e.g. xide plugin), which extends the 'ide' plugin used by the tests. This plugin needs to reimplement the executor used by the tests, so it is able to launch their product instead of NetBeans IDE. When later running the tests, they need to install the 'xide' plugin to the plugins installation directory (more details is available below) and run XTest with property xtest.preferred.plugins=xide. XTest then uses 'xide' plugin to execute the tests instead the 'ide' plugin, so all tests can happily run without any change.

Plugin Descriptor

The plugin descriptor is the most important file of the plugin. It describes all actions provided by plugin as well as its dependency on other plugins. The well commented DTD for plugin descriptor is available here. The following sections shows an hypthetical example of the plugin descriptor for the 'xide' module.

<?xml version="1.0" encoding="UTF-8"?>

<!-- this introduces plugin with name 'xide', version '1.0', which extends 'ide' plugin-->
<XTestPlugin name="xide" version="1.0" extends="ide">

    
    <!-- dependecies section - plugin requires XTest at least version 1.5 -->
    <Dependencies requiredXTestVersion="1.5">	
	<!-- since 'xide' extends 'ide' plugin, it needs to depend on it -->
        <UsePlugin name="ide" version="1.0"/>  
    </Dependencies>

    <!-- compilers supplied by this plugin -->
    <AvailableCompilers>
	<!-- xide_compilation for xide speicific tests, 
             please note since this plugin extends 'ide' plugin, all compilers from 'ide' plugin are also available 
	     - id is the ide of the action
             - antfile is the relative path to script, where the action is available
             - target is the target of the ant script with this action
             - default is the true/false property whether this action should be used as a default action
                        when compiling tests. For compilation, the 'ide' plugin provides the default action
	-->
        <Compiler id="xide_compilation" antfile="lib/compilation_targets.xml" target="compile" default="false"/>
    </AvailableCompilers>

    <!-- packagers supplied by this plugin -->
    <AvailablePackagers>
	<!-- xide packager for xides specific tests. Attributes are the same as with compilers -->
        <Packager id="xide_enhanced_packaging" antfile="lib/packaging_targets.xml" target="package" default="false"/>
    </AvailablePackagers>    

    <!-- executors supplied by this plugins -->
    <AvailableExecutors>
        <!-- overriden ide_exection from ide plugin. When tests supposed to use 'ide' executor are run with 
             'xtest.preferred.plugins="xide"', this executor is used instead of the one supplied by 'ide' plugin 
        -->
        <Executor id="ide_execution" antfile="lib/xide_execution_targets.xml" target="original_ide_execution" default="true"/>        
        <!-- xide executor for special xide tests (different from overriden ide executor) -->
        <Executor id="xide_execution" antfile="lib/xide_execution_targets.xml" target="xide_execution"/>        
    </AvailableExecutors>

    <!-- result processors supplied by this plugin -->
    <AvailableResultProcessors>
        <!-- special result processor for tests run with 'xide_execution' executor. All attributes are the same as with compiler,
             only the 'executorID' identifies the executor after which this result processor is run (all othe tests use the default
             result processor from 'ide' plugin
         -->
        <ResultProcessor id="xide_processor" executorID="xide_execution" antfile="lib/result_processor_targets.xml" target="report" default="false"/>
    </AvailableResultProcessors>

</XTestPlugin>

Directory Layout

Plugins are expected to be installed in 'plugins' subdirectory of your XTest home directory (available also as ${plugins.install.dir} property in XTest build script). Each plugin is installed in a directory with its name, which is called plugin home (also exported as a property).  In this directory have to be plugin descriptor in a file called plugin_descriptor.xml. This file basically described the plugin, more on this you can read in the following section. The rest of the structure of the plugin is up to plugin developer itself - there are no rules to be adhered). The sources for the standard plugins supplied with XTest are available in plugins_src directory in XTest module.

The directory layout is shown below (for the jvm plugin):

${xtest.home}/
       |--- bin/ - XTest launch scripts, ...
       |--- lib/ - XTest libraries, stylesheets, ...
       |--- ...
       |--- plugins/ - plugins home, available as ${plugins.install.dir} from XTest build script
               |--- jvm/ - plugin name, exported as ${xtest.plugin.home} when running the plugin
                     |--- lib/ ( files used by jvm plugin - nevertheless, plugin developer can use whatever layout he wants)
                     |--- plugin_descriptor.xml - the plugin descriptor describing the plugin itself (more details are available below)

Included Plugins

The base distribution of XTest contains the following plugins:

• 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.
  

How to Write a Simple Plugin

To do ...

Plugin Properties

This sections provides description of all properties supplied by XTest to plugins in runtime (i.e. when plugins are running). You should use these properties instead of path references to other plugins and xtest home, since the layout of XTest files and directories can change without a prior notice.

Property name	Description
xtest.plugin.home	Home directory of the plugin itself. You can use this property to navigate in files and directories of the plugin.
xtest.plugin.name	Name of the plugin itself.
xtest.plugin.version	Version of the plugin itself
xtest.{plug_name}.plugin.home	References to home of all plugins, which this plugins extends. For example the hypothetical 'xide' plugin described as an example above could use a reference called 'xtest.ide.plugin.home' to get to 'ide' plugin home. Also since the 'ide' plugin extends the 'base' plugin, 'xide' plugin can use also 'xtest.base.plugin.home' to get to the home directory of the 'base' plugin.
xtest.preferred.plugins	User's property used to specify which plugins should be used rather than the original one. For details, please see the 'General Concept' in the Design section.

Properties which Plugin Needs to Understand

Future Tasks

If plugins concept will prove it is a viable solution, it would be nice if it could be enhanced further. In particular it would be nice if plugins could use not only ant tasks as the actions, but also standard java classes/methods. When actions would be implemented as the standard java code, it would definitely clarify the development/execution/debuggin of XTest, as well as users would not be bothered by tons of output generated by ant.