Functional test uses Maven and TestNG to run integration tests, which consist of automated browser testing using Selenium web application testing system.
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.
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
All of the tests forms suite and they are enumerated in TestNG descriptor src/test/resources/testng.xml.
By default selenium local instance of SeleniumServer logs to file target/selenium/selenium-server.log.
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).
Recommended: Maven 2.1.0, SunJDK 1.6.0_16
Requires locally built selenium-testing-lib library (obtain it from SVN repository)
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:
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)
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:
Additional settings which influence selenium configuration defaults:
$ mvn ... -Dselenium.maximize=true
This mode allows force to use selenium debug mode and also browser side logging (note: this combination is very verbose):
$ mvn ... -Dselenium.debug=true
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)
(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:
$ 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="")
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:
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)
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)
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)
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.
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:
$ mvn verify -DcontainerId=tomcat6x -Dmaven.test.skip=true -P press-key-to-shutdown-server
$ mvn verify -P 'press-key-to-shutdown-server,local-selenim-session,!integration-test,!container-demoapp-deployable-dependency'
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'