
== Build and testsuite framework


=== Introduction

The JBossWS project build and testsuites have been completely revisited
in version 5.0.0.Beta3. JBossWS now uses the _Arquillian_
framework to run its integration tests against WildFly containers.

There are two test modules in JBossWS' testsuite, _cxf-tests_ and
_shared-tests_ . Each test module requires at least one _WildFly_
container to run. Multiple containers are used for modules whose tests
can't run at the same time on the same container. By default, containers
are managed (started / stopped) by Arquillian. The JBossWS build system
fetches a copy of the required container from the Maven repository,
unpacks it, patches it installing the current webservices stack on it
and finally hands it over to Arquillian for the testsuite runs. The test
framework also allows Arquillian to manage an already available
container instance on the local filesystem. Finally, it's also possible
to execute single tests against a locally running container
(non-Arquillian managed) and run the tests concurrently.


==== Prerequisites and requirements

* Maven version 3.2.2 or higher is required to build and run the
testsuite.
* A unique class name for each test across the testsuite's three child
modules. Classes may have the same package name across the child modules
but the full-qualified name must be unique to avoid breaking
concurrent tests run.


=== Architecture overview

When the build fetches the Wildfly container from the Maven repository, a
patched copy is placed in the target/test-server sub-directory of
each testsuite module. For instance, you could have:

./modules/testsuite/cxf-tests/target/test-server/jbossws-cxf-dist-5.0.0-SNAPSHOT/wildfly-8.1.0.Final
./modules/testsuite/shared-tests/target/test-server/jbossws-cxf-dist-5.0.0-SNAPSHOT/wildfly-8.1.0.Final

Each container copy is provided with specific standalone mode
configuration files ( _jbws-testsuite-SOME_IDENTIFIER.xml_ ) in the
`standalone/configuration` server directory. The contents of such
descriptors depends on the tests that are to be run against such
container configurations (the most common difference when compared to
the vanilla standalone.xml is the setup of additional security domains,
system properties, web connectors etc.) Each configuration includes
logging setup to ensure logs are written to unique files (
_jbws-testsuite-SOME_IDENFIFIER.log_ ) in `standalone/log` directory.


==== Target Container Identification

JBossWS supports the current WildFly release and several previous versions
for testing. Maven profiles are used to identify
the target container to be used for testing. The naming convention is
_wildflyXYZ_ , for example _wildfly820_ to mean WIldFly 8.2.0.Final.

To run tests against an existing local copy of a WildFly container, the
user must specify the absolute path to the server implementation's home
directory using the command line option, _-Dserver.home=/foo/bar_ . The
server should not be running, as the build will create various
standalone server configurations and start multiple instances on
different port numbers. If only a single test or few tests are to be
executed, the user can have those executed against live WildFly
instances previously started on the same port numbers expected by the
tests. Arquillian is configured to detect such scenario and use the
available server.


==== Port Mapping

To facilitate concurrent testing, a port offset has been defined for each
of the server configurations. The offsets are defined in the
`<properties>` element of the `modules/testsuite/pom.xml` file.


=== Command Line Options

As any other Maven-based project, JBossWS is built as follows:

....
mvn -P[profile] -D[options] [phase]
....


==== Profile

JBossWS uses Maven profiles to declare the target container and other
types of environment setup. Multiple profiles are provided as a comma
separated list of profile names. Only a single target container profile
is allowed at the same time though.

[cols=",",options="header",]
|===
|Profile |Description
|`wildflyXYZ` |Designates the target container to use, where XYZ is
WildFly's three digit version number

|`fast` |Declares the tests are to be run concurrently

|`dist` |Explicitly includes _dist_ module in the build; by default this
is automatically triggered (only) when a `wildflyXYZ` profile is set.

|`testsuite` |Explicitly includes the testsuite modules in the build; by
default this is automatically triggered (only) when a `wildflyXYZ`
profile is set.
|===


==== Options

Below is a list of the available build / test options:

[cols=",",options="header",]
|===
|Option |Description
|server.home |Declares the absolute path to a given local server
instance.

|exclude-udp-tests |Force skipping the UDP tests. This option might be
needed when running on a network that does not allow UDP broadcast.

|noprepare |Skip integration tests preparation phase, which includes
tuning of the server configurations, wsconsume/wsprovide invocations,
etc.

|debug |Turns on Surefire debugging of integration tests only. Debugging
address is 5005.

|jboss.bind.address |Starts the containers bound to the specified
network interface address.

|arquillian.deploymentExportPath |Instructs Arquillian to write the
actual test deployments to disk in the specified module sub-directory.

|test |Runs the test in the specified comma-separated list of JUnit
classes

|maven.surefire.debug |Turns on Surefire debugging in any module
including tests.
|===


==== Examples

Build the project, deploy the WS stack to a local copy of WildFly
8.2.0.Final and run the testsuite:

....
mvn -Pwildfly820 -Dserver.home=/foo/wildfly-8.2.0.Final integration-test
....

Use _WildFly 8.1.0.Final_ as the target container (letting the build
fetch it), patch it with current WS stack and run only test
_MtomTestCase_ that is located in the _cxf-test_ module:

....
mvn -Pwildfly810 integration-test -Dtest="org/jboss/test/ws/jaxws/samples/MtomTestCase"
....

Build, deploy, then run the tests concurrently. Run till Maven
post-integration-test phase to trigger test servers shutdown and save
memory at the end of each testsuite module:

....
mvn -Pfast,wildfly810 post-integration-test
....

Clean the project:

....
mvn -Pdist,testsuite clean
....

Build the WS stack and install it on a specified server instance without
running the integration testsuite:

....
mvn -Pwildfly900 -Dserver.home=/foo/wildfly-9.0.0.Alpha2-SNAPSHOT package
....

When a server.home option is not provided, the build creates a zip
archive with a vanilla WildFly server patched with the current WS stack:
the zip file path is modules/dist/target/jbossws-cxf-dist-$\{
*project.version}* -wildflyXYZ.zip

....
mvn -Pwildfly810 package
....


=== Container remote debugging

While debugging a testcase is simply a matter of providing the
-Ddebug option, remote debugging the container code that runs the WS
stack requires few additional setup steps. The suggested approach is to
identify a single test to run; before actually running the test,
manually start a target container in debug mode and specifying the
proper port offset and server configuration (have a look at the
arquillian.xml decriptors in the testsuite), then run the tests with
-Dserver.home=... option pointing to the home dir for the server
currently running.
