How to Test Applications with Payara® Server & Micro with Arquillian

Published on 12 Apr 2018

Photo of Andrew Pielage by Andrew Pielage

Before putting any application out for public access, it’s always worth testing that it works how you expect it to (and also how you don’t expect it to!). Effective testing of applications is something you can spend a week being taught, but for this blog I’ll just cover the basics of running JUnit and TestNG tests against Payara® Server & Micro using Arquillian.

 

Arquillian is a testing platform that can be used to perform unit, functional, and integration tests of applications being deployed to Java Application Servers. You can find more information on what it can be used for on their website here.

 

Setting Up

Arquillian is probably easiest to integrate into your projects using Maven, a build dependency tool used in many projects – Payara Server included!

In your Maven POM, include the following dependencies, excluding the JUnit or TestNG dependency as per your preference or requirements:

 

<dependencyManagement>

    ...

    <dependencies>

        ...

        <dependency>

            <groupId>org.jboss.arquillian</groupId>

            <artifactId>arquillian-bom</artifactId>

            <version>1.1.14.Final</version>

            <type>pom</type>

            <scope>import</scope>

        </dependency>

        ...

    </dependencies>

    ...

</dependencyManagement>

 

<dependencies>

    <!-- Junit -->

    <dependency>

        <groupId>org.jboss.arquillian.junit</groupId>

        <artifactId>arquillian-junit-container</artifactId>

        <scope>test</scope>

    </dependency>

    <dependency>

        <groupId>junit</groupId>

        <artifactId>junit</artifactId>

        <version>4.12</version>

        <scope>test</scope>

    </dependency>

    ...

    <!-- TestNG -->

    <dependency>

        <groupId>org.jboss.arquillian.testng</groupId>

        <artifactId>arquillian-testng-container</artifactId>

        <scope>test</scope>

    </dependency>

    <dependency>

        <groupId>org.testng</groupId>

        <artifactId>testng</artifactId>

        <version>6.9.10</version>

        <scope>test</scope>

    </dependency>

    ...

</dependencies>

  

The last thing to set up is your container, namely Payara Server or Micro. Four options present themselves to you here:

  • Embedded - Manages the lifecycle of an embedded container (runs in the same JVM as the test runner). Embedded containers are usually opted for faster test suites due to their simplicity of management.
<dependency>

    <groupId>fish.payara.arquillian</groupId>

    <artifactId>arquillian-payara-server-4-embedded</artifactId>

    <version>1.0.Beta3</version>

    <scope>test</scope>

</dependency>

<dependency>

    <groupId>fish.payara.extras</groupId>

    <artifactId>payara-embedded-all</artifactId>

    <version>5.181</version>

    <scope>test</scope>

</dependency>
  • Server Managed - Manages the lifecycle of a local installation of the container/server. This means that the full application server is used to run the tests, so this might impact on the footprint of the suite, including the time to start/stop the container. Typically used if you want to test against a full Payara Server instance but want everything to be managed by Maven (so you don’t have to set up an instance separately). Given that the container is managed by Maven, you can’t just drop-in the dependency and be good to go; you need to configure how Maven will find and use a Payara Server installation.
<dependency>

    <groupId>fish.payara.arquillian</groupId>

    <artifactId>arquillian-payara-server-4-managed</artifactId>

    <version>1.0.Beta3</version>

    <scope>test</scope>

</dependency>

     

  • Micro Managed - Similar to Server Managed, except uses a Payara Micro instance instead of a Payara Server one. Just as with the Server Managed container, this isn’t a simple drop-in and play container, requiring you to perform some additional configuration.
<dependency>

    <groupId>fish.payara.arquillian</groupId>

    <artifactId>arquillian-payara-micro-5-managed</artifactId>

    <version>1.0.Beta3</version>

    <scope>test</scope>

</dependency>
  • Remote - The adapter itself doesn't manage the lifecycle of a container but binds to an already running container, either locally or on a remote location. This can simplify tests in many scenarios when the continuous integration workflow depends on an already configured application server's instance since the tests only need to know where the server's is located and Arquillian manages the communication to it.
<dependency>

    <groupId>fish.payara.arquillian</groupId>

    <artifactId>arquillian-payara-server-4-remote</artifactId>

    <version>1.0.Beta3</version>

    <scope>test</scope>

</dependency>

 

Running Your Tests Against Payara Server

To run tests with Arquillian against Payara Server, test classes must be annotated with @RunWith(Arquillian.class) or extend the Arquillian class (public class x extends Arquillian) for JUnit or TestNG tests respectively, and have a method annotated with @Deployment to create and deploy a test archive.

 

Arquillian uses test archives to specify the classes and resources required for the test to deploy and run. These test archives use the ShrinkWrap API to define a JAR, WAR, or EAR deployment, allowing your tests to range from basic unit tests, to complicated integration and functional tests.

 

Then you just need to annotate your test methods with @Test or @Test() for JUnit or TestNG respectively, and run them!

 

An Example

