Full XWiki plugin guide

XWiki is an Open-Source enterprise wiki that makes it easy to create and share documents.
It also offers a powerful Plugin architecture that allows us to write plugins that change the way things work or add entirely new functionalities.
So this led us to the conclusion that XWiki was a good choice for a Test document repository.

1. Installation

Standalone distribution

The standalone distribution is ideal for those who want to use GreenPepper quickly as possible. If you are a first-time user or just evaluating GreenPepper, this distribution should be selected.

You can download the GreenPepper XWiki distribution (XWiki Enterprise 2.x with GreenPepper plugin already setup) from the download page.

See the Administration guide of XWiki for more details to setup XWiki.

Manual installation

The manual installation involves many actions and should be executed by someone familiar with XWiki. In case the installation does not work, consult our forum and don't hesitate to ask for help.

From an existing XWiki installation, stop the XWiki instance if it is running then execute the following actions.

Copy to WEB-INF/lib

Copy the greenpepper-xwiki-plugin-x.x-complete.jar to the WEB-INF/lib directory of your XWiki webapps.

Register the GreenPepper plugin

Add the GreenPepper plugin entry class com.greenpepper.xwiki.GreenPepperPlugin to the list of active plugins under the file WEB-INF/xwiki.cfg.

WEB-INF/xwiki.cfg

#-# List of active plugins.
xwiki.plugins=\
	com.xpn.xwiki.monitor.api.MonitorPlugin,\
	com.xpn.xwiki.plugin.skinx.JsSkinExtensionPlugin,\
	com.xpn.xwiki.wysiwyg.server.plugin.WysiwygPlugin, \
	...
	com.xpn.xwiki.plugin.tag.TagPlugin, \
	com.greenpepper.xwiki.GreenPepperPlugin

GreenPepper web.xml

Add the following XML snippet to the file WEB-INF/web.xml inside the <web-app></web-app> element.

WEB-INF/web.xml

<!-- GreenPepper -->
<listener>
	<listener-class>com.greenpepper.xwiki.web.GreenPepperContextListener</listener-class>
</listener>

<servlet>
	<servlet-name>GreenPepper</servlet-name>
	<servlet-class>com.greenpepper.xwiki.web.GreenPepperServlet</servlet-class>
</servlet>

<servlet>
	<servlet-name>GreenPepper XMLRPC Api</servlet-name>
	<servlet-class>com.greenpepper.xwiki.xmlrpc.GreenPepperXmlRpcServlet</servlet-class>
</servlet>

<servlet-mapping>
	<servlet-name>GreenPepper</servlet-name>
	<url-pattern>*.greenpepper</url-pattern>
</servlet-mapping>

