1. Abstract

The WildFly Testing Tools module (wildfly-testing-tools) provides utilities for creating deployment descriptors, managing WildFly modules, and working with ShrinkWrap deployments. These tools can be used with any testing framework, not just the WildFly JUnit Extension.

2. Overview

This module provides two main utilities:

  • DeploymentDescriptors - Create common WildFly deployment descriptors programmatically

  • ModuleBuilder - Build custom WildFly modules for testing

These utilities work with ShrinkWrap’s Asset API and can be used with any testing framework including JUnit, TestNG, Arquillian, or standalone test harnesses.

3. Getting Started

3.1. Maven Dependency

Add the tools module to your test dependencies:

<dependency>
    <groupId>org.wildfly.testing</groupId>
    <artifactId>wildfly-testing-tools</artifactId>
    <version>${version.org.wildfly.testing}</version>
    <scope>test</scope>
</dependency>

3.2. Requirements

  • Java 17 or later

  • ShrinkWrap API 1.2 or later (for deployment descriptors)

  • WildFly installation (for module management)

4. Deployment Descriptors

The DeploymentDescriptors class provides factory methods for creating common WildFly deployment descriptors as ShrinkWrap Asset objects.

4.1. Creating jboss-web.xml

Set a security domain:

Asset jbossWeb = DeploymentDescriptors.createJBossWebSecurityDomain("my-domain");
war.addAsWebInfResource(jbossWeb, "jboss-web.xml");

Set a context root:

Asset jbossWeb = DeploymentDescriptors.createJBossWebContextRoot("/myapp");
war.addAsWebInfResource(jbossWeb, "jboss-web.xml");

4.2. Creating jboss-deployment-structure.xml

Manage module dependencies:

Set<String> addedModules = Set.of("org.jboss.logging", "org.jboss.resteasy.resteasy-jackson2-provider");
Set<String> excludedModules = Set.of("org.jboss.resteasy.resteasy-jaxb-provider");

Asset deploymentStructure = DeploymentDescriptors.createJBossDeploymentStructure(
    addedModules,
    excludedModules
);
war.addAsManifestResource(deploymentStructure, "jboss-deployment-structure.xml");

This is particularly useful when:

  • You need to add WildFly modules that aren’t automatically available

  • You want to exclude modules to avoid conflicts

  • Testing with specific module configurations

4.3. Creating permissions.xml

Configure runtime permissions for deployments running under a security manager:

Set<Permission> permissions = new LinkedHashSet<>();
permissions.add(new RuntimePermission("getClassLoader"));
permissions.add(new SocketPermission("localhost:8080", "connect,resolve"));
permissions.add(new PropertyPermission("user.dir", "read"));

Asset permissionsXml = DeploymentDescriptors.createPermissionsXml(permissions);
war.addAsManifestResource(permissionsXml, "permissions.xml");

Append permissions to existing configuration:

Asset existingPermissions = DeploymentDescriptors.createPermissionsXml(basePermissions);
Asset updatedPermissions = DeploymentDescriptors.appendPermissions(
    existingPermissions,
    additionalPermissions
);

5. Module Management

The ModuleBuilder provides a fluent API for creating custom WildFly modules programmatically.

5.1. Creating Modules

Build custom WildFly modules:

ModuleDescription moduleDescription = ModuleBuilder.of("com.example.mymodule")
        .addDependency("org.jboss.logging")
        .addDependency("org.jboss.resteasy.resteasy-core")
        .addResourcePath("my-library.jar")
        .build();

The module will be created in the WildFly modules directory and automatically cleaned up when the ModuleDescription is closed.

5.2. Managing Module Dependencies

Add optional dependencies:

ModuleDependency optionalDep = ModuleDependency.builder("org.jboss.optional")
        .setOptional(true)
        .build();

ModuleDescription moduleDescription = ModuleBuilder.of("com.example.mymodule")
        .addDependency(optionalDep)
        .build();

Control dependency exports and services:

ModuleDependency dependency = ModuleDependency.builder("org.example.api")
        .setExport(true)
        .setServices("import")
        .build();

5.3. Cleaning Up Modules

Modules are automatically cleaned up when closed (try-with-resources):

try (ModuleDescription module = ModuleBuilder.of("com.example.mymodule")
        .addDependency("org.jboss.logging")
        .build()) {
    // Use the module during tests
    // Module is automatically deleted when leaving this block
}

Or manually close:

moduleDescription.close();

6. Using with Different Frameworks

6.1. With WildFly JUnit Extension

@WildFlyTest
public class ModuleTest {

    @GenerateDeployment
    public static void createDeployment(final WebArchive deployment) {
        Asset deploymentStructure = DeploymentDescriptors.createJBossDeploymentStructure(
            Set.of("com.example.mymodule"),
            Set.of()
        );

        deployment.addClass(MyClass.class)
                .addAsManifestResource(deploymentStructure, "jboss-deployment-structure.xml");
    }

    @Test
    public void testWithCustomModule() {
        // Test implementation
    }
}

6.2. With Arquillian

@ArquillianTest
public class ArquillianModuleTest {

    @Deployment
    public static WebArchive createDeployment() {
        Asset jbossWeb = DeploymentDescriptors.createJBossWebSecurityDomain("my-domain");

        return ShrinkWrap.create(WebArchive.class)
                .addClass(SecuredServlet.class)
                .addAsWebInfResource(jbossWeb, "jboss-web.xml");
    }

    @Test
    public void testSecurity() {
        // Test implementation
    }
}

6.3. Standalone Usage

public class StandaloneDeploymentBuilder {

    public WebArchive buildTestDeployment() {
        Set<Permission> permissions = new LinkedHashSet<>();
        permissions.add(new RuntimePermission("getClassLoader"));
        Asset permissionsXml = DeploymentDescriptors.createPermissionsXml(permissions);

        return ShrinkWrap.create(WebArchive.class, "test.war")
                .addClass(TestServlet.class)
                .addAsManifestResource(permissionsXml, "permissions.xml");
    }
}

7. Best Practices

7.1. Deployment Descriptors

  • Use DeploymentDescriptors instead of manually creating XML strings

  • Keep deployment descriptors minimal - only add what’s necessary

  • Use meaningful security domain and context root names

  • Document why specific modules are added or excluded

7.2. Module Management

  • Always use try-with-resources or manually close ModuleDescription

  • Use unique module names to avoid conflicts between tests

  • Clean up modules in @AfterAll or equivalent teardown methods

  • Don’t create modules in production code - only for testing

7.3. Integration

  • Combine with @RequiresModule to skip tests when modules aren’t available

  • Use WildFly JUnit Extension for automatic lifecycle management

  • Leverage ShrinkWrap’s fluent API for clean test code

Appendix A: API Reference

For complete API documentation, see the JavaDoc API Documentation.