Arquillian: quick start guide

This guide shows main IntelliJ IDEA features for writing and running Arquillian tests.

Before you start

Make sure that the following software is installed on your computer:

Arquillian plugin
Java Development Kit (JDK)
GlassFish Server, version 4

The server will be used as a managed Arquillian container. Download GlassFish.

You should also download javax-inject.jar. This file will be used as a library when developing our sample test class.

Creating a project with Arquillian JUnit support

Click Create New Project on the Welcome screen, or select File | New | Project.

The New Project wizard opens.
In the left-hand pane, select Java Enterprise.
From the Project SDK list, select the JDK that you want to use in your project.

If the JDK is installed on your computer, but not defined in the IDE, select Add JDK and specify the path to the JDK home directory.

If you don't have the necessary JDK on your computer, select Download JDK.
If GlassFish is not defined in IntelliJ IDEA yet, click New to the right of the Application Server field and select Glassfish Server.

In the Glassfish Server dialog, specify the GlassFish Server installation directory.
Under Additional Libraries and Frameworks, select the Arquillian JUnit checkbox.

Click Next.
Specify the name for your new project (for example, HelloArquillian) and click Finish.

(To add Arquillian JUnit support for an existing project: in the Project tool window, right-click your project or module folder and select Add Framework Support. Then, select the Arquillian JUnit checkbox in the dialog that opens.)

Creating a class

Now we are going to create a class that we'll test. Let the class name be com.example.hello.Greeter.

In the Project tool window, right-click the src folder, point to New and select Java Class.
In the Create New Class dialog that opens, type com.example.hello.Greeter in the Name field and press Enter.
The package com.example.hello and the class Greeter are shown in the Project tool window.

At the same time, the file Greeter.java opens in the editor.

Developing code for the Greeter class

Here is the code for the Greeter class.

package com.example.hello;

import java.io.PrintStream;

public class Greeter {
    public void greet(PrintStream to, String name) {
        to.println(createGreeting(name));
    }

    public String createGreeting(String name) {
        return "Hello, " + name + "!";
    }
}
    

Copy the code into the editor.

Defining javax-inject.jar as a library

To be able to write and run our Arquillian test, we need javax-inject.jar as a library.

In the project root folder, create the folder lib (New | Directory) and copy javax-inject.jar into that folder.
Open the Project Structure dialog Ctrl+Alt+Shift+S and select Libraries.
Click , select Java and select javax-inject.jar in the dialog that opens.
Click OK in the Choose Modules dialog.
Click OK in the Project Structure dialog.

Creating a folder for test sources

In the project root folder, create the folder test.
Right-click that folder, point to Mark Directory As and select Test Sources Root.

Creating a test class

In the editor, position the caret within the name of the class Greeter.
Click the light bulb Alt+Enter and select Create Test.
In the Create Test dialog that opens, select Arquillian JUnit4 from the Testing library list. Under Create test methods for, select the method that doesn't return a value greet. Click OK.

The new test class is shown in the Project tool window.

At the same time, the file GreeterTest.java opens in the editor.

The initial content of the test class is defined by the corresponding template. You can edit that template on the Code tab of the File and Code Templates page in the Settings / Preferences dialog (Ctrl+Alt+S | Editor | File and Code Templates).

Completing the code for the GreteerTest class

Here is the code for the test class in its final state:

package com.example.hello;

import org.jboss.arquillian.container.test.api.Deployment;
import org.jboss.arquillian.junit.Arquillian;
import org.jboss.shrinkwrap.api.ShrinkWrap;
import org.jboss.shrinkwrap.api.asset.EmptyAsset;
import org.jboss.shrinkwrap.api.spec.JavaArchive;
import org.junit.Assert;
import org.junit.Test;
import org.junit.runner.RunWith;

import javax.inject.Inject;

import static org.junit.Assert.*;

@RunWith(Arquillian.class)
public class GreeterTest {
    @Deployment
    public static JavaArchive createDeployment() {
        return ShrinkWrap.create(JavaArchive.class)
            .addClass(Greeter.class)
            .addAsManifestResource(EmptyAsset.INSTANCE, "beans.xml");
        }

    @Inject
    Greeter greeter;

    @Test
    public void greet() throws Exception {
        String name="Arquillian";
        Assert.assertEquals("Hello, Arquillian!", greeter.createGreeting(name));
        greeter.greet(System.out, name);
    }
}
    

To insert a proper import statement for @Inject, type @Inj and select @Inject (javax.inject).
Add the remaining code by copying.

Creating a run configuration for running the test

To the left of public class GreeterTest, click and select Run 'GreeterTest'.
In the Edit configuration dialog that opens, click Configure.
In the Arquillian Containers dialog, click , point to Embedded and select GlassFish Embedded 3.1. (We'll start by running the test in an embedded container.)
In the Edit configuration dialog, select GlassFish Embedded 3.1.

Running the test in an embedded container

In the Edit configuration dialog, click Run.
The Run tool window opens and, after some time, the test result is shown there.
Close the Run tool window by clicking .

Editing the run configuration: adding a managed container

Now let's change our run configuration so that it could be used for running the test in a managed container.

Click the run configuration selector and select Edit Configurations.
In the Run/Debug Configurations dialog, click Configure.
In the Arquillian Containers dialog, click and select Manual container configuration.
Change the name of the configuration (for example to GlassFish Managed).
Under Dependencies, click and select Add maven dependency.
In the Download Library From Maven Repository dialog, type arquillian-glassfish-managed-3.1 and click . Then select org.jboss.arquillian.container:arquillian-glassfish-managed-3.1:1.0.0.CR4 from the list.
Select the Download to checkbox and click OK.

At this step, your Arquillian Containers dialog should look something like this:

Click OK.
In the Run/Debug Configurations dialog, select GlassFish Managed and click OK.

Creating the arquillian.xml configuration file

To be able to run an Arquillian test in a managed container, the container adapter needs to know the container location. So let's create the arquillian.xml configuration file with the necessary info.

In the project root folder, create the folder test-resources.
Right-click the new folder, point to Mark Directory As and select Test Resources Root.
In the test-resources folder, create a new file arquillian.xml.
Copy the following into the file:

<?xml version="1.0"?> <arquillian xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://jboss.org/schema/arquillian" xsi:schemaLocation="http://jboss.org/schema/arquillian http://jboss.org/schema/arquillian/arquillian_1_0.xsd"> <container qualifier="glassfish" default="true"> <configuration> <property name="glassFishHome">C:\GlassFish\glassfish4</property> </configuration> </container> </arquillian>

Use your actual path to the GlassFish Server installation folder in place of C:\GlassFish\glassfish4.

Running the test in a managed container

To the right of the run configuration selector, click .

The Run tool window opens and the test result is shown there.
Close the tool window .

Modifying arquillian.xml

Sometimes, you need to deploy your test to a container that is already running. In such cases, you can just change the container configuration file a little and continue using the managed container adapter.

Add the following to arquillian.xml:

Running the test: deploying to a running server

Start GlassFish Server: select GlassFish and click .

When the server is started, you'll see something like this in the Run tool window.
Select GlassFish Managed: GreeterTest and click .

After some time, the test result is shown in the Run tool window.

Last modified: 19 August 2020