<servlet-mapping>
	<servlet-name>GreenPepper XMLRPC Api</servlet-name>
	<url-pattern>/greenpepper/xmlrpc/*</url-pattern>
</servlet-mapping>

Templates javascript.vm

Add the following code snippet at the end of the file templates/javascript.vm.

templates/javascript.vm

## GreenPepper
#set($gpp = $xwiki.getPlugin("GreenPepper"))
#if($gpp)$gpp.javascript()#end

Templates stylesheets.vm

Add the following code snippet at the end of the file templates/stylesheets.vm.

templates/stylesheets.vm

## GreenPepper
#set($gpp = $xwiki.getPlugin("GreenPepper"))
#if($gpp)$gpp.style()#end

Templates contentview.vm

Using the Colibri Skin

Add the following code snippet before the <div id="xwikicontent">.

XWiki 2.3+

The contentview.vm is not longer under the Colibri Skin directory. Modify the contentview.vm under the templates directory.

contentview.vm

#set($gpp = $xwiki.getPlugin("GreenPepper"))
#if($gpp)<div id="gp_header">$gpp.header()</div><div id="gp_content"></div>#end

Restart XWiki

Restart the XWiki instance and you should be ready to use GreenPepper.

2. Configure GreenPepper XWiki plugin

GreenPepper plugin setup

The plugin will alert you when GreenPepper need to be configured (ex: first time use or license renewal). You will need to click the icon to configure GreenPepper. This icon will only be available when the active XWiki user has administration right.

Database Setup

GreenPepper has its own database to store multiple data such as executions results, references and so on.
You will have two options:

Quick install: an HSQL database will be created locally. This setup is not suggested for a production environment, it was put inplace for quick trial setup purposes.
Custom install: This will allow you to setup GreenPepper to use an external DBMS via a JNDI name.

License

The plugin will alert you when GreenPepper need to upload a valid license.

You will be able upload your licence and see your licence details :

Runner

You will be able to add/remove/update your runners (GreenPepper Open; Test engine)

Java Runner

The most recent Java runner will be available by default. At each start of Confluence, we make sure there is a Java Runner matching the GreenPepper plugin version.

Due to an incompatibility with the actual XML-RPC library from XWiki, you need to add the following jars to the classpath of the Java Runner (download each one and specify the full path)

.Net Runner

Default command line :	.../GreenPepper.exe ${inputPath} ${outputPath} -a ${classpaths} -r ${repository} -f ${fixtureFactory} --xml
Main class :	*leave it empty*
Environment :	.NET
Classpaths (mandatory) :	.../GreenPepper.Core.dll .../GreenPepper.Extensions.dll .../CookComputing.XmlRpc.dll

All required assemblies are found in the GreenPepper Open .Net binaries.
Note : You need to specify the full path for the Assembly files and the GreenPepper.exe file.

Maven Runner

Default command line :	java -cp ${classpaths} ${mainClass} ${inputPath} ${outputPath} -l ${locale} -r ${repository} -f ${fixtureFactory} --xml --pdd ${projectDependencyDescriptor}
Main class :	com.greenpepper.maven.runner.Main
Environment :	JAVA
Classpaths (mandatory) :	.../apache-maven-2.0.x/lib/maven-2.0.x-uber.jar .../apache-maven-2.0.x/boot/classworlds-1.1.jar .../greenpepper-maven-runner-x.x-complete.jar

Note : You need to specify the full path for the classpath files.
More info Maven Runner.

Project Manager

Your Space registration to GreenPepper.
From this pane you will be able to:

Set your GreenPepper credentials to be able to run the tests if the space is secured.
Add/Remove/Edit your System under tests for a specific GreenPepper project.

Register a Space to use GreenPepper

The plugin will alert you when a Space is actually not registered as a GreenPepper project.

Responding Yes to this question will register the current Space as a new GreenPepper project. You then will need to add your System Under Tests using the plugin configuration screens under the Project Management tab.

Un-register a Space

To un-register a Space, simply delete the XWiki object XWiki.GreenPepperSpaceClass associated to the main page of the Space.

3. Use

Make a page executable

As you might have already noticed, Pages in registered spaces have a checkbox labeled GreenPepperized. Checking it will automatically register the document in the server. The default System Under Test will be automatically associated to your newly executable page.

I. Configurating your executable page

You might want to associate your page to other Systems Under Test. To do so, click the Configure button.
You can now remove or add System Under Test associations. This is important if you want the greenpepper-labels or greenpepper-children macro to select your page.

II. Executing your page

You can now Execute your page. Next to the Execute button you will find which System Under Test will be involved. You can select the desired System Under Test. The dropdown list only contains the Systems Under Test configured in step I.

GreenPepper XWiki Macros

Children Macro

Description: This macro can execute a batch of documents resulting from a page hierarchy.
Syntax:

{{greenpepper-children/}}

Optional parameters:

all: Default --> false
If set to true, the complete hierarchy of the parent page will be included in the execution list.
Otherwise only the first-level children will be included.
spaceKey: Default --> Macro's residing space
You can specify a specific space for your parent page.
pageTitle: Default --> Macro's residing page
You can specify a specific title for the parent page.
title: Default --> blank
You can specify your own title.
expanded: Default --> false
You can ask for the list to be expanded on page load.
suts: Default --> All
You can narrow the list to specific Systems Under Test (1 or more; if more than one they must be separated by a comma).
sort Default --> Hierarchical sort
You can configure the way children are sorted. Choose Creation to sort by content creation dates, Title to sort alphabetically by titles and Modified to sort by modification dates (last date first).
reverse Default --> false
You can reverse the sorting sequence.
openInSameWindow Default --> false
You can control whether or not the link to the specification will open in the same window.

EXAMPLE

{{greenpepper-children spaceKey="GreenPepper Demo" pageTitle="Demo" expanded="true"/}}

Import Macro

Description: This macro allows you to import classes into your executable document without polluting it with undesirable and unmeaningful user tables.
Syntax:

{{greenpepper-import parameter="package1|package2|...|packageN" /}}

EXAMPLE

{{greenpepper-import parameter="my.class.to.import|some.other.class.to.import"/}}

This will generate the following hidden table:

import

my.class.to.import

some.other.class.to.import

Info Macro

Description: This macro allows you to create tables and/or bullet lists that you do not want to be processed as executable specifications within your executable documents.
Syntax:

{{greenpepper-info}} _your body_ {{/greenpepper-info}}

EXAMPLES

{{greenpepper-info}}
* My bullet list
* Some information 
{{/greenpepper-info}}

Labels search Macro

Description: This macro can execute a batch of documents resulting from a label search.
Syntax:

{{greenpepper-labels\}}

Mandatory parameter:

labels:
You can pre-enter the labels to base the search on.
Using the , as the label separation is equivalent to an OR query. Therefore, label1,label2 will retrieve all pages labeled by label1 OR label2.
Using the & as the label separation is equivalent to an AND query. Therefore, label1&label2 will retrieve all pages labeled by label1 AND label2.

Optional parameters:

spaceKey: Default --> None
You can narrow the label search to a specific space.
If none is specified, the available GreenPepperized spaces will be in a select list.
title: Default --> blank
You can specify your own title.
expanded: Default --> false
You can ask for the list to be expanded on page load.
suts: Default --> All
You can narrow the list to specific Systems Under Test (1 or more; if more than one they must be separated by a comma).
sort Default --> NONE
You can configure the way children are sorted. Choose Creation to sort by content creation dates, Title to sort alphabetically by titles and Modified to sort by modification dates (last date first).
reverse Default --> false
You can reverse the sorting sequence.
openInSameWindow Default --> false
You can control whether or not the link to the specification will open in the same window.

EXAMPLE

{{greenpepper-labels spaceKey="GreenPepper Demo" title="Demo" labels="Demo" expanded="true" openInSameWindow="true"/}}

XWiki with IDE

To connect your Eclipse or Visual Studio environment to XWiki, then context path should look like

http://myxwikiserver/xwiki/greenpepper/xmlrpc

which is the main XWiki url followed by /greenpepper/xmlrpc and the handler is greenpepper1

4. Advanced XWiki

Maven Runner

These are the steps needed to configure the Maven runner.
Before you begin, you must verify the following:

You have Maven properly installed
You have downloaded the binaries of the GreenPepper Maven Runner
XWiki is well configured.

Maven Runner

Configuring a System Under Test can be tedious if you are having a lot of library dependencies. The Maven Runner allow you to use your existing pom.xml to resolve dependencies needed for the execution of specifications. Only the <dependencies> element of the pom.xml is read. Artifacts found will be resolved and added to the classpath of the runner. The artifact of the project itself will also be part of the classpath.

Maven Runner Configuration

From the Runner Configuration Panel, please follow these steps.

Click on Add a new Runner
Enter the name of your Runner (Mandatory)
Enter the Command line (please refer to Executing a Specification)
Know that (similar to velocity)
- ${classpaths} will be replaced by the Runner, SUT and Fixtures classpaths -(Mandatory for GP)
- ${mainClass} will be replaced by the Runner specified Main Class -(Mandatory for GP)
- ${inputPath} will be replaced by an input path -(Mandatory for GP)
- ${outputPath} will be replaced by an output path -(Mandatory for GP)
- ${locale} will be replaced by the user locale -Default: English (java only)
- ${repository} will be replace by the repository of the Specification resolver class -Default: FileSystemRepository
- ${fixtureFactory} will be replaced by the SUT Fixture Factory Class;Fixture Factory Args -Default: CoreFixtureFactory
- ${projectDependencyDescriptor} will be replaced by the project dependency descriptor file location-(Mandatory for the Maven runner)
  Example of a command line:
  java -mx252m -cp ${classpaths} ${mainClass} ${inputPath} ${outputPath} -l ${locale} -r ${repository} -f ${fixtureFactory} --xml --pdd ${projectDependencyDescriptor}
The main class : com.greenpepper.maven.runner.Main -(Mandatory, main Maven runner class)
The Server name and port (if you are using the Remote agent)
Click Save
Enter the location of your Runner library and its dependencies.
- GreenPepper Maven Runner library
  - greenpepper-maven-runner-x.x-complete.jar
- Maven libraries
  - maven-2.x.x-uber.jar from the lib directory of your Maven home
  - classworlds-1.1.jar from the boot directory of your Maven home

System Under Test Configuration

Make sure your XWiki Space is registered as a GreenPepper Project (see)

From the Space Registration Panel, please follow these steps.

Click on Add a new System Under Test
Enter the name of your System Under Test (Mandatory)
Select your Maven runner (Mandatory)
Enter the Fixture factory to use (optional)
Enter the Fixture arguments (optional)
Enter the Project Dependency Descriptor (Mandatory)
- Since we are using Maven, there is 2 possibilities :
  - use a valid Project Object Model file (pom.xml)
  - NEW in 2.8 use the groupId:artifactId:version (Maven Coordinates) where the version can be a Version Ranges
    Ex:
    greenpepper-open:greenpepper-core:2.7 greenpepper-open:greenpepper-extensions-db:[2.7,)
    You may need to add required repositories to the settings.xml of Maven (or routing all repositories using the mirrors) using the coordinates.
Click Save

Maven Plugin Fixture Artifact Dependency

By default, the Maven Runner will detect if the pom.xml is using the Maven Plugin to create fixture artifact. If so, the fixture artifact will be automatically added to the list of dependencies.

However, if you want to use a fixture artifact from another project, you will need to add the <dependency> of that project with <classifier>fixtures</classifier>.

NEW in 2.7.1/2.8.1/2.9 scopes
You can now specify scope on the command line (by default, runtime and compile are always use) :

--scope provided

Using an external database with XWiki

Web Container

Jetty

By default, the standalone XWiki distribution is using Jetty as the web container.

To use an external database for GreenPepper inside this distribution, you will need to :

Copy the JDBC driver to the directory WEB-INF/lib

Create a file WEB-INF/jetty-web.xml with the information about the database connectivity (JDBC). This example is defining a MySql database :

WEB-INF/jetty-web.xml

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">
<Configure class="org.mortbay.jetty.webapp.WebAppContext">
    <New id="GreenPepperDS" class="org.mortbay.jetty.plus.naming.Resource">
        <Arg></Arg>
        <Arg>java:comp/env/jdbc/GreenPepperDS</Arg>
        <Arg>
            <New class="org.apache.commons.dbcp.BasicDataSource">
                <Set name="driverClassName">com.mysql.jdbc.Driver</Set>
                <Set name="url">jdbc:mysql://localhost:3306/greenpepper?autoReconnect=true&amp;useUnicode=true&amp;characterEncoding=utf8</Set>
                <Set name="username">[dbuser]</Set>
                <Set name="password">[dbpassword]</Set>
                <Set name="maxActive">5</Set>
                <Set name="maxIdle">1</Set>
                <Set name="maxWait">10000</Set>
            </New>
        </Arg>
    </New>
</Configure>

Others

Follow the guide of your container to setup a JNDI datasource

Configuration

Go to the configuration screen of GreenPepper by clicking the icon or by browsing to *http://localhost:8080/xwiki/index.greenpepper* URL (make sure to point to your server host and port!).

Under the Database tab, you will need to use the Custom Installation type, select your database provider and enter the JNDI name of the datasource.

Make sure the Test link is successfull.

5. FAQ

I do not see the icon to configure GreenPepper

The icon is only available if you have administration right.

I got a NoSuchMethodError error :

If you have this error :

java.lang.NoSuchMethodError: org.picocontainer.MutablePicoContainer.addComponent(Ljava/lang/Object;)Lorg/picocontainer/MutablePicoContainer;
        	at org.codehaus.waffle.context.pico.PicoComponentRegistry.<init>(PicoComponentRegistry.java:75)
        	at org.codehaus.waffle.context.pico.PicoWaffleContextListener.buildComponentRegistry(PicoWaffleContextListener.java:19)
        	at org.codehaus.waffle.context.WaffleContextListener.contextInitialized(WaffleContextListener.java:34)
        	at com.greenpepper.xwiki.web.GreenPepperContextListener.contextInitialized(GreenPepperContextListener.java:31)
        	at org.mortbay.jetty.handler.ContextHandler.startContext(ContextHandler.java:548)
                ...

You need to remove the file WEB-INF/lib/picocontainer-1.2.jar. We already have a newer version of PicoContainer in the GreenPepper plugin and it is compatible with version 1.2. Most of the time, both can co-exist but sometimes, class loader issue will throw this type of error.