Kabir Khan [
http://community.jboss.org/people/kabirkhan] modified the document:
"JBoss Modules Surefire Plugin"
To view the document, visit:
http://community.jboss.org/docs/DOC-16240
--------------------------------------------------------------
This is a fork of org.apache.maven.plugins:maven-surefire-plugin:2.6:test which allows you
to run tests using modular classloading provided by jboss-modules. The source for this
plugin is available in github (
https://github.com/kabir/jboss-modules-surefire-plugin
https://github.com/kabir/jboss-modules-surefire-plugin).
It works by suppying it with a prebuilt modules root (such as the one from a built JBoss
AS 7) and a module definition file to define more modules for your test. The plugin will
then create an additional modules directory from the module definition file, and then
invoke org.jboss.modules.Main using the configured modules directories. Since everything
is now run via jboss modules, you should not execute tests directly from your IDE, but
rather run them via maven. If you want to debug the tests, do a
mvn install -Dmaven.surefire.debug=true
and attach a debugger to port 5005.
h4. Configuration
It has the configuration options of the 'real' surefire plugin (
http://maven.apache.org/plugins/maven-surefire-plugin/test-mojo.html
http://maven.apache.org/plugins/maven-surefire-plugin/test-mojo.html), although your
mileage may vary if you start playing with the fork modes. The plugin takes a module
definition file and creates a directory structure containing modules in the jboss-modules
format
It has the configuration options of the
http://maven.apache.org/plugins/maven-surefire-plugin/test-mojo.html original surefire
plugin, although your mileage may vary if you start playing with the fork modes. The
plugin takes a module definition file and creates a directory structure containing modules
in the jboss-modules format.
For the forked module there are some more options for configuring the modules:
*roots:*
Points to a list of exisiting module root directories, such as jboss-as7/modules
* *Type:* java.io.File[]
* *Required:* No
*cleanModulesDirectory:*
If true (default) clean out the modules directory created by the plugin each time we run
the tests.
* *Type:* boolean
* *Required:* No
* *Expression:* ${jboss.modules.clean}
* *Default:* true
*modulesDirectory:*
The absolute path of the modules output directory created from +*moduleDefinitionFile*+
* *Type:* java.io.File
* *Required:* No
* *Expression:* ${jboss.modules.directory}
* *Default:* ${project.build.directory}/modules
*logModule:*
The name of the -logmodule parameter passed in to JBoss Modules (i.e. the name of the
module containg the jboss logmanager). This is needed if the target project uses
java.util.Logging or jboss logging, and the jboss log manager is not on the system
classpath.
* *Type:* java.lang.String
* *Required:* No
* *Expression:* ${jboss.modules.logmodule}
*logConfiguration:*
The JBoss logging configuration if any. This must be set if the target project uses jboss
logging and you want any output to be displayed
* *Type:* java.io.File
* *Required:* No
* *Expression:* ${logging.configuration}
*moduleDefinitionFile:*
The path of the module definition file.
* Type java.io.File
* Required: Yes
* Expression: ${jboss.modules.definition}
* Default: ${project.build.testOutputDirectory}/modules/module-def.xml
In addition, when using jboss logging you will need to set the following system properties
in your pom when using this plugin (full example later):
<systemProperties>
<property>
<name>java.util.logging.manager</name>
<value>org.jboss.logmanager.LogManager</value>
</property>
<property>
<name>jboss.home.dir</name>
<value>${jboss.home}</value>
</property>
<property>
<name>org.jboss.boot.log.file</name>
<value>${jboss.home}/standalone/log/boot.log</value>
</property>
</systemProperties>
*h4. Module Definition File
*
This sets up the modules used for running your tests, which are then copied to
*+modulesDirectory+* from the plugin settings. The plugin automatically sets up a module
called +jboss.surefire.module+ for you which contains the plugin classes. This module is
then used as the module passed in to org.jboss.modules.Main. If you want to set up more
modules you can define those in the *+moduleDefinitionFile+*. The schema is very simple,
and rather than duplicating the work done by jboss-modules the validation of most of the
stuff is delegated to jboss-modules when loading the modules. Here is an example:
<?xml version="1.0" encoding="UTF-8"?>
<modules xmlns="urn:jboss:surefire-module:1.0"
targetNs="urn:jboss:module:1.0">
<test-module-resources>
<resource-root path="$junit:junit$"/>
<resource-root path="$$CLASSES$$"/>
<resource-root path="$$TEST.CLASSES$$"/>
</test-module-resources>
</test-module-dependencies>
<module name="org.jboss.as.standalone"/>
<module name="org.jboss.modules"/>
<module name="org.jboss.threads"/>
<module name="my.test.module"/>
</test-module-dependencies>
<module name="my.test.module">
<resources>
<resource-root path="$some.group:some-artifact$"/>
</resources>
</module>
</modules>
+targetNs+ is the schema of the targetted jboss-modules version.
+test-module-resources+ adds the listed resources directly into the resources section of
the created +jboss.surefire.module+ module.
+test-module-dependencies+ adds the listed dependencies directly into the dependencies
section of the created +jboss.surefire.module+ module. In this case we follow the
jboss-modules 1.0 schema. The resource root paths containing '$' get expanded as
shown in this example of what the generated
+modulesDirectory+/jboss/surefire/module/main/module.xml looks like:
<?xml version="1.0" encoding="UTF-8"?>
<module name="jboss.surefire.module"
xmlns="urn:jboss:module:1.0">
<main-class name="org.apache.maven.surefire.booter.SurefireBooter"/>
<resources>
<!-- These two always get included -->
<resource-root path="surefire-api-2.6.jar"/>
<resource-root path="surefire-booter-1.0.0.Alpha1.jar"/>
<!-- The maven dependency $junit.junit$ gets pulled from the maven repository
using the version from your project dependencies
-->
<resource-root path="junit-4.8.1.jar"/>
<!-- $$CLASSES$$ uses the main classes directory from your project -->
<resource-root path="classes"/>
<!-- $$TEST.CLASSES$$ uses the test classes directory from your project -->
<resource-root path="test-classes"/>
</resources>
<dependencies>
<module name="org.jboss.as.standalone"/>
<module name="org.jboss.modules"/>
<module name="org.jboss.threads"/>
<module name="org.jboss.threads"/>
</dependencies>
</module>
You can have as many +modules/module entries as you like and they just get copied across.
The $some.group:some.artifact$+ value gets resolved from your project's dependencies
into the path to that dependency in your local maven repository. In this case (assuming
your pom has a dependency on some.group:some-artifact:1.3.0, which then gets copied from
the local maven repository to the module directory)
+modulesDirectory+/my/test/module/main/module.xml looks like:
<?xml version="1.0" encoding="UTF-8"?>
<module name="my.test.module" xmlns="urn:jboss:module:1.0">
<resources>
<resource-root path="some-artifact-1.3.0.jar'/>
</resources>
</module>
To summarize, you have the following options to set the resource-root paths.
* Full path: Nothing special happens in this case, the module will simply point to that
place
* $$CLASSES$$: Copies the main classes directory from your project to the created module
* $$TEST.CLASSES$$: Copies the test classes directory from your project to the created
module
* $maven.group.id*:*maven.artifact.id$: Resolves the maven dependency from your project
dependencies and copies the jar to the created module
h4. Consuming the plugin from a pom
Normally you want to turn off the normal surefire plugin since that does not understand
modular classloading
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.6</version>
<!-- Disable the standard surefire plugin since that runs tests without
modular classloading -->
<configuration>
<skipTests>true</skipTests>
</configuration>
</plugin>
Then enable and configure the jboss modules surefire plugin (${jboss.home} is configured
elsewhere in the pom and points to a built JBoss AS 7 instance)
<plugin>
<groupId>org.jboss.maven.surefire.modular</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>1.0.0.Alpha1</version>
<executions>
<execution>
<goals>
<goal>test</goal>
</goals>
</execution>
</executions>
<configuration>
<!-- standard surefire options -->
<redirectTestOutputToFile>true</redirectTestOutputToFile>
<enableAssertions>true</enableAssertions>
<systemProperties>
<property>
<!-- We need to enable the log manager for jboss as -->
<name>java.util.logging.manager</name>
<value>org.jboss.logmanager.LogManager</value>
</property>
<property>
<!-- The root of the jboss installation -->
<name>jboss.home.dir</name>
<value>${jboss.home}</value>
</property>
<property>
<!-- Set the boot log location -->
<name>org.jboss.boot.log.file</name>
<value>${jboss.home}/standalone/log/boot.log</value>
</property>
<!-- If using EmbeddedServerFactory to create the AS instance
(used by the
arquillian container) set a directory to copy across the
${jboss.home}/standalone directory to, to avoid pollution of
standalone.xml
between runs
--> <property>
<name>jboss.embedded.root</name>
<value>target/temp-config</value>
</property>
</systemProperties>
<includes>
<include>org/jboss/as/test/surefire/**/*TestCase.java</include>
</includes>
<!-- Extra forked plugin options -->
<logModule>org.jboss.logmanager</logModule>
<logConfiguration>${jboss.home}/standalone/configuration/logging.properties</logConfiguration>
<roots>
<root>${jboss.home}/modules</root>
</roots>
</configuration>
</plugin>
h4. Running Arquillian Tests
The plugin can be used to run arquillian tests against an embedded AS 7 instance using
modular classloading everywhere at runtime.
If running an Arquillian IN_CONTAINER test, Arquillian will first execute parts of the
test on the client side to create the deployments, before starting an embedded AS instance
and deploying the tests into the started server. The test is then run in the server as
part of the deployment.
If running an Arquillian AS_CLIENT test, Arquiilian will start the embedded AS instance
and then run the test on the client to connect to the started AS instance.
Since the tests are now booted up using JBoss Modules, there is no runtime classpath to
speak of, so you need to set up your modules to be able to see the arquillian classes and
to be able to see the test class and the dependencies for what is executed on the client
(the parts of the test run inside the server don't need anything special since that is
handled for us by the server). Here is an example of a module definition file for running
an Arquillian test:
<?xml version="1.0" encoding="UTF-8"?>
<modules xmlns="urn:jboss:surefire-module:1.0"
targetNs="urn:jboss:module:1.0">
<test-module-resources>
<resource-root
path="$org.jboss.as:jboss-as-arquillian-container-embedded$"/>
<resource-root
path="$org.jboss.as:jboss-as-arquillian-container-common$"/>
<resource-root path="$$TEST.CLASSES$$"/>
</test-module-resources>
<test-module-dependencies>
<!-- Arquillian dependencies -->
<module services="import"
name="org.jboss.surefire.arquillian-deps"/>
<!-- Add other test dependencies here -->
</test-module-dependencies>
<!-- Add more test modules as needed -->
</modules>
org.jboss.surefire.arquillian-deps is a module that ships with JBoss AS 7, and contains
the dependencies needed for arquillian. It can be found
https://github.com/jbossas/jboss-as/blob/master/build/src/main/resources/...
here. In addition, the test module in this example contains the project test classes
directories, and it adds the resource roots containing the JBoss AS 7 embedded Arquillian
container and the common Arquillian container classes. Including these container classes
makes Arquillian start up the embedded AS 7 container.
h4. TBD
* Investigate if surefire report works with this or if that needs forking too
--------------------------------------------------------------
Comment by going to Community
[
http://community.jboss.org/docs/DOC-16240]
Create a new document in JBoss AS7 Development at Community
[
http://community.jboss.org/choose-container!input.jspa?contentType=102&am...]