| = TomEE and Arquillian |
| :jbake-date: 2016-03-16 |
| :jbake-type: page |
| :jbake-status: published |
| :jbake-tomeepdf: |
| |
| TomEE has several arquillian adapter flavors: |
| |
| - openejb-embedded: a plain embedded OpenEJB supporting most of EE features |
| - tomee-embedded: a full TomEE running in the same JVM |
| - tomee-remote: a standard TomEE running in its own process as in production |
| - tomee-webapp (not recommanded): an adapter starting from a Tomcat and installing tomee-webapp |
| |
| === Embedded or Remote? |
| |
| Big advantage of embedded adapters is to be able to debug as usual. However it has few drawbacks which can make you |
| rething this choice: |
| |
| - JVM resources are available where it will likely not be the case in war mode (src/main/resources typically) |
| - You can mix server and client side features when writing a test |
| - Classloading is a bit different by design and less isolated (test dependencies) so you can get runtime surprises when really deploying |
| |
| To summarize: the choice is the trade off you choose between easiness and reality of the simulation. |
| |
| TIP: in TomEE build we build the same tests against all tomee adapters in the same build/module, this means you can use embedded adapter in dev |
| and activate remote tomee too (not only cause then if there is a failure you don't know if you missed it locally or if it is due |
| to the switch of adapter) on your continuous integration platform. |
| |
| NOTE: all configurations have defaults |
| |
| === OpenEJB Embedded |
| |
| ==== Coordinates |
| |
| [source,xml] |
| ---- |
| <dependency> |
| <groupId>org.apache.tomee</groupId> |
| <artifactId>arquillian-openejb-embedded</artifactId> |
| <version>${tomee7.version} |
| </dependency> |
| ---- |
| |
| ==== arquillian.xml |
| |
| |=== |
| |Name|Description |
| |properties|container properties, as in conf/system.properties (not in xml format) |
| |preloadClasses|some class to load (ie enforce static block initialization) |
| |startDefaultScopes|should CDI default scopes be started (includes @RequestScoped) |
| |singleDeploymentByArchiveName |names of archives (or true for all) to dploy a single time |
| |=== |
| |
| Sample: |
| |
| [source,xml] |
| ---- |
| <?xml version="1.0" encoding="UTF-8" standalone="yes"?> |
| <arquillian |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://jboss.org/schema/arquillian http://jboss.org/schema/arquillian/arquillian_1_0.xsd"> |
| <container qualifier="openejb" default="true"> |
| <configuration> |
| <property name="properties"> |
| # used to not have a single DataSource and be able to test the resource resolution |
| db1 = new://Resource?type=DataSource |
| db1.JdbcUrl = jdbc:hsqldb:mem:db1 |
| |
| # will preload both classes, simple comma separated qualified names work too |
| openejb.arquillian.predeploy-archives = org.company.openejb.arquillian.openejb.archive.[SimpleArchive|SimpleArchive2] |
| </property> |
| </configuration> |
| </container> |
| </arquillian> |
| ---- |
| |
| === TomEE Embedded |
| |
| ==== Coordinates |
| |
| [source,xml] |
| ---- |
| <dependency> |
| <groupId>org.apache.tomee</groupId> |
| <artifactId>arquillian-tomee-embedded</artifactId> |
| <version>${tomee7.version} |
| </dependency> |
| ---- |
| |
| ==== Configuration |
| |
| |=== |
| |Name|Description |
| | exportConfAsSystemProperty|export system properties with adapter prefix(es) (ex: httpPort will be set as tomee.httpPort) |
| | httpsPort | the HTTPS port |
| | httpPort | the HTTP port |
| | stopPort | the shutdown port |
| | dir | where to create the TomEE work dir (a fake file layout is created for Tomcat needs) |
| | appWorkingDir | where to dump applications (`@Deployment`) |
| | host | which host to use |
| | stopHost | which port to use to shutdown TomEE (port on Server configuration) |
| | stopCommand | which command to use to shutdown TomEE |
| | serverXml | where is the provided server.xml |
| | portRange | when port are set to -1 TomEE adapter will generate an available port, if specified the range will be used |
| | preloadClasses | which classes to initialize during container startup |
| | quickSession | should the session use a Random instead of SecureRandom (useful when the machine doesn't have a lot of entropy) |
| | unsafeEjbd | should EJB allow all classes |
| | unpackWars | unpackWARs value in server.xml |
| | properties | container properties |
| | webContextToUseWithEars |sometimes you can need this to adjust which context the adapter uses to find the ArquillianServletRunner |
| | keepServerXmlAsThis |don't replace ports etc in server.xml and use it like it has been provided when serverXml is set |
| | singleDumpByArchiveName | dump only once `@Deployment` archives using the name as key |
| | singleDeploymentByArchiveName |deploy only once `@Deployment` archives using the name as key |
| |ssl| should https be activated |
| |withEjbRemote| should EJBd remote be activated |
| |keystoreFile | if ssl is set to true the keystore location |
| |keystorePass | if ssl is set to true the keystore password |
| |keystoreType | if ssl is set to true the keystore type |
| |clientAuth |should SSL connector use clientAuth |
| |keyAlias | if ssl is set to true the key to use |
| |sslProtocol | if ssl is set to true the protocol to use |
| |users |a map of users (properties syntax) |
| |roles |user roles (properties syntax) |
| |webResourcesCached |should resources be cached or not (`DefaultServlet` caching) |
| |=== |
| |
| |
| Sample: |
| |
| [source,xml] |
| ---- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <arquillian |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation=" |
| http://jboss.org/schema/arquillian |
| http://jboss.org/schema/arquillian/arquillian_1_0.xsd"> |
| <container qualifier="tomee" default="true"> |
| <configuration> |
| <property name="serverXml">conf/server.xml</property> |
| |
| <!-- port = -1 means random --> |
| <property name="httpPort">-1</property> |
| <property name="stopPort">-1</property> |
| |
| <!-- ssl --> |
| <property name="httpsPort">-1</property> |
| <property name="ssl">false</property> |
| <property name="keystoreFile">keystore-path</property> |
| <property name="keystorePass">changeit</property> |
| <property name="keystoreType">JKS</property> |
| <property name="clientAuth">false</property> |
| <property name="keyAlias">alias</property> |
| <property name="sslProtocol">protocol</property> |
| |
| <!-- where to create TomEE files --> |
| <property name="dir">target/tomee-embedded</property> |
| |
| <!-- where to dump on disk applications to deploy --> |
| <property name="appWorkingDir">target/working-dir</property> |
| |
| <!-- optional - limit the port allowed when random --> |
| <property name="portRange">20001-30000</property> |
| |
| <!-- container config --> |
| <property name="properties"> |
| # same as embedded case |
| </property> |
| |
| <!-- Deployer config --> |
| <property name="deployerProperties"> |
| # openejb.deployer.binaries.use=true |
| # openejb.deployer.forced.appId=[name] |
| # openejb.deployer.save-deployments=false |
| </property> |
| </configuration> |
| </container> |
| </arquillian> |
| ---- |
| |
| === TomEE Remote |
| |
| IMPORTANT: if a server is already started on host:port then it will be used instead of starting the configured TomEE type. |
| |
| To use a custom instance with arquillian ensure to have ejbd and tomee webapp activated. A way is to have in `conf/system.properties` these entries: |
| |
| [source] |
| ---- |
| tomee.remote.support=true |
| openejb.system.apps=true |
| |
| # you can customize it depending the security level you need on the instance |
| tomee.serialization.class.whitelist = |
| tomee.serialization.class.blacklist = org.codehaus.groovy.runtime.,org.apache.commons.collections.functors.,org.apache.xalan,java.lang.Process |
| ---- |
| |
| For really remote instances (= not on localhost) you need the `deployerProperties` of previous snippet too: |
| |
| [source,xml] |
| ---- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <arquillian |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation=" |
| http://jboss.org/schema/arquillian |
| http://jboss.org/schema/arquillian/arquillian_1_0.xsd"> |
| <container qualifier="tomee" default="true"> |
| <configuration> |
| <!-- ... --> |
| <property name="deployerProperties"> |
| openejb.deployer.binaries.use=true |
| openejb.deployer.save-deployments=false |
| </property> |
| </configuration> |
| </container> |
| </arquillian> |
| ---- |
| |
| ==== Coordinates |
| |
| [source,xml] |
| ---- |
| <dependency> |
| <groupId>org.apache.tomee</groupId> |
| <artifactId>arquillian-tomee-remote</artifactId> |
| <version>${tomee7.version} |
| </dependency> |
| ---- |
| |
| ==== Configuration |
| |
| |=== |
| |Name|Description |
| | exportConfAsSystemProperty|export system properties with adapter prefix(es) (ex: httpPort will be set as tomee.httpPort) |
| | httpsPort | the HTTPS port |
| | httpPort | the HTTP port |
| | stopPort | the shutdown port |
| | dir | where to create the TomEE work dir (a fake file layout is created for Tomcat needs) |
| | appWorkingDir | where to dump applications (`@Deployment`) |
| | host | which host to use |
| | stopHost | which port to use to shutdown TomEE (port on Server configuration) |
| | stopCommand | which command to use to shutdown TomEE |
| | serverXml | where is the provided server.xml |
| | portRange | when port are set to -1 TomEE adapter will generate an available port, if specified the range will be used |
| | preloadClasses | which classes to initialize during container startup |
| | quickSession | should the session use a Random instead of SecureRandom (useful when the machine doesn't have a lot of entropy) |
| | unsafeEjbd | should EJB allow all classes |
| | unpackWars | unpackWARs value in server.xml |
| | properties | container properties |
| | webContextToUseWithEars |sometimes you can need this to adjust which context the adapter uses to find the ArquillianServletRunner |
| | keepServerXmlAsThis |don't replace ports etc in server.xml and use it like it has been provided when serverXml is set |
| | singleDumpByArchiveName | dump only once `@Deployment` archives using the name as key |
| | singleDeploymentByArchiveName |deploy only once `@Deployment` archives using the name as key |
| |groupId|the maven groupId of the TomEE (or not) artifact |
| |artifactId|the maven artifactId of the TomEE (or not) artifact |
| |version |the maven version of the TomEE (or not) artifact |
| |classifier |the maven classifier of the TomEE (or not) artifact |
| |type |the maven type of the TomEE (or not) artifact (should be zip) |
| |removeUnusedWebapps |should default webapps (ROOT, manager, ...) be removed |
| |ajpPort |the ajp port if used |
| |conf |a folder to synchronize with TomEE conf folder |
| |bin |a folder to synchronize with TomEE bin folder |
| |lib |a folder to synchronize with TomEE lib folder |
| |endorsed |a folder to synchronize with TomEE endorsed folder |
| |javaagent |a list (flat format) of javaagent to add when launching tomee, can use maven coordinates if prefixed with `mvn:` |
| |additionalLibs |a list (flat format) of library to add to TomEE libraries, can use paths of maven coordinates when prefixed with `mvn:` |
| |cleanOnStartUp |should TomEE folder be deleted on startup if exists |
| |debug |should the container run in debug mode (`-Dopenejb.server.debug=true` activates it without touching the configuration) |
| |debugPort |if activated which port to use to debug |
| |catalina_opts |equivalent to `CATALINA_OPTS` environment variable |
| |simple_log |should logs be inline |
| |deployerProperties |deployer properties, useful when not deploying on an instance managed by the build (remote instance typically) |
| |=== |
| |
| |
| Sample: |
| |
| [source,xml] |
| ---- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <arquillian |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation=" |
| http://jboss.org/schema/arquillian |
| http://jboss.org/schema/arquillian/arquillian_1_0.xsd"> |
| <container qualifier="tomee" default="true"> |
| <configuration> |
| <property name="serverXml">conf/server.xml</property> |
| |
| <!-- tomee zip to use --> |
| <property name="groupId">org.apache.tomee</property> |
| <property name="artifactId">apache-tomee</property> |
| <property name="version">LATEST</property> |
| <property name="type">zip</property> |
| |
| <!-- tomee provided files, ignored by default --> |
| <property name="bin">src/test/tomee/bin</property> |
| <property name="conf">src/test/tomee/conf</property> |
| <property name="lib">src/test/tomee/lib</property> |
| |
| <!-- |
| remote debugging, |
| -Dopenejb.server.debug can activate it too |
| --> |
| <property name="debug">false</property> |
| <property name="debugPort">5005</property> |
| |
| <!-- nice one line logging --> |
| <property name="simpleLog">true</property> |
| |
| <!-- jvm config --> |
| <property name="catalina_opts">-XX:-UseParallelGC</property> |
| |
| <!-- remove if exist --> |
| <property name="cleanOnStartUp">true</property> |
| |
| <!-- remove default webapps --> |
| <property name="removeunusedWebapps">true</property> |
| |
| <!-- port = -1 means random --> |
| <property name="httpPort">-1</property> |
| <property name="stopPort">-1</property> |
| |
| <!-- where to create TomEE --> |
| <property name="dir">target/apache-tomee</property> |
| |
| <!-- where to dump on disk applications to deploy --> |
| <property name="appWorkingDir">target/working-dir</property> |
| |
| <!-- optional - limit the port allowed when random --> |
| <property name="portRange">20001-30000</property> |
| |
| <!-- container config --> |
| <property name="properties"> |
| # same as embedded case |
| </property> |
| |
| <!-- we monitor the test with sirona --> |
| <property name="javaagent"> |
| mvn:org.apache.sirona:sirona-javaagent:0.2-incubating:jar:shaded |
| </property> |
| |
| <!-- Deployer config --> |
| <property name="deployerProperties"> |
| # openejb.deployer.binaries.use=true |
| # openejb.deployer.forced.appId=[name] |
| # openejb.deployer.save-deployments=false |
| </property> |
| |
| </configuration> |
| </container> |
| </arquillian> |
| ---- |
| |
| === Multiple instances |
| |
| With arquillian you can create cluster or isolated instances. Here is a sample `arquillian.xml`: |
| |
| [source,xml] |
| ---- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <arquillian xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation=" |
| http://jboss.org/schema/arquillian |
| http://jboss.org/schema/arquillian/arquillian_1_0.xsd"> |
| <group qualifier="tomee-cluster"> |
| <container qualifier="tomee-1"> |
| <configuration> |
| <property name="httpPort">-1</property> |
| <property name="stopPort">-1</property> |
| <property name="ajpPort">-1</property> |
| <property name="dir">target/tomee1</property> |
| <property name="appWorkingDir">target/wd1</property> |
| </configuration> |
| </container> |
| <container qualifier="tomee-2"> |
| <configuration> |
| <property name="httpPort">-1</property> |
| <property name="stopPort">-1</property> |
| <property name="ajpPort">-1</property> |
| <property name="dir">target/tomee2</property> |
| <property name="appWorkingDir">target/wd2</property> |
| </configuration> |
| </container> |
| </group> |
| </arquillian> |
| ---- |
| |
| Then in your test just specify the container you are testing against: |
| |
| [source,java] |
| ---- |
| @RunWith(Arquillian.class) |
| public class MultipleTomEETest { |
| @Deployment(name = "war1", testable = false) |
| @TargetsContainer("tomee-1") |
| public static WebArchive war1() { |
| return /* ... */; |
| } |
| |
| @Deployment(name = "war2", testable = false) |
| @TargetsContainer("tomee-2") |
| public static WebArchive war2() { |
| return /* ... */; |
| } |
| |
| @Test |
| @OperateOnDeployment("war1") |
| public void testRunningInDep1( |
| @ArquillianResource URL url) { |
| // test on tomee 1, url is contextual |
| } |
| |
| @Test |
| @OperateOnDeployment("war2") |
| public void testRunningInDep1( |
| @ArquillianResource URL url) { |
| // test on tomee 1, url is contextual |
| } |
| } |
| ---- |