com.tplan.robot.scripting.report
Class XSLReportProvider

java.lang.Object
  com.tplan.robot.scripting.report.XSLReportProvider

All Implemented Interfaces:

Plugin, Configurable, ConfigurationChangeListener, CommandListener, ReportProvider, ScriptListener, ActionListener, EventListener

public class XSLReportProvider
extends Object
implements Plugin, ReportProvider, Configurable, ScriptListener, ActionListener, CommandListener, ConfigurationChangeListener

Enterprise Report Provider. It is a highly customizable report generator capable of creating reports in XML and HTML formats.

The class works on top of another internal enterprise feature - test result XML generator. It is an object able to create an XML with test results and output objects created by the test script, such as test suites declarations, scripts (test cases), test steps, screenshots, warnings, image comparisons etc.

The report provider takes an advantage of the test result XML to produce a report through an XSL transformation:

• When the output format is XML (the output file specified through the Report command has the .xml extension), the provider just inserts a link to the XSL file into the test result XML, making it displayable by any XSL-compliant web browser. As most recent web browsers support the XML/XSL transformation, the XML report may be then viewed by any web browser the same way as HTML or parsed by any other third party tool. See an online Sample XML Report example.
• When the output format is HTML (the file extension is either .htm or .html), the provider performs transformation of the test result XML using the given XSL file to produce an HTML report.

There is a default XSL file bundled with the code which transforms the test result data to the same visual report format as the default HTML provider distributed with the free T-Plan Robot Enterprise version. The file delivers exactly the same functionality and it even uses the same preference values. The added value of the Enterprise Report Provider is that it allows to customize the report through a custom XSL file. This way the report appearance may be radically changed to comply with individual needs.

For example, to change the logo image in the test report perform the following steps:

• Save contents of the internal XSL to a file on your file system. We recommend to save it to the T-Plan Robot Enterprise installation folder because it makes the configuration and eventual migration easy.
• Select Edit->Preferences in the T-Plan Robot Enterprise GUI to open the Preferences window. Find a node labeled "Enterprise Report Provider" and select it. A panel with the provider preferences should be displayed.
• Select the "Use custom XSL report template" check box and enter the path to your custom XSL file to the text field below. If you saved the file to the T-Plan Robot Enterprise installation folder, you may enter just the file name.
• Enter your logo image path to the text field labeled "Files To Copy". This will make sure that the image file gets copied to the report output folder. We recommend to copy the logo image file to the installation folder and enter just the file name to the text field. If you reference your logo image through a global URL, you may skip this step.
• Select OK to save the preferences.
• Open the XSL file in a text editor. Locate the logo image file name "tplogo.png" and replace it with the file name (or an URL) of your custom logo.

That's it! The next time you execute a test script with the Report command, it will use your custom XSL template to create the report with your logo. It will also copy the logo image file to the output folder to make it accessible by the report.

The XSL template allows to customize the report in any way. Should you want to learn more about XSL formast and transformations, we suggest you to review the following resources:

• XSLT Overview at wikipedia.org,
• XSLT Tutorial - introductory XSL/XSLT tutorial provided by w3schools.com,
• XSLT Tutorial by ZVON - extensive and detailed multi-language tutorial.

Be however aware that XSL transformations are resource intensive. As the report gets refreshed every time the status changes or a new output object is created, it may decrease performance of the whole tool, especially in test scripts with a large number of output objects. Should you experience any delays or low performance, consider one of the following steps:

• Move the Report command call to the end of your test script. It will save the time needed for frequent refresh during the test script execution while the resulting report will be the same. The trade off is that you won't be able to see the report early and you also have to make sure that the Report command gets called before any script termination through the Exit command.
• Open the provider's preferences and modify its behavior. It allows you to restrict report refresh conditions.
• If your output format is HTML, change it to XML. This way you avoid the XSL transformation and the provider just links the XSL style sheet to the XML report. The XSL transformation then gets performed by the web browser used to view the XML.

