August 12, 2009

TestTrack SDK Helpful Hint - Troubleshooting

Helix ALM
In this installment of the TestTrack SDK Helpful Hint posts, I am going to discuss ways to troubleshoot issues when programming with the SOAP SDK.

Basic Programming Tips

If you are using the TestTrack SDK, chances are that you have some familiarity with programming, so the following list is probably nothing new to you:
  • Run in Debug mode: If you are in an Integrated Development Environment, chances are you have the ability to use breakpoints and run the application in Debug mode. With the TestTrack SDK, you could see how a CDefect object is being built, like the array of CEvents used in the workflow.
  • Print out to console: If you are not in an Integrated Development Environment and do not have access to breakpoints, then you might only be able to print to console the values of variables to make sure everything is being built correctly.
  • Keep it simple: Start simple and build up until you run into the issue. For example, let's say you are writing an application that logs in to TestTrack, gets a list of defects based on field values, gets a number of them for modification, and then logs out. When you run the application you get exceptions. So where is the problem?  Break it down. First, write a simple application that logs in and out of TestTrack. Did that cause a problem?  Then add the code to get the defect list. Did that cause a problem? So you get the idea. You keep building it up until the issue appears again. This should allow you to isolate the issue.

Capture the Messenger

So you have used the tips above and you know where the error is, but you still don't know what is causing the error. Let's back up a little bit. Remember that the way SOAP works is that when your application sends a request to the TestTrack SOAP CGI running on the web server, the application sends this request in the form of an XML file. The TestTrack SOAP CGI reads this request, translates it, and sends it to the TestTrack server. The TestTrack server then sends a response to the TestTrack SOAP CGI, which translates it into an XML file and sends this back to the application. The diagram below illustrates this process. soap When a request to the TestTrack server fails, the response from TestTrack usually includes a meaningful message. The message is enclosed in the "faultstring" tag of the response. The trick is how to get to that message. The approach will vary based on the language that you use. For example, using C# and the .NET framework, all you really need to do is enclose your code in the proper try/catch statements. Most of your exception messages will be the message enclosed in the faultstring tag. You will see messages like "The following fields are required: Type". However, not everyone uses C# or even Visual Studio, so in those cases, what can you do? Besides C#, I have also used Java and Python. Java is very much like C#, except that the exceptions do not give me the same type of error messages that programming in C# does. Python is even more difficult, since you must read in the XML and parse for the "faultstring" tag. The best way to troubleshoot any type of SOAP issue is to intercept the XML requests and responses. This way you can see how the XML request is built by your application and the request that is returned. This is especially helpful when you receive cryptic errors, like "well-formedness error".

So how do you do this?

There are several tools available. Since I am a Windows user, I find the MS SOAP Toolkit very helpful. You install this on the same computer as your application. The SOAP toolkit acts like a "middle man" between your application and the TestTrack SOAP CGI. Your application sends the request to the SOAP toolkit, and it forwards it to the SOAP CGI. This means that you will need to change the URL that your application uses to communicate to the SOAP CGI, mainly switching the address from something like "" to "http://localhost:8080/scripts/ttsoapcgi.exe". The SOAP toolkit will want to use a different port than the one in use by your web server. In my example, the web server where the SOAP CGI resides runs on port 80. When I set up the trace I have it listen on port 8080, which is why I included that in the URL. Below is a modified version of the previous diagram to show where the SOAP toolkit fits in. soap2 As mentioned above, this is especially helpful when you are getting cryptic error messages. Sometimes the libraries that you are using to build the SOAP request may not handle certain things correctly, or may not build certain things correctly. Being able to catch the request that is being sent allows you to see what is actually happening and can help you troubleshoot the problem. Here is a screenshot of the MS SOAP toolkit capturing a failed add defect request: soaptoolkit If you are not a Windows user there are other tools, such as SOAP UI, that can be used to help with troubleshooting.