Troubleshooting and Debugging

There are many methods for debugging business logic and adaptors throughout Kitewheel Hub. While most error messages are very self explanatory, some issues are not as obvious. As a general rule, one should have a test-driven development plan for building graphs in Kitewheel Hub. Implementing such a plan means that every adaptor and every graph should have a unit test case and every process should utilize a tool such as Postman to send test data to test end points and processes. By having this plan from the start, it will make any troubleshooting and debugging much simpler to do, as you can quickly refer to already written test cases to test your graph as you develop the logic and integrations.

In this page, you will find a general guideline of how to move from the high level to the granular level in identifying the issue, debugging it, and then testing it. To do so, we will start with running tests in the admin page and gradually move towards running tests in the graph. 

Testing Adaptor Connections in the Admin page

One of the first things to check is whether or not the service you are integrating with is still successfully connected or not.

To do so: go to the admin page for the project, select the connections tab, and select the connection you want to test - then click the 'Test Connection' button. The 'Test Conneciton' button will result in a pop up that says if the connection was tested successfully or not.  Only saved connections can be tested.  The 'Test Connection' button will be disabled if there are any unsaved edits to the connection.

If the test runs successfully, and if issue exists, it may not be an issue with the connection, in which case one would proceed to look at the graph instead.

If the connector fails to run a test for a database adaptor, more often than not, it is due to a change in the password.

If the connector fails on a queue adaptor, it may be an issue with a name mismatch of the queue assigned or an incorrect password. 

Image: Testing a database connection: 

Image: Pop-up saying that the connection had failed

Debugging in the graph 

If the admin page tests successfully, the next thing to look at is running the graph and looking at the JSON as the record progresses through the graph. To test the graph, there are generally two ways to go about it:

Method 1) Using test data that will get picked up by the listener; and

Method 2) Using mock JSON data to send into the graph.

As a rule of thumb, one could start testing the graph through Method 1 and use that resulting JSON to test particular sections of the graph or individual nodes after identifying the incriminating node. 

Using test data that will get picked up by the listener
  • Enables end-to-end testing to send data from one end of the process to the other
  • Can test multiple nodes in one go to pin-point which general area of nodes is performing the incorrect action
  • Can display the json at the end of each subgraph to see if the JSON is what's expected
  • Can't test the output of an individual node
  • Forced to test the entire graph from the start node to the point of error

Using mock data to test an individual node
  • Can see the output of each node one at a time before it gets passed to the next node or subgraph, providing a more granular view of the record
  • Good for quickly testing a single node, debugging and retesting until the node works as expected
  • Gives you the flexibility to test the graph from any starting point
  • More tedious as it requires a lot of manual changing in the JSON data
  • Does not constitute as end to end testing

After the faulting node has been discovered, depending on the type of node it is, there are different ways to debug the problem and resolve the issue. If the node is having a validation error, check that it is pointing to the correct connection string in the right environment. If that is correct, please visit that node's wiki page to see it's common error messages and possible solutions. 

Important: After debugging the issue, remember to do regression testing on the entire graph to make sure no new issues were introduced!