# 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:

- tomcat6x
- jboss5x (can be use to run inside JBoss AS 6.X too)

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:

- locally built or modified artifacts
- testing snapshots other than the latest

### 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'