T-Plan Robot Enterprise, (C) 2009-2013 T-Plan Limited. All rights reserved.

Field Summary

static String	INTERNAL_XSL_FILE Name of the internal XSL file.
static int	STATUS_CODE_FAIL
static int	STATUS_CODE_PAUSED
static int	STATUS_CODE_RUNNING
static int	STATUS_CODE_STOPPED
static int	STATUS_CODE_SUCCESS
static String	XSL_CONFIG_ATTACH_SCRIPTS XSL property - attach script configuration flag.
static String	XSL_CONFIG_ATTACH_TEMPLATES XSL property - attach template images configuration flag.
static String	XSL_CONFIG_CREATE_COMMENT_TABLE XSL property - create warning table configuration flag.
static String	XSL_CONFIG_CREATE_COMPARISON_TABLE XSL property - create image comparison table configuration flag.
static String	XSL_CONFIG_CREATE_WARNING_TABLE XSL property - create warning table configuration flag.
static String	XSL_CONFIG_DISPLAY_FAILED_COMPARISONS_ONLY XSL property - create image comparison table configuration flag.
static String	XSL_CONFIG_DISPLAY_WARNINGS XSL property - display warnings in the HTML body configuration flag.
static String	XSL_CONFIG_INCLUDE_STEPS_IN_BODY XSL property - create warning table configuration flag.
static String	XSL_PARAM_DURATION_SECONDS XSL property - number of seconds.
static String	XSL_PARAM_DURATION_STRING XSL property - a string expressing start and end date and duration of automation.
static String	XSL_PARAM_LOG_FILE XSL property - log file.
static String	XSL_PARAM_PAUSE_REASON XSL property - pause reason.
static String	XSL_PARAM_STATUS XSL property - status code.

Constructor Summary

XSLReportProvider()

Method Summary

