How to debug Integration Tests in WSO2 API Manager Code?

After my changes some Integration Tests are failing! How can I find where the problem is? — Is this you? Then this article is for you.

Photo by Safar Safarov on Unsplash

You might get the requirement to debug Integration tests in WSO2 API Manager code after writing a test yourself in product-apim repository or else if a change done by you to carbon-apimgt repository causes a build failure.

Let’s see how this can be done easily.

Step 1 : Build the product-apim repo without tests.

Build the WSO2 API Manager distribution as described in the section titled “How to quickly build a latest WSO2 API Manager pack (distribution) and start the server locally?”, in article “How to contribute to WSO2 API Manager?” by skipping the tests. Make sure your changes are included when you are building the repositories.

Step 2 : Find the test case that you need to debug

In the product-apim repository’s tests-backend module, you will be able to find the Integration tests for WSO2 API Manager.

Assume that the test you need to debug is, APITagVisibilityByRoleTestCase. Open it up in your IDE (IntelliJ IDEA for example) and place breakpoints at the specific line numbers that you need to stop and analyze during debugging.

Step 3 : Comment out the rest of the test cases that are not needed

If you want to run only your selected test case, (this is the situation most of the time), comment out the other test cases in testng.xml leaving the APITagVisibilityByRoleTestCase related entry as it is.

Step 4 : Configure the debugger configurations in your IDE to listen in port 5005 for product-apim

Now configure the remote debugger configurations in your IDE to listen in port 5005 which is the default.

Step 5 : Add debug command to automation.xml

In order to debug the carbon-apimgt code while running the Integration test, you must specify the debug command at the place where the carbon server is running when executing the Integration tests.

This can be done by adding the debug option as a command line argument in automation.xml file in product-apim repository.

For this, find and uncomment the following property in it.

<parameter name=”cmdArg” value=”debug 5005"/>

And then, most importantly change the port to 5006 because as you remember, the product-apim repository is configured to connect with port 5005 during the debugging session. Then the property will look like below.

<parameter name=”cmdArg” value=”debug 5006"/>

Step 6 : Configure the debugger configurations in your IDE to listen in port 5006 for carbon-apimgt

Now open a different IDE window with carbon-apimgt code and configure a remote debugger configuration for port 5006.

Step 7 : Place breakpoints in carbon-apimgt code

If you want to debug specific code from carbon-apimgt that gets executed while running the integration tests, place breakpoints at the respective places in your IDE.

Step 8 : Run the Integration tests in debug mode

Now we can start running the Integration test. For this, navigate in to <repo-root>/modules/integration/tests-integration/tests-backend directory by using your terminal or command line.

Then execute the following command.

mvn clean install -Dmaven.surefire.debug

This will compile the code and show that it is listening for port 5005 when the testing phase has started to run as follows.

Listening for port 5005

This is the time that you need to connect the IDE containing product-apim to this port 5005.

After it is connected, you will see the following screen.

Will be listening for port 5006

If the build seem to be stuck at this point for about 10 seconds, keep connecting the IDE containing carbon-apimgt to port 5006. After seeing a message as connected in the IDE, the tests will eventually start running.

Once the tests start to run, please keep an eye on the Connected status shown in the debug window in your IDE containing the carbon-apimgt. If you see it as disconnected, connect the IDE back to 5006 port. This happens because the carbon server can restart from one test group to another, so you need to reconnect the port as we have given that number as a command line argument in automation.xml.

Port 5006 disconnected

Okay Great! Now we have actually done everything needed to configure the setup for debugging the code, both the Integration test and the carbon-apimgt code at the same time. You can continue your debugging and identify the culprit for the failing test case with ease. 🙂

Happy Debugging!

Thank you for reading the article!

If you find any outdated content or issues with this article, please feel free to create an issue at Developer Corner Git repository here. Let’s grow together and help others in their journey too!

If you like this article please give it a clap. 🙂


Senior Software Engineer @ WSO2 | Toastmaster