Extensions: How to mock build items and capabilities produced by other extensions without introducing a circular dependency?

[stephanpelikan]

Hi,

I'm developing a Quarkus extension for our business process management system (BPMS) framework VanillaBP. It is about bringing in hexagonal architecture in the context of business processing applications.

There is one main extension doing some annotation based wiring and processing. Any adapter (in the manner of a hexagonal architecture) for a BPMS is a separate extension providing custom build items. The main extension consumes those build items to fulfill the wiring. Additionally, I use Capabilities to validate whether configuration properties given match the adapter extensions provided.

At the moment I stuck building tests for the main extension: It needs the presence of adapter extensions to work properly. My first approach was to build a dummy adapter extension used only in test scope. This worked with capabilities only but fails once I introduced custom build items because of a circular dependency. The main extension provides the build item class > the dummy adapter extension uses the main extension deployment as a dependency > the main extension tests fail because the dummy adapter was not build yet.

It seems to me it would be better to mock adapter extensions in the tests for the main extension. Unfortunately, I didn't find any hints in the docs or the web how to mock custom build items (in real life provided by adapter extensions) and how to mock capabilities (in real life set by adapter extensions) to make this code of the main extension work:

  @Record(ExecutionTime.STATIC_INIT)
  @BuildStep
  void buildProcessServices(
      final QuarkusMigrationAdapterProperties properties,
      // capabilities collected by Quarkus from extensions loaded
      final Capabilities capabilities,
      // consume custom build items provided by adapter extensions
      final List<VanillaBpMigratableProcessServiceBuildItem> processServiceBuildItems) {

    final var adaptersProvidedByOtherExtensions = capabilities
        .getCapabilities()
        .stream()
        .filter(capability -> capability.startsWith(PREFIX_ADAPTER_PACKAGE))
        .map(capability -> capability.substring(PREFIX_ADAPTER_PACKAGE.length())
        .toList();
    
   .... // check whether properties given match the capabilities of extensions loaded

   processServiceBuildItems.forEach(...  process build items according to properties ...);
  
}

How to test this? There are a lot of extensions consuming "custom" build items which also have to be tested.

---

While writing this post I digged into arc extension which consumes custom build items and I found a test which shows how to "mock" build-items. I applied this to my situation:

public class DummyAdapters {
  public static Consumer<BuildChainBuilder> singleDummyAdapter() {
    return builder -> {
      builder.addBuildStep(new BuildStep() {
        @Override
        public void execute(
            final BuildContext context) {
          context.produce(new FeatureBuildItem("vanillabp-dummy"));
          context.produce(new CapabilityBuildItem("io.vanillabp.adapter.dummy", "vanillabp-dummy"));
          context.produce(VanillaBpMigratableProcessServiceBuildItem
              .builder()
              .adapaterName("dummy")
              .build());
        }
      })
          .produces(VanillaBpMigratableProcessServiceBuildItem.class)
          .produces(CapabilityBuildItem.class)
          .produces(FeatureBuildItem.class)
          .build();
    };
  }
}

public class MyTest {
  @RegisterExtension
  static final QuarkusUnitTest unitTest = new QuarkusUnitTest()
      .setArchiveProducer(() -> ShrinkWrap
          .create(JavaArchive.class)
          .addPackage("io.vanillabp.integration.test.sample")    // load sample application classes
          .addAsResource("application.yaml")                     // load sample application properties
          .addClass(DummyAdapters.class))                           // necessary due to anonymous class in DummyAdapters
      .addBuildChainCustomizer(DummyAdapters.singleDummyAdapter()); // add mocked adapter
   ...

This works! It gives the warning

2025-06-17 08:55:24,148 WARN  [io.qua.dep.ste.CapabilityAggregationStep] (build-21) The following capabilities were found to be missing from the processed extension descriptors:
 - io.vanillabp.adapter.dummy provided by vanillabp-dummy
Please report this issue to the extension maintainers to get it fixed in the future releases.

but I guess it is OK, since this is just a warning. I hope this post will help others, since documentation seems to be missing for this.

Cheery,
Stephan