Get Started Faster with Forge

Authors: Paul Bakker, Lincoln Baxter, III Translations:
Level: First Steps Last Update:Sep 09, 2012

This guide gets you acquainted with the Arquillian plugin for JBoss Forge. After reading this guide, you’ll be able to:

  • Install the Arquillian plugin into your Forge installation
  • Use the plugin to add the Arquillian infrastructure to a Maven-based Java project
  • Generate a component and corresponding Arquillian test
  • Execute the Arquillian test on multiple containers without manual configuration

You’ll be performing many of the same steps described in the Getting Started guide, only you’ll be letting Forge handle the dirty work for you. We’ve designed this guide to be a fast read to get you started quicker than ever before!


This guide assumes you have JBoss Forge setup. Installing Forge is a relatively short process. Refer to the Getting Started guide or the official Forge documentation for download and installation instructions. You’ll also need JDK 1.6 or higher installed on your machine.

This guide simulates output for a user with a home directory of /home/ike who creates projects in the projects folder and puts applications in the applications folder. Adjust these paths to match your system.

Create a Project

Before we can get started with Arquillian, we first need a project. If you have not created one yet, use the following Forge commands to generate a basic Java EE 6 project that includes CDI.

$ new-project --named arquillian-demo --topLevelPackage org.arquillian.example
? Use [/home/ike/projects/arquillian-demo] as project directory? [Y/n]
***SUCCESS*** Created project [arquillian-demo] in new working directory [/home/ike/projects/arquillian-demo]
Wrote /home/ike/projects/arquillian-demo
Wrote /home/ike/projects/arquillian-demo/pom.xml
Wrote /home/ike/projects/arquillian-demo/src/main/java
Wrote /home/ike/projects/arquillian-demo/src/test/java
Wrote /home/ike/projects/arquillian-demo/src/main/resources
Wrote /home/ike/projects/arquillian-demo/src/test/resources
Wrote /home/ike/projects/arquillian-demo/src/main/java/org/arquillian/example
Wrote /home/ike/projects/arquillian-demo/src/main/resources/META-INF/forge.xml

Forge adds the JBoss Community repository to the pom.xml file. This repository is not required to use Arquillian. You can easily remove the repository from the pom.xml file using this Forge command:

$ project remove-repository 
Removed repository [JBOSS_NEXUS->]
Wrote /home/ike/projects/arquillian-demo/pom.xml

Your new project is now created! Next, we need to create some code to test. Let’s use Forge to create a new CDI bean.

First, we will install CDI into our project using the beans plugin.

$ beans setup
***SUCCESS*** Installed [forge.spec.cdi] successfully.
***SUCCESS*** Beans (CDI) is installed.
Wrote /home/ike/projects/arquillian-demo/src/main/resources/META-INF/beans.xml
Wrote /home/ike/projects/arquillian-demo/pom.xml

Next we will use the plugin to create a new dependent-scoped bean.

$ beans new-bean --type org.arquillian.example.MySimpleBean --scoped DEPENDENT
Picked up type <JavaResource>: org.arquillian.example.MySimpleBean
Wrote /home/ike/projects/arquillian-demo/src/main/java/org/arquillian/example/

The project now has a component. Switch back to the project root and get ready to test it!

$ cd ~~

Setup Arquillian

Setting up Arquillian is easy, as you might have seen in the Getting Started guide. However, there is a lot of copy/paste work required to setup a new Arquillian container adapter in the pom.xml. Forge can do that for you with a single command!

First you will need to install the Forge Arquillian plugin.

$ forge install-plugin arquillian
Connecting to remote repository []... connected!
***INFO*** Preparing to install plugin: arquillian
***INFO*** Checking out plugin source files to [/tmp/forgetemp7898368163271511889/repo] via 'git'
***INFO*** Installing plugin artifact.
***SUCCESS*** Installed from [] successfully.

The plugin is ready to use. Now we need to set up Arquillian and a container adapter. We’ll configure Arquillian to use JBoss AS 7.

$ arquillian setup --container JBOSS_AS_MANAGED_7.X

Forge will prompt you which version of JUnit, Arquillian and JBoss AS 7 to use. Use the latest final versions for each.

Forge can even download JBoss AS 7 for you automatically, which it prompts for in the setup command:

 ? Do you want Arquillian to install the container? [y/N]
If you answer y:
Forge will ask you where you want to install JBoss AS 7 (e.g., /home/ike/applications). Forge then configures the Maven dependency plugin to download and unpack AS 7 to that location (if it’s not already there) before the tests are run.
If you answer N:
You’ll need an existing installation of JBoss AS 7 on your machine.

