The Gradle plugin used to run the system tests supports the debugging of the services running inside Docker containers. This makes debugging issues with system tests so much less painful.

Note: Service debugging is currently only supported through the IntelliJ IDE. If you’re using another IDE, then please consider contributing to get service debugging working for your IDE.


Debugging of services currently requires the AttachMe IntelliJ plugin to be installed.

The aggregate-template repository has preconfigured the service to support debugging.

ProTip: Details of what configuration is required, if you want to dig into the details, can be found in the creek-system-test and system-test Gradle plugin docs.

Debugging a service

With AttachMe plugin installed, the handle-occurrence-service can be debugged with the following steps:

  1. Create and run an AttachMe run configuration.
    AttacheMe run configuration
  2. Name the new configuration, but leave the default port at the default 7857.
    AttacheMe run configuration details
  3. Place the required breakpoints in the code. For example, place one in the TopologyBuilder’s extractHandles() method.
    Add breakpoint
  4. Run the system tests, specifying which service to debug:

    ./gradlew systemTest \
      --debug-service="handle-occurrence-service" \

When the system tests start the handle-occurrence-service Docker container, the service will attach to the debugger. This will cause a new debug window to open and for the breakpoint to be hit:

Breakpoint hit

Pretty cool, right?

ProTip: The --verification-timeout-seconds argument increases the amount of time the system tests wait for the expected output, allowing more time to debug the code. Learn more on this, and other options, in the system test plugin documentation.