Monday, June 09, 2014

Java EE7 and Maven project for newbies - part 5 - Unit testing using Arquillian / Wildfly 8 #maven #jboss #wildfly #arquillian


    This is the first 'extra' post, based on the  maven JavaEE7 demo project I am 'building' on this series of blog posts. We have already defined a solid structure and some modules. One very common case in an application like this, is to use Arquillian (+JUnit), a god sent framework, that enable us to unit test our EJB services using a 'real' application server, most probably the same that we are going to deploy to. I am actually following the basic setup guide as it can be found here, the difference is that I am going to setup Wildfly 8.1 as my embedded container to host my unit tests. Widlfy 8.1 is a fully blown JavvaEE7 container, so I can safely test all my features.



    Arquillian mind set and Maven

    One of the basic things you need to understand in order to adopt Arquillian in your Maven-ized project is the following  terms (ideas) that are actually implemented as dependencies.
    • You need the Arquillian framework/library of course, imagine that it is a new car but is missing it's engine. The front part it's empty.
    • You need an Arquillian Container Adapter, imagine that you need to install some kind of placeholders in the front part of your car, something like a frame that is going to be used so that an engine can be 'installed'.
    • You need a real container (application server), this is the engine that we are going to fit into our car.
    • You need JUnit, this is the 'test track' that your car is going to run and be tested.
    • You need your code (your EJB(s)), these are the passengers that are going to be placed in the car and test a ride on the Junit track.



    Defining the dependencies on the parent pom

    As we have already elaborated in the previous 4 posts, the parent pom is the place to define the dependencies and their versions of libraries to be used in our application.  Have in mind the above list of terms let's get started and update the dependencyManagement section  of our parent pom.

    Some tips on the above fragment:
    • Some of the dependencies are of type pom, and scope import. This is actually a special case on defining group of dependencies all together. A pom type dependency, means that this is a group of individual libraries grouped together under this definition. You only need to define this uber pom  and you will inherit the individual dependencies within it. In the Maven terminology this grouping of dependencies are called 'BOM' or also known as Bill of Materials. Arquillian is consisted of several concrete libraries and dependencies, instead of defining each one of the, one by one, we have the same result if we define the arquillian-bom.
    • The 'arquillian-transaction-bom' is an optional dependency, you may not define it, it adds extra features to the arquillian engine and in your tests. One of the most famous 'extra' features is the '@Transactional' arquillian annotation. See details here or here.
    • A special case, for Wildfly and JBoss. You will notice the dependency, 'wildfly-embedded', you will assume that this is a 'embedded' uber jar version of the Wildfly application server, like the one for Glassfish. Eventually this is not, and this is a common mistake that people make when trying to setup Arquillian with Wildfly. In order to make the whole thing work you need to download the 'real' application server. Have a look on the following section, where will will tackle this special case.



    Configuring our ejb module for Arquillian and tests

    In our demo applications we have 'coded' most of our EJB services on the module called sample-ejb. So we need to add extra configuration to it's pom in order to 'fire'  junit+arquillian tests during the test phase of this module.

    Most of the configuration will do on this pom, is to cover this 'special' case of Widlfly not being offered as a fully blown embedded container. So in order to make the whole mechanism work we need, to tell Maven, during our test phase, to download the (as we would do using a browser for example) unzip it somewhere, and the point Arquillian to the path. Once that is done, rAquillian will take over.


    Downloading the wildfly server, before hand

    The configuration below is written in the sample-services pom, our 'EJB services' module

    Some tips on the above fragment:
    • We use the maven-dependency-plugin
    • We instruct the plugin to kick in during the 'process-test-classes' phase of the Maven lifecycle, and when it kicks in to execute the 'unpack' goal. So before Maven starts running the tests the above part of the configuration will have downloaded and unpacked Wildfly 8.1 to the class path.

     Running the tests, using maven - surfire plugin

    Again the code below is part of the sample-services.pom. We actually configure Maven Surefire Plugin, which is the plugin that executes the Junit-Arquilian tests.

    Some tips on the above fragment:
    • Surefire provides the execution environment for the unit tests. In our case we have Junit-Arquillian powered tests. In order Arquillian to correctly initialize itself and to identify the container we need to pass as system parameters, the path of the download application server. Remember that wildfly / jboss is a special case.  The container will already be downloaded on out /target folder. 

    Add the required dependencies on the sample-services module

     Create a sample Test

    We are done

    Under the sample-parent folder level, type

    mvn clean package

    The complete code for this example can be found on the following bitbucket tag.

    Move on to Part 6?


    1. What about UserServices?
      Where is that class definition?

      1. It is actually added in the 'temp' deployment jar we add create on the createDeployment method, is being added automatically by Arquillian, since it is part of our project/depedency


    2. Do you have some example using wildfly-arquillian-container-managed?

      1. No, it really depends which version you are looking for.