In either case, you need to tell Arquillian where JBoss AS 7 is installed. One way is to set the JBOSS_HOME environment variable to the location where AS 7 is installed. The preferred way is to set the installation path explicitly using the jbossHome container configuration property in the arquillian.xml file. Forge can help us out with that:

$ arquillian configure-container --profile JBOSS_AS_MANAGED_7.X
Which property do you want to set?

  1 - [Configuration{type='java.lang.String', name='jbossHome', description='The JBoss configuration to start.', defaultValue='$JBOSS_HOME'}]
 ? Choose an option by typing the number of the selection: 1
 ? What value do you want to set? /home/ike/applications/jboss-as-7.1.1.Final
Wrote /home/ike/projects/arquillian-demo/src/test/resources/arquillian.xml

Here’s the resulting arquillian.xml file (formatted for clarity):

<arquillian xmlns=""
    <container qualifier="JBOSS_AS_MANAGED_7.X">
            <property name="jbossHome">/home/ike/applications/jboss-as-7.1.1.Final</property>

In order to use this container configuration, you either have to:

  • Add the attribute default="true" to the <container> element in arquillian.xml
  • Write the qualifier JBOSS_AS_MANAGED_7.X as the only contents of the file src/test/resources/arquillian.launch

That’s it! Arquillian is configured and ready to run tests inside JBoss AS 7.

Write a Test

Now let’s write a test. Once again, Forge can help you get started quickly.

$ arquillian create-test --class
Picked up type <JavaResource>: org.arquillian.example.MySimpleBeanTest
Wrote /home/ike/projects/arquillian-demo/src/test/java/org/arquillian/example/

A new test class with a deployment and test method is added to the project.

package org.arquillian.example;

import org.arquillian.example.MySimpleBean;
import javax.inject.Inject;
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.spec.JavaArchive;
import org.jboss.shrinkwrap.api.asset.EmptyAsset;
import org.junit.Assert;
import org.junit.Test;
import org.junit.runner.RunWith;
import static org.junit.Assert.*;
import static org.hamcrest.core.Is.*;

public class MySimpleBeanTest {
    @Inject private MySimpleBean mysimplebean;

