Setting Up

Arquillian is probably easiest to integrate into your projects using Maven. 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 Payara Micro. Four options present themselves to you here:

• Embedded - Manages the life-cycle 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. The Server Managed option is 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 Micro Managed 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, it requires that you perform some additional configuration.

  <dependency>
    <groupId>fish.payara.arquillian</groupId>
    <artifactId>arquillian-payara-micro-4-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 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 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

An Example

 <project>
     ...
    <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>org.jboss.arquillian.testng</groupId>
            <artifactId>arquillian-testng-container</artifactId>
            <scope>test</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 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:

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:

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.