RichFaces-Demo - functional-test

About

Introduction

Functional test uses Maven and TestNG to run integration tests, which consist of automated browser testing using Selenium web application testing system.

Structure

Each component from RichFaces-Demo application corresponds with one package of test cases (except of components which share one presentation like data table, column and column group).

Each package is divided to one or more test cases presenting features of one component, traditionally distinguished by own tab.

Location

All test cases are under src/test/richfaces/integrationTest package, separated to packages by component name such as

org.jboss.richfaces.integrationTest.dataTable

and each test case is named by feature it corresponds like

org.jboss.richfaces.integrationTest.dataTable.ExtendedDataModelTestCase

TestNG descriptor

All of the tests forms suite and they are enumerated in TestNG descriptor src/test/resources/testng.xml.

Logging

By default selenium local instance of SeleniumServer logs to file target/selenium/selenium-server.log.

Resources

The majority of locators and assert values used in test are externalized in *.properties files.

You can find all string belonging to the given package of test cases in path such as src/test/resources/${package}/locators.properties (*/messages.properties respectively).

Build environment

Recommended: Maven 2.1.0, SunJDK 1.6.0_16

Requires locally built selenium-testing-lib library (obtain it from SVN repository)

Command-line usage

Basics

Tests run in integration-test phase, but also post-integration-test contains finalization processes.

So basic operation which you may want to trigger is run all of the tests - this operation requires specification of browser to use (propagated to Selenium configuration; consult documentation):

$ mvn post-integration-test -Dbrowser="*firefox"

(we can use also verify phase adequately since it is more simple to type)

$ mvn verify -Dbrowser="*firefox"

This command run the tests using externally run container. This is default behaviour, but you probably want to prepare all of the necessary stuff in container instead:

Container specification

Build are using Cargo to run richfaces-demo inside container. To use that, you must specify containerId definition:

$ mvn verify -Dbrowser="*firefox" -DcontainerId=tomcat6x

Configuration now supports:

By default, build is configured to obtain container installation archive from URL in specified version. In that way is container downloaded automatically (note: Cargo is caching the downloaded binary).

You can specify the version manually by redefining container.version:

$ mvn verify -Dbrowser="*firefox" -DcontainerId=tomcat6x -Dcontainer.version=6.0.18

You also may want avoid downloading container (note: it is highly recommended to specify the version of container to overwrite default version, because build isn't able to obtain it automatically from archive):

$ mvn verify -Dbrowser="*firefox" -DcontainerId=tomcat6x -Dcontainer.version=6.0.18 -Dcontainer.installer.url=file:/home/foo/binaries/apacha-tomcat-6.0.18.zip

(notice the file:/ prefix in container.installer.url definition)

Running one-off tests

By default, complete suite specified in TestNG descriptor are run during integration-test phase.

If you want to run only selected tests, use comma-separated list of paths specifing the test cases (you can use wildcards). For example:

$ mvn ... -Dtest=TooltipTestCase
$ mvn ... -Dtest="extendedDataTable/*" (run all of the tests for EDT)
$ mvn ... -Dtest="ActionParameter*,tooltip/*" (run ActionParameterTestCase and all of the tests for Tooltip)
$ mvn ... -Dtest="*Validator*" (run all validator tests)

Selenium configuration

Additional settings which influence selenium configuration defaults:

Maximizing selenium window with tested application

$ mvn ... -Dselenium.maximize=true

Run selenium in debugging mode

This mode allows force to use selenium debug mode and also browser side logging (note: this combination is very verbose):

$ mvn ... -Dselenium.debug=true

Changing host and port of SeleniumServer

By default build uses local selenium (localhost:8444) started in pre-integration-test phase, but you can define other host and/or port too:

$ mvn ... -Dselenium.host=remote.host -Dselenium.port=4444

(note: despite of specifying other host for connecting remote SeleniumServer, the local instance of SeleniumServer is triggered automatically on the specified port ${selenium.port} listening on 0.0.0.0 - but you can turn the local Selenium session off by disabling it's profile: -P '!local-selenium-session')

(note: build automatically prepares JavaScript extensions for SeleniumServer, so it is necessary to copy that extensions from target/test-classes/custom-extensions.js and start designated SeleniumServer with switch -userExtension pointed to that file - the custom-extensions.js are built in process-test-resources phase)

Which richfaces-demo artifact use?

(You may omit following examples if you aren't using Cargo (containerId definition) to deploy richfaces-demo.)

By default, selenium obtains newest snapshot of richfaces-demo from snapshots.jboss.org, but you may want to override version - in that case use one of following methods to specify artifact what you want to be tested:

Specifying release version

$ mvn ... -Ddemo.version=3.3.3.BETA1

But especially when testing release, you may want to specify suitable profile for given container, so let specify classifier of richfaces-demo artifact:

$ mvn ... -DcontainerId=tomcat6x ... -Ddemo.version=3.3.3.BETA1 -Ddemo.classifier=tomcat6

$ mvn ... -DcontainerId=jboss5x ... -Ddemo.version=3.3.3.BETA1 -Ddemo.classifier=jee5

(If you don't define demo.classifier, standard behaviour (no classifier) taken precedence and you should use only JavaEE 5 compatible containers (don't use tomcat6x))

$ mvn ... -DcontainerId=jboss5x ... -Ddemo.version=3.3.3.BETA1 (defaults to -Ddemo.classifier="")

Use local richfaces-demo artifact

If you want use artifact on your local filesystem (specified by location), just use:

$ mvn ... -Ddemo.location=../richfaces-demo.war

or

$ mvn ... -Ddemo.location=$HOME/richfaces-demo-3.3.3-20100104.212113-50.war

This is very usable for:

Application context

You can redefine application context, where application actually resides (defaults to http://localhost:8080/richfaces-demo/) in following way:

$ mvn ... -Dcontext.root=http://some.host/ -Dcontext.path=/deployed/richfaces-demo/

(note: this definition points Selenium where application resides, so the host must be available from host where selenium instance is running)

Use prepared template of Firefox profile

If you already have Firefox's profile prepared for testing (e.g. when you have there installed own extenssions), you may use it as template for Selenium:

$ mvn ... -Dbrowser="*firefox" -DfirefoxProfileTemplate="$HOME/.mozilla/8vykwrsm.default"

(note: don't be scared about using such profile since Selenium makes a working copy of given profile first)

Testing JSF2

It is necessary to use jsf2 definition to run test properly configured for JSF2:

$ mvn ... -Djsf2

(note: that definition implies turning profile jsf2_0 on: -Pjsf2_0)

Configuration by default

All of the definitions above are configured with respect of configuration by default paragidm, so it is possible to achieve different behaviours with varying combinations.

All default values are specified in pom.xml in properties.

Special configurations

Debugging

If you want to use the selenium server or container without running the test suite (e.g. for debugging purposes), you may find the following examples useful:

Run container only

$ mvn verify -DcontainerId=tomcat6x -Dmaven.test.skip=true -P press-key-to-shutdown-server

Run Selenium server only

$ mvn verify -P 'press-key-to-shutdown-server,local-selenim-session,!integration-test,!container-demoapp-deployable-dependency'

Run integration test suite only

If you have already running selenium server and container, you can just run a test suite:

$ mvn verify -Dbrowser="*firefox" -P '!local-selenium-session,!container-demoapp-deployable-dependency'