    @Deployment public static JavaArchive createDeployment() {
        return ShrinkWrap.create(JavaArchive.class, "test.jar")
            .addAsManifestResource(EmptyAsset.INSTANCE, "beans.xml");

    public void testIsDeployed() {

As you can see, the test injects the class under test (i.e., MySimpleBean) using CDI, so this will immediately prove if the test really runs in a container.

You can run the test from your IDE, from Maven (outside of Forge) or from Forge itself. Let’s stick with Forge.

$ build test --profile JBOSS_AS_MANAGED_7.X
Running org.arquillian.example.MySimpleBeanTest
Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

Congratulations! You’ve earned your first green bar with Arquillian and JBoss Forge!

Now let’s try to test some JPA code.

Test Persistence

Before we can start writing tests that use the Java Persistence API (JPA), we need to configure JPA. We will then create an Entity and a corresponding Data Access Object. These are the classes we will test.

$ persistence setup --provider HIBERNATE --container JBOSS_AS7
***SUCCESS*** Installed [forge.spec.jpa] successfully.
***INFO*** Setting transaction-type="JTA"
***INFO*** Using example data source [java:jboss/datasources/ExampleDS]
 ? The JPA provider [HIBERNATE], also supplies extended APIs. Install these as well? [y/N] n
Wrote /home/ike/projects/arquillian-demo/src/main/resources/META-INF/persistence.xml
Wrote /home/ike/projects/arquillian-demo/pom.xml

Now create our entity.

$ entity --named Language --package org.arquillian.example.domain
Created @Entity [org.arquillian.example.domain.Language]
Picked up type <JavaResource>: org.arquillian.example.domain.Language
Wrote /home/ike/projects/arquillian-demo/src/main/java/org/arquillian/example/domain/

Then add some fields to our entity.

$ field string --named name
Added field to org.arquillian.example.domain.Language: @Column private String name;
Wrote /home/ike/projects/arquillian-demo/src/main/java/org/arquillian/example/domain/

If you open the Language class, you’ll see a typical JPA entity structure.

Now we need a Data Access Object (DAO) to manage this entity. Copy this dao class into your project.

package org.arquillian.example.dao;

import org.arquillian.example.domain.Language;
import javax.annotation.PostConstruct;
import javax.ejb.Singleton;
import javax.ejb.Startup;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import java.util.List;

public class LanguageDao {
    EntityManager em;

    public List<Language> listLanguages() {
        return em.createQuery("select l from Language l").getResultList();

    public void insertTestData() {
        Language java = new Language();

        Language ruby = new Language();

        Language groovy = new Language();

To compile this class, you’ll need to add the EJB APIs to the project.

$ ejb setup
***SUCCESS*** Installed [forge.spec.ejb] successfully.
***SUCCESS*** Enterprise Java Beans (EJB) is installed.
Wrote /home/ike/projects/arquillian-demo/pom.xml

It’s now time to create our test class. This part should look familiar from the first half of this tutorial, except this time we instruct the create-test command to prepare the test for testing JPA.

$ arquillian create-test --class --enableJPA
Picked up type <JavaResource>: org.arquillian.example.dao.LanguageDaoTest
Wrote /home/ike/projects/arquillian-demo/src/test/java/org/arquillian/example/dao/

This again creates a new test, but also adds your persistence.xml to the deployment. Here’s the test it generated:

package org.arquillian.example.dao;

import org.arquillian.example.dao.LanguageDao;
import javax.inject.Inject;
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.spec.JavaArchive;
import org.jboss.shrinkwrap.api.asset.EmptyAsset;
import org.junit.Assert;
import org.junit.Test;
import org.junit.runner.RunWith;
import static org.junit.Assert.*;
import static org.hamcrest.core.Is.*;

public class LanguageDaoTest {
    @Inject private LanguageDao languagedao;

    @Deployment public static JavaArchive createDeployment() {
        return ShrinkWrap.create(JavaArchive.class, "test.jar")
            .addAsManifestResource("META-INF/persistence.xml", "persistence.xml")
            .addAsManifestResource(EmptyAsset.INSTANCE, "beans.xml");

    public void testIsDeployed() {

Open the test in your IDE and add the Language entity to the deployment. Add the proper import, then change this line:


…to this one:

.addClasses(Language.class, LanguageDao.class)

Now write a new test method to assert the behavior of listLanguages().

public void testListLanguages() {
    Assert.assertEquals(3, languagedao.listLanguages().size());

Now run the tests.

$ build test --profile JBOSS_AS_MANAGED_7.X

Congratulations! Another green bar with Arquillian!

Add More Container Adapters

Adding more container adapters is as easy as executing the setup command again. For example, let’s add a Glassfish remote adapter.

$ arquillian setup --container GLASSFISH_REMOTE_3_1_(REST)

Simply switch between containers by switching the Maven profile. For example in Forge:

$ build test --profile GLASSFISH_REMOTE_3_1_(REST)

Some additional setup is required to get this test to work on a standalone GlassFish instance. Call it homework ~:)

Export the Deployment

For debugging purposes, it can be useful to export your deployment to a file. You can do so using Forge.

First navigate to an Arquillian test:

$ cd src/test/java/org/arquillian/example/

Then export the deployment:

$ arquillian export

You can find the exported archive in the project’s target directory.

$ cd ~~
$ ls target/*.jar

If you inspect that jar file using an archive program, you’ll find that it matches the ShrinkWrap archive you defined in the @Deployment method of the test.

Share the Knowledge

Find this guide useful?

There’s a lot more about Arquillian to cover. If you’re ready to learn more, check out the other available guides.


Find a bug in the guide? Something missing? You can fix it by forking this website, making the correction and sending a pull request. If you’re just plain stuck, feel free to ask a question in the user discussion forum.

Recent Changelog

  • Sep 09, 2012: Translation "get started faster with forge" it by Luca Stancapiano
  • Apr 30, 2012: Change tense of headings, remove the word guide from link text by Dan Allen
  • Apr 29, 2012: Change home directory to /home/ike by Dan Allen
  • Apr 29, 2012: Correct container configuration instructions for as 7, make headings active tense, rewording by Dan Allen
  • Apr 29, 2012: Add instructions for using the configure-container command by Dan Allen
  • Apr 29, 2012: Markup updates by Dan Allen
  • Apr 29, 2012: Include instructions for configuring jbosshome in arquillian.xml by Dan Allen
  • Apr 29, 2012: Change working directory in outputs to /home/paul/projects by Dan Allen
  • Apr 29, 2012: Add instruction to remove the jboss community repository by Dan Allen
  • Apr 29, 2012: Update guide to arquillian and forge; change package to org.arquillian.example; show contents of generated classes by Dan Allen
  • Apr 05, 2012: Use description in prolog for guide summary by Dan Allen
  • Feb 10, 2012: Identify authors & translators by site identity by Dan Allen
  • Nov 18, 2011: Change title to "get started faster with forge" by Dan Allen

See full history »