To help put things into context, I’ll demonstrate a very basic test using TestNG, Maven, and Payara Micro (I’ll assume you already know how to create a Maven project as well as the src & test folder structure, otherwise check out Maven’s documentation: https://maven.apache.org/guides/getting-started/). First, fill out your POM with the required dependencies I described before so it looks like this:

 

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

 

    <groupId>fish.payara.examples</groupId>

    <artifactId>arquillian-example</artifactId>

    <version>1.0-SNAPSHOT</version>

    <packaging>jar</packaging>

 

    <name>Arquillian Example</name>

 

    <properties>

        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

       

        <payara.version>5.181</payara.version>

    </properties>

   

    <dependencyManagement>

        <dependencies>

            <dependency>

                <groupId>org.jboss.arquillian</groupId>

                <artifactId>arquillian-bom</artifactId>

                <version>1.1.14.Final</version>

                <type>pom</type>

                <scope>import</scope>

            </dependency>

        </dependencies>

    </dependencyManagement>

   

    <dependencies>

        <dependency>

            <groupId>javax</groupId>

            <artifactId>javaee-api</artifactId>

            <version>8.0</version>

            <scope>provided</scope>

        </dependency>

       

        <dependency>

            <groupId>org.jboss.arquillian.testng</groupId>

            <artifactId>arquillian-testng-container</artifactId>

            <scope>test</scope>

        </dependency>

        <dependency>

            <groupId>org.testng</groupId>

            <artifactId>testng</artifactId>

            <version>6.9.10</version>

            <scope>test</scope>

        </dependency>

       

        <dependency>

            <groupId>fish.payara.arquillian</groupId>

            <artifactId>arquillian-payara-micro-5-managed</artifactId>

            <version>1.0.Beta3</version>

            <scope>test</scope>

        </dependency>

    </dependencies>

 

    <build>

        <plugins>

            <!-- Download and copy Payara Micro artefact -->

            <plugin>

                <groupId>org.apache.maven.plugins</groupId>

                <artifactId>maven-dependency-plugin</artifactId>

                <version>3.0.2</version>

                <executions>

                    <execution>

                        <phase>process-test-classes</phase>

                        <goals>

                            <goal>copy</goal>

                        </goals>

                        <configuration>

                            <artifactItems>

                                <artifactItem>

                                    <groupId>fish.payara.extras</groupId>

                                    <artifactId>payara-micro</artifactId>

                                    <version>${payara.version}</version>

                                    <overWrite>false</overWrite>

                                    <outputDirectory>${session.executionRootDirectory}/target/</outputDirectory>

                                </artifactItem>

                            </artifactItems>

                        </configuration>

                    </execution>

                </executions>

            </plugin>

            <!-- Configure Payara Micro Runtime -->

            <plugin>

                <groupId>org.apache.maven.plugins</groupId>

                <artifactId>maven-surefire-plugin</artifactId>

                <version>2.21.0</version>

                <configuration>

                    <environmentVariables>

                        <MICRO_JAR>${session.executionRootDirectory}/target/payara-micro-${payara.version}.jar</MICRO_JAR>

                    </environmentVariables>

                </configuration>

            </plugin>

        </plugins>

    </build>

   

</project>

 

As a managed container, we need to configure how Maven will find and use a Payara Micro instance. In this example, we use the Maven Dependency plugin to download the Payara Micro artefact, and then copy it into the target directory. We then use the Maven Surefire plugin (this is Maven’s test plugin) to set the MICRO_JAR environment variable, pointing it at the downloaded artefact. This environment variable is then used by the Arquillian container to locate the Payara Micro JAR that it should use.

 

Next, you need an application to test. Below is a basic application containing just a single method:

 

package fish.payara.examples.arquillian;

 

public class HelloWorld {

    public String sayHello() {

        return "Hello World";

    }

}

 

Then, you need a test class. This test class simply creates the deployment for Arquillian, and checks that the message being returned by the sayHello() method is correct:

 

package fish.payara.examples.arquillian;

 

import org.jboss.arquillian.container.test.api.Deployment;

import org.jboss.arquillian.testng.Arquillian;

import org.jboss.shrinkwrap.api.ShrinkWrap;

import org.jboss.shrinkwrap.api.spec.JavaArchive;

import org.testng.Assert;

import org.testng.annotations.Test;

 

public class HelloWorldTest extends Arquillian {

   

    @Deployment

    public static JavaArchive createDeployment() {

        return ShrinkWrap.create(JavaArchive.class)

            .addClass(HelloWorld.class);

    }

 

    @Test()

    public void sayHelloTest() {

        HelloWorld helloWorld = new HelloWorld();

        Assert.assertEquals(helloWorld.sayHello(), "Hello World");

    }

}

 

And finally, you can then run the test with one command: mvn clean test

This will compile your application, start a Payara Micro instance, deploy your test application, and run your tests against it.

 

Wrapping Up

Hopefully this should give you enough of a start to begin running your own tests against Payara Server. If you still need some extra help though, the Arquillian website hosts some decent guides. Alternatively, you can check out the Java EE 7 and Java EE8 Sample repositories, which also make use of Payara Server & Micro with Arquillian.

 

 

Comments