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:

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 - Create jboss-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

5.2. Additional Resources

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.