Myfaces Portlet Bridge Test Harness

Introduction

permlink The Myfaces Portlet Bridge Test Harness is a system to test a portlet bridge implementation against the specification. It consists of a portlet web applications containing one or more portlets and a testing infrastructure which will exercise each portlet on a Pluto page. It has two main purposes.

1. Be able to quickly run a MyFaces Portlet Bridge implementation against a built-in pluto/jetty environment in order to test spec compliance as a prelude to final TCK testing and approval. This includes verifications against MyFaces and Mojarra. The testing framework should also allow other bridge implementations to be tested in this environment. If the bridge implementation is available in a maven repository, it can be substituted in for the MyFaces Portlet Bridge simply by setting a few command line arguments.

2. Be able to test the generate test war files which may be deployed into other portal environments in order to test portlet bridge implementation on other portals. Once the war files are deployed, the test harness should be able to be run against these external servers to ensure compliance.

How does this relate to the TCK

permlink The Portlet Bridge Test harness will ease specification compliance testing of JSF Portlet Bridges, but it is not meant to replace the TCK. According to the JSP, the company responsible for the project must produce a well versioned and complete TCK to ensure compliance. In this case, that would be Oracle. This project will be the basis for the TCK compliance testing released from Oracle. It is intended that the tests will be developed here and, at some point, Oracle will repackage the code into an official TCK. In order to claim spec compliance, all Portlet Bridge implementation will need to pass the official TCK, but using this test harness until that time should give you a fairly good indicator of where your bridge implementation may fall short.

Installation

The current test suite can be downloaded from http://svn.apache.org/repos/asf/myfaces/portlet-bridge/testsuite/trunk. For example, assuming that the source control tool being used is command-line Subversion, the code can be installed into a directory <TCK_DIR> using the command:

svn co http://svn.apache.org/repos/asf/myfaces/portlet-bridge/testsuite/trunk <TCK_DIR>

The test suite may then be built and optionally tested as a set of war files. The following sections describe the main build scenarios and how they are run.

Testing bridge implementations

The test suite portlet war files can be compiled, built, deployed to an embedded server and run against a Pluto client using the command:

mvn install

This will include the latest Portlet Bridge, currently the 1.0.0-SNAPSHOT. This behaviour may be customised using various options. A full description of the build properties can be found here. The following are some of the more likely examples.

Changing JSF Implementations

By default the test suite will compile and run the tests against Mojarra. Although this is an Apache project, Mojarra is the default because of the TCK compliance issues. It is very simple to change the tests to run against myfaces however, by simply adding:

-Djsf=myfaces

Also, by default the test harness tests against the minimum JSF versions avaialble in the specification. For mojarra, it will test against 1.2_03 and for myfaces it will test against 1.2.2. To change the version of faces being used to run the tests, you simply need to add the following:

-Djsf.version=1.2.7

Therefore, running the tests against Myfaces 1.2.7 would be:

mvn -Djsf=myfaces -Djsf.version=1.2.7 install

Substituting Bridge Implementation

One of the main goals of the Test Framework is to be able to quickly and easily test other bridge implementations. There are a lot of configuration options for doing this provided your bridge is available in the maven repository. If it is not, then you will need to mock up the test war file yourself and deploy the app to an external portal server. Eventually the Test Harness should be able to support running against servers in this environment. For now, lets start with the simplest case and work our way from there:

Currently the framework is set up to test against the Portlet Bridge 1.0.0-SNAPSHOT. This means that for everything to work, you would have had to have installed the latest trunk. Let's say, however, that you want to run the test harness against the latest released version of the bridge. You could specify this by setting the following:

mvn -Dportlet-bridge.version=1.0.0-beta-2 install

This will download the 1.0.0-beta-2 version of the MyFaces Portlet Bridge and run the verification tests against it. Expect quite a few failures in the beta code, the trunk passes many more of the verification tests.

Now let us say that we want to run the Testing framework against the JBoss Portlet Bridge, you could specify the artifact and the group id's as follows:

mvn -Dportlet-bridge.version=1.0.0-CR3 -Dportlet-bridge.groupId=org.jboss.portletbridge -Dportlet-bridge.api.artifactId=portletbridge-api -Dportlet-bridge.impl.artifactId=portletbridge-impl -Dmaven.repo.remote=http://repository.jboss.org/maven2/ install

Building war files for deployment on external portal environments

The portlet war files may be generated on their own for deployment and testing on a portal environment outside maven. The general format of the command is:

mvn clean install -Dtck.generate-war[=<environment name>]

The project is structured as a main directory (TCK_DIR) with subdirectories with names starting with portlet-bridge-testsuite-. The testsuite war files can be found in the directories <TCK_DIR>/portlet-bridge-testsuite-*/target directories.

Exactly what the war files contain may be configured using command line properties. For example, to generate war files to be run in an environment which already contains JSF and bridge libraries use the following command:

mvn clean install -Dtck.generate-war -DincludeBridge=false

Setting the tck.generate-war property will skip the test phase of the build and setting includeBridge to false excludes the bridge libraries from the generated war files. War files for certain environments may be set up by specifying a value for tck.generate-war.

Pluto 1.x

To generate war files to run in a Pluto 1.x environment use the command:

mvn clean install -Dtck.generate-war=pluto

The generated war files will automatically include:

To include the myfaces JSF libraries instead use:

mvn clean install -Dtck.generate-war=pluto -Djsf=myfaces

Pluto 2.0

To generate war files to run in a Pluto 2.0 environment use:

mvn clean install -Dtck.generate-war=pluto2.0

The same configuration and library changes will be made but for Pluto 2.0 where appropriate. The generated wars can now be run on the Pluto 2.0/Tomcat 6 bundle.

Command line properties

The following may be used to change the behaviour of the build using the syntax mvn install -Dproperty name=value

Property name

Default value

Allowed values

Description

jsf

mojarra*

mojarra, myfaces

allows you to specify the faces implementation to be used for testing. If used in conjunction with the -Dportlet.tck.make-war=true property then specifying this flag will include the JSF implementation specified in the war file's WEB-INF/lib

jsf.version

1.2_03 (for mojarra) or 1.2.2 (for myfaces)

allows you to specify a version number of the Faces implementation to test against.

portlet-bridge.groupId

org.apache.myfaces.portlet-bridge

allows you to specify a groupId for the bridge implementation which should be tested against. It is assumed that this is available to maven. For more fine grained control (for instance if you want to use the R.I's api but your own bridge implementation), you can declare a groupId for the portlet-bridge.api.groupId and portlet-bridge.impl.groupId separately. By default, however, both of those properties contain the value of this property.

portlet-bridge.version

1.0.0-SNAPSHOT

allows you to specify a version for the bridge implementation which should be tested against. It is assumed that this is available to maven. For more fine grained control (for instance if you want to use the R.I's api but your own bridge implementation), you can declare a version for the portlet-bridge.api.version and portlet-bridge.impl.version separately. By default, however, both of those properties contain the value of this property.

portlet-bridge.api.groupId

${portlet-bridge.groupId}

see portlet-bridge.groupId

portlet-bridge.api.artifactId

portlet-bridge-api

allows you to specify a artifactId for the bridge api which should be tested against. It is assumed that this is available to maven.

portlet-bridge.api.version

${portlet-bridge.version}

see portlet-bridge.version

portlet-bridge.impl.groupId

${portlet-bridge.groupId}

see portlet-bridge.groupId

portlet-bridge.impl.artifactId

portlet-bridge-impl

allows you to specify a artifactId for the bridge implementation which should be tested against. It is assumed that this is available to maven.

portlet-bridge.impl.version

${portlet-bridge.version}

see portlet-bridge.version

tck.generate-war

No value

No value, pluto

Generates a testsuite war file for deployment on an external portal, i.e., without testing it on an embedded server. If it is set to pluto web.xml will be updated with Pluto 1.x configuration files. The bridge and JSF libraries will be included in the generated war along with their dependencies.

includeBridge

No value

No value, false

Controls whether the portlet bridge libraries are included in a generated war file. They are included by default but may be excluded by setting includeBridge to false.

Running_the_Test_Harness (last edited 2010-02-10 19:21:53 by AlistairWilson)