1. Abstract
WildFly Testing Tools is a comprehensive testing framework for applications running on WildFly application server. It consists of three independent sub-projects that work together to simplify Jakarta EE and WildFly testing with JUnit.
| This is not a replacement for Arquillian. These tools are WildFly-specific and designed for simpler, focused WildFly testing scenarios. |
2. Quick Start
Choose the module(s) you need:
-
Just need conditional tests? → Use WildFly JUnit API
-
Need full server lifecycle management? → Use WildFly JUnit Extension
-
Need deployment utilities? → Use WildFly Testing Tools
Most users will want the Extension module, which includes full server management, deployment handling, and resource injection.
2.1. Maven Dependencies
<dependencies>
<!-- Full testing framework with server lifecycle -->
<dependency>
<groupId>org.wildfly.testing</groupId>
<artifactId>wildfly-junit-extension</artifactId>
<version>${version.org.wildfly.testing}</version>
<scope>test</scope>
</dependency>
<!-- Optional: Deployment utilities -->
<dependency>
<groupId>org.wildfly.testing</groupId>
<artifactId>wildfly-testing-tools</artifactId>
<version>${version.org.wildfly.testing}</version>
<scope>test</scope>
</dependency>
</dependencies>
3. Modules Overview
3.1. WildFly JUnit API
Artifact: wildfly-junit-api
Provides annotations for conditional test execution based on WildFly configuration:
-
@RequiresModule- Skip tests when WildFly modules aren’t available -
@AnyOf- Run tests if any of multiple requirements are met -
@JBossHome- Inject WildFly installation directory
Use when: You need conditional tests but manage the server yourself or use another framework like Arquillian.
3.2. WildFly JUnit Extension
Artifact: wildfly-junit-extension
Full-featured JUnit extension that automatically manages WildFly server lifecycle:
-
Automatic server startup and shutdown
-
Per-test deployment management
-
Resource injection (
ServerManager,URI) -
Domain mode support
-
Manual lifecycle control when needed
-
Custom resource producers via SPI
Use when: You want comprehensive WildFly testing with minimal boilerplate.
3.3. WildFly Testing Tools
Artifact: wildfly-testing-tools
Utilities for creating deployment descriptors and managing modules:
-
DeploymentDescriptors- Createjboss-web.xml,jboss-deployment-structure.xml,permissions.xml -
ModuleBuilder- Build custom WildFly modules programmatically
Use when: You need deployment utilities with any testing framework (JUnit, TestNG, Arquillian).
4. Example Usage
4.1. Basic Test with Extension
@WildFlyTest
public class HelloWorldTest {
@GenerateDeployment
public static void createDeployment(final WebArchive deployment) {
deployment.addClass(HelloServlet.class);
}
@Test
public void testHello(@ServerResource URI uri) throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(uri.resolve("hello"))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
Assertions.assertEquals(200, response.statusCode());
}
}
4.2. Conditional Testing with API
@RequiresModule("org.jboss.as.ejb3")
@RequiresModule("org.jboss.as.jpa")
public class EjbJpaTest {
@Test
public void testEjbWithJpa() {
// Only runs if both EJB and JPA modules are available
}
}
4.3. Using Testing Tools
Asset deploymentStructure = DeploymentDescriptors.createJBossDeploymentStructure(
Set.of("org.jboss.logging"),
Set.of()
);
war.addAsManifestResource(deploymentStructure, "jboss-deployment-structure.xml");
5. Documentation
5.1. Module Documentation
-
WildFly JUnit API - Conditional test annotations
-
WildFly JUnit Extension - Server lifecycle and resource injection
-
WildFly Testing Tools - Deployment and module utilities
5.2. Additional Resources
-
Real-World Examples - REST, JPA, Security, and EJB testing examples
-
Troubleshooting Guide - Common issues and solutions
6. Architecture
The three sub-projects work together as follows:
-
API can be used standalone or with any framework (including Arquillian)
-
Extension depends on API and optionally uses Tools
-
Tools is completely independent and works with any framework
Appendix A: Frequently Asked Questions
A.1. General Questions
Q: Is this a replacement for Arquillian?
A: No. This framework is WildFly-specific and simpler than Arquillian. Use Arquillian if you need multi-container support or advanced features. Use this framework for WildFly-only testing with less setup overhead.
Q: Can I run tests in parallel?
A: In some cases, yes. If you modify the server configuration or use manual mode testing, it’s highly suggested you do not use parallel execution. In other cases it should work.
Q: How do I specify which WildFly installation to use?
A: Set the jboss.home system property or JBOSS_HOME environment variable. See Extension Configuration for all available properties.
Q: How do I enable debug logging?
A: Set the org.wildfly.testing logger to DEBUG/FINE level in your logging framework. See Troubleshooting for complete examples.
Appendix B: Glossary
- Deployment
-
A packaged application (WAR, EAR, JAR, RAR) that is deployed to WildFly for testing. Created using ShrinkWrap.
- Domain Mode
-
WildFly’s clustered configuration mode where a domain controller manages multiple server instances across server groups.
- Manual Mode
-
A testing mode (enabled with
@ManualMode) where the test controls server lifecycle instead of the framework. - ServerManager
-
The main API for controlling and interacting with a WildFly server instance during tests.
Appendix C: Related Documentation
-
JavaDoc API Documentation - Complete API reference for all three sub-projects
-
WildFly Plugin Tools - ServerManager API documentation
-
WildFly Project - WildFly application server documentation
-
JUnit Documentation - JUnit user guide
-
ShrinkWrap - Java API for creating archives