void	actionPerformed(ActionEvent e) Implementation of the ActionListener interface.
void	checkDependencies(PluginManager manager) Check whether the current product installation contains all dependencies (other plugins) required to install this plugin.
void	commandEvent(CommandEvent e) This method is called when a command handler fires an event.
void	configurationChanged(ConfigurationChangeEvent evt) This method gets called when a configuration parameter is changed.
int	create(ScriptingContext context, Map params) Create a report.
String	getCode() Get plugin code.
Date	getDate() Get plugin release date.
String	getDescription() Get plugin description to be displayed in the GUI.
String	getDisplayName() Get short plugin name to be displayed in the GUI.
Class	getImplementedInterface() Get Class of the exposed functional interface that this plugin implements.
int[]	getLowestSupportedVersion() Get the lowest required version of T-Plan Robot Enterprise.
String	getMessageAfterInstall() Get text of a message to be displayed after installation of this plugin.
String	getMessageBeforeInstall() Get text of a message to be displayed before installation of this plugin.
List<Preference>	getPreferences() Get metadata of displayable/editable configurable parameters.
String	getSupportContact() Get support contact.
String[]	getSupportedFormats() Get formats supported by this particular provider.
String	getUniqueId() Get unique ID associated with the plugin.
String	getVendorHomePage() Get the vendor home page.
String	getVendorName() Get vendor (provider) name to be displayed in the GUI.
int[]	getVersion() Get plugin version in form of an integer array.
boolean	isOfflineMode()
boolean	requiresRestart() Indicate whether installation of this plugin requires application restart.
void	scriptEvent(ScriptEvent event) Gets called when a script event is available.
void	setConfiguration(UserConfiguration cfg) If an object implementing this interface is a plugin (i.e.
void	setOfflineMode(boolean offlineMode)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INTERNAL_XSL_FILE

public static String INTERNAL_XSL_FILE

Name of the internal XSL file.

XSL_PARAM_DURATION_STRING

public static final String XSL_PARAM_DURATION_STRING

XSL property - a string expressing start and end date and duration of automation.

See Also:

Constant Field Values

XSL_PARAM_DURATION_SECONDS

public static final String XSL_PARAM_DURATION_SECONDS

XSL property - number of seconds.

See Also:

Constant Field Values

XSL_PARAM_STATUS

public static final String XSL_PARAM_STATUS

XSL property - status code.

See Also:

Constant Field Values

XSL_PARAM_PAUSE_REASON

public static final String XSL_PARAM_PAUSE_REASON

XSL property - pause reason.

See Also:

Constant Field Values

XSL_PARAM_LOG_FILE

public static final String XSL_PARAM_LOG_FILE

XSL property - log file.

See Also:

Constant Field Values

XSL_CONFIG_ATTACH_SCRIPTS

public static final String XSL_CONFIG_ATTACH_SCRIPTS

XSL property - attach script configuration flag.

See Also:

Constant Field Values

XSL_CONFIG_CREATE_WARNING_TABLE

public static final String XSL_CONFIG_CREATE_WARNING_TABLE

XSL property - create warning table configuration flag.

See Also:

Constant Field Values

XSL_CONFIG_CREATE_COMMENT_TABLE

public static final String XSL_CONFIG_CREATE_COMMENT_TABLE

XSL property - create warning table configuration flag.

See Also:

Constant Field Values

XSL_CONFIG_INCLUDE_STEPS_IN_BODY

public static final String XSL_CONFIG_INCLUDE_STEPS_IN_BODY

XSL property - create warning table configuration flag.

See Also:

Constant Field Values

XSL_CONFIG_DISPLAY_WARNINGS

public static final String XSL_CONFIG_DISPLAY_WARNINGS

XSL property - display warnings in the HTML body configuration flag.

See Also:

Constant Field Values

XSL_CONFIG_ATTACH_TEMPLATES

public static final String XSL_CONFIG_ATTACH_TEMPLATES

XSL property - attach template images configuration flag.

See Also:

Constant Field Values

XSL_CONFIG_CREATE_COMPARISON_TABLE

public static final String XSL_CONFIG_CREATE_COMPARISON_TABLE

XSL property - create image comparison table configuration flag.

See Also:

Constant Field Values

XSL_CONFIG_DISPLAY_FAILED_COMPARISONS_ONLY

public static final String XSL_CONFIG_DISPLAY_FAILED_COMPARISONS_ONLY

XSL property - create image comparison table configuration flag.

See Also:

Constant Field Values

STATUS_CODE_RUNNING

public static final int STATUS_CODE_RUNNING

See Also:

Constant Field Values

STATUS_CODE_PAUSED

public static final int STATUS_CODE_PAUSED

See Also:

Constant Field Values

STATUS_CODE_STOPPED

public static final int STATUS_CODE_STOPPED

See Also:

Constant Field Values

STATUS_CODE_FAIL

public static final int STATUS_CODE_FAIL

See Also:

Constant Field Values

STATUS_CODE_SUCCESS

public static final int STATUS_CODE_SUCCESS

See Also:

Constant Field Values

Constructor Detail

XSLReportProvider

public XSLReportProvider()

Method Detail

getSupportedFormats

public String[] getSupportedFormats()

Description copied from interface: ReportProvider

Get formats supported by this particular provider. The formats are not case sensitive and they must correspond to the supported file extensions. For example, a provider able to generate XML, HTML and Excel formats should return new String[] {"xml", "html", "htm", "xls"}.

The method is used by the calling Report instance to validate file name provided by the script command. If the file doesn't have one of the extensions supported by the selected provider, a syntax error is reported.

Specified by:

getSupportedFormats in interface ReportProvider

Returns:

array of supported formats (file extensions).

create

public int create(ScriptingContext context,
                  Map params)

Create a report.

Specified by:

create in interface ReportProvider

Parameters:

context - an execution context.

params - Report command argument map.

Returns:

exit code. A value of zero (0) means success while any other number indicates a failure.

actionPerformed

public void actionPerformed(ActionEvent e)

Implementation of the ActionListener interface.

This method is at present used just by the state update timer which invokes this method at regular intervals. The method then creates a screenshot of the RFB buffer and saves it into a so called state image. A link to this image is then elaborated into the report as a view of the current state.

This class uses its own instance of the ScreenshotCommand class because we don't want the default ScreenshotCommand class to fire all the listeners which would make the report command to re-create the HTML report and even include the state image into the report body.

Specified by:

actionPerformed in interface ActionListener

Parameters:

e - an action event.

scriptEvent

public void scriptEvent(ScriptEvent event)

Description copied from interface: ScriptListener

Gets called when a script event is available.

Specified by:

scriptEvent in interface ScriptListener

Parameters:

event - a script event.

commandEvent

public void commandEvent(CommandEvent e)

Description copied from interface: CommandListener

This method is called when a command handler fires an event.

Specified by:

commandEvent in interface CommandListener

configurationChanged

public void configurationChanged(ConfigurationChangeEvent evt)

Description copied from interface: ConfigurationChangeListener

This method gets called when a configuration parameter is changed.

Specified by:

configurationChanged in interface ConfigurationChangeListener

Parameters:

evt - A ConfigurationChangeEvent object describing the event source and the parameter that has changed.

getPreferences

public List<Preference> getPreferences()

Description copied from interface: Configurable

Get metadata of displayable/editable configurable parameters. This method should declare a list of metadata for all configurable parameters which may be editable in the GUI. If the returned list is not null and contains at least one parameter, it gets picked up by the Preferences dialog which creates a panel with GUI components allowing to edit the declared configuration parameters.

Specified by:

getPreferences in interface Configurable

Returns:

a list of metadata for all public editable configuration parameters.

getCode

public String getCode()

Description copied from interface: Plugin

Get plugin code. This string serves as an identifier of the functionality delivered by the plugin. For example, desktop client plugins return protocol name like "RFB" or "RDP" as their code.

Plugin code is used by pluggable instance factories to identify a particular plugin. It may be used to replace internal plugins with third party code. For example if you develop a class which implements this and the com.tplan.robot.remoteclient.RemoteDesktop interfaces and the getCode() method returns "RFB", it will replace the internal implementation of the RFB (VNC) client.

Specified by:

getCode in interface Plugin

Specified by:

getCode in interface ReportProvider

Returns:

plugin code (identifier). The name must not be null.

getDisplayName

public String getDisplayName()

Description copied from interface: Plugin

Get short plugin name to be displayed in the GUI.

Specified by:

getDisplayName in interface Plugin

Returns:

short plugin name.

getDescription

public String getDescription()

Description copied from interface: Plugin

Get plugin description to be displayed in the GUI.

Specified by:

getDescription in interface Plugin

Returns:

plugin description. May be null.

getVendorName

public String getVendorName()

Description copied from interface: Plugin

Get vendor (provider) name to be displayed in the GUI.

Specified by:

getVendorName in interface Plugin

Returns:

vendor name. May be null.

getSupportContact

public String getSupportContact()

Description copied from interface: Plugin

Get support contact. If the contact is a valid mail link like "mailto:<mailaddress>" or an HTTP link like "http://<link>", the application may follow it with appropriate program (mail client or web browser).

Specified by:

getSupportContact in interface Plugin

Returns:

support contact. May be null or a text to be displayed by the GUI or a valid URI.

getVersion

public int[] getVersion()

Description copied from interface: Plugin

Get plugin version in form of an integer array. Major version numbers are first. For example, version 1.2.3 should be represented as new int[] { 1, 2, 3 }.

Specified by:

getVersion in interface Plugin

Returns:

version number.

getImplementedInterface

public Class getImplementedInterface()

Description copied from interface: Plugin

Get Class of the exposed functional interface that this plugin implements. For example remote desktop clients return com.tplan.robot.remoteclient.RemoteDesktopClient.class.

Specified by:

getImplementedInterface in interface Plugin

Returns:

class instance of the implemented functional interface.

requiresRestart

public boolean requiresRestart()

Description copied from interface: Plugin

Indicate whether installation of this plugin requires application restart. If it returns true, users are asked to restart after plugin installation via GUI.

Specified by:

requiresRestart in interface Plugin

Returns:

true if installation of the plugin requires application restart, false otherwise.

getVendorHomePage

public String getVendorHomePage()

Description copied from interface: Plugin

Get the vendor home page. If the contact is a valid HTTP link like "http://<link>", the application may follow it with appropriate program (typically web browser).

Specified by:

getVendorHomePage in interface Plugin

Returns:

vendor home page URL.

getDate

public Date getDate()

Description copied from interface: Plugin

Get plugin release date.

Specified by:

getDate in interface Plugin

Returns:

plugin release date.

getUniqueId

public String getUniqueId()

Description copied from interface: Plugin

Get unique ID associated with the plugin. The plugin manager uses the ID together with the version string to identify whether a plugin is already installed and whether a newer version of the same plugin is available.

The unique ID in fact identifies a particular plugin delivered by a particular vendor. Plugin developers are recommended to choose an ID and keep it constant for all versions of one particular plugin. The ID is never displayed in the GUI so it doesn't have to be a readable text. To avoid conflicts with other vendors it is recommended to elaborate vendor or author name and feature description into the ID, for example "custom RFB client implemented by John Doe".

Specified by:

getUniqueId in interface Plugin

Returns:

unique plugin ID.

getLowestSupportedVersion

public int[] getLowestSupportedVersion()

Description copied from interface: Plugin

Get the lowest required version of T-Plan Robot Enterprise. If user attempts to install the plugin on a lower version, an error is reported.

Specified by:

getLowestSupportedVersion in interface Plugin

Returns:

the lowest T-Plan Robot Enterprise version supported by this plugin.

getMessageBeforeInstall

public String getMessageBeforeInstall()

Description copied from interface: Plugin

Get text of a message to be displayed before installation of this plugin. It may contain any relevant user information.

Specified by:

getMessageBeforeInstall in interface Plugin

Returns:

message to be displayed before installation.

getMessageAfterInstall

public String getMessageAfterInstall()

Description copied from interface: Plugin

Get text of a message to be displayed after installation of this plugin. It may contain any relevant user information.

Specified by:

getMessageAfterInstall in interface Plugin

Returns:

message to be displayed after installation.

checkDependencies

public void checkDependencies(PluginManager manager)
                       throws DependencyMissingException

Description copied from interface: Plugin

Check whether the current product installation contains all dependencies (other plugins) required to install this plugin. This method is called before the plugin is installed and it should throw a DependencyMissingException if one or more dependencies are missing.

Specified by:

checkDependencies in interface Plugin

Parameters:

manager - shared instance of the plugin manager.

Throws:

DependencyMissingException - when one or more dependencies requested by this plugin is missing.

setConfiguration

public void setConfiguration(UserConfiguration cfg)

Description copied from interface: Configurable

If an object implementing this interface is a plugin (i.e. implements also the Plugin interface) and is instantiated through a supported plugin factory, the Plugin Manager calls this method right after an instance of this object is created.

Custom objects which do not already have their configuration parameters in the default configuration file should take advantage of this method to store their configuration into the shared User Configuration instance. It is recommended to call the UserConfiguration.saveConfiguration() method in the end to save the configuration to the hard drive.

Objects wishing to be notified of changes of configuration parameters should implement the ConfigurationChangeListener interface and register with the UserConfiguration instance through the addConfigurationChangeListener() method.

Specified by:

setConfiguration in interface Configurable

Parameters:

cfg - global shared instance of user configuration preloaded with parameters from the default and user configuration files.

isOfflineMode

public boolean isOfflineMode()

Returns:

the offlineMode

setOfflineMode

public void setOfflineMode(boolean offlineMode)

Parameters:

offlineMode - the offlineMode to set