What it is
Arquillian is a powerful testing platform for Java that simplifies integration and functional testing of Java EE and Jakarta EE applications. It allows developers to execute tests inside real runtime containers rather than mocks, ensuring realistic behavior and deployment conditions.
Arquillian allows developers to write tests that run inside real or embedded containers. It manages the deployment lifecycle, container startup, and test execution, and integrates with popular testing frameworks like JUnit and TestNG.
Installation
Add dependencies in pom.xml:
<dependency>
<groupId>org.jboss.arquillian.junit</groupId>
<artifactId>arquillian-junit-container</artifactId>
<version>1.7.0.Final</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.jboss.arquillian.container</groupId>
<artifactId>arquillian-weld-embedded</artifactId>
<version>3.0.0.Final</version>
<scope>test</scope>
</dependency>Getting started
The smallest useful thing you can do with it, and what each part means.
import org.jboss.arquillian.junit.Arquillian;
import org.jboss.arquillian.container.test.api.Deployment;
import org.jboss.shrinkwrap.api.ShrinkWrap;
import org.jboss.shrinkwrap.api.spec.JavaArchive;
import org.junit.Test;
import org.junit.runner.RunWith;
@RunWith(Arquillian.class)
public class MyServiceTest {
@Deployment
public static JavaArchive createDeployment() {
return ShrinkWrap.create(JavaArchive.class)
.addClass(MyService.class)
.addAsManifestResource("beans.xml");
}
@Test
public void testServiceMethod() {
MyService service = new MyService();
assertEquals("Hello", service.sayHello());
}
}Advanced usage
Where the library earns its place over a simpler alternative.
import javax.inject.Inject;
@Inject
MyService service;
@Test
public void testInjectedService() {
assertEquals("Hello", service.sayHello());
}// In arquillian.xml, configure container:
// <container qualifier="wildfly" default="true">
// <configuration>
// <property name="managementAddress">localhost</property>
// <property name="managementPort">9990</property>
// </configuration>
// </container>@RunWith(Arquillian.class)
public class MyTestNGTest extends AbstractTestNGSpringContextTests {
// TestNG methods with @Test annotations
}Errors and fixes
The failures you are most likely to hit, and what actually resolves them.
- DeploymentException
- Occurs when the deployment archive is invalid or container fails to start. Verify ShrinkWrap configuration and container availability.
- InjectionException
- Occurs when CDI beans cannot be injected. Ensure beans.xml is present and CDI beans are properly defined.
- ContainerStartupException
- Occurs if the container cannot start. Check container installation, network settings, and version compatibility.
Best practices
- Use ShrinkWrap to define minimal deployment packages containing only required classes and resources.
- Leverage embedded containers for fast, repeatable tests during development.
- Use Arquillian Drone or Selenium integration for functional web testing.
- Separate unit tests and integration tests clearly to maintain test speed.
- Configure container-specific settings in arquillian.xml to match production environments.
Background
Why it exists, and what it was reacting to.
Arquillian was created to overcome limitations of traditional unit testing frameworks for enterprise applications. It provides a way to deploy your code in a container, run tests against it, and verify real-world interactions, making integration testing easier, repeatable, and closer to production scenarios.