Mr. Cluey : Library : QAPDebug

QAP Debug

When writing test scripts, there are two major categories of bugs that you have to worry about; bugs in the software that you are testing and bugs in the scripts that you write.

QAPDebug.inc was put together with the latter problem in mind. QAPDebug offers a way to add messages to the result file, with an important twist: when running the test scripts, you can switch off the messages.

If your development environment has a preprocessor, you can use special keywords, called directives, to select what you want to compile, and which bits you no longer need. It is a common practice to put extra messages and tests into the code which the preprocessor will eliminate when it is time to release the code.

Alas, QA Partner and Silk don't have a real preprocessor; any code that you put into your scripts is always going to be there. You can get the same effect by putting run time tests around the code that you want to run only when "debugging".

I usually need three different types of messages when I am debugging. One is used for information, another for warnings, and a third for errors. These are, as you would expect, simply wrappers around Print, LogWarning, and LogError. In each function, a a check against a variable is made to see if QAPDEBUG has been enabled. The three functions are QAPDebugPrint, QAPDebugLogWarning, and QAPDebugLogError.

Typically, QAPDebugPrint is used for information only - reporting that a script has changed some global setting, that a particularly tricky piece of code has executed correctly, or that a particular value was passed into a subsystem. QAPLogWarning typically marks obsolete methods which are still valid, or changes to settings that are expected to remain constant in most cases. QAPLogError reports bugs in the scripts; invalid parameters passed, unexpected exceptions being thrown.

Note that in all of these instances, we want the tester's attention drawn to the script itself - not the application. This central theme determines when QAPDebug should be used rather than the standard methods.

The variable QAPDebugState determines whether the debug messages will appear. It is declared private because we want to restrict the visibility of the variable, only allowing scripts to access it through the QAPSetDebugReports.

As debug messages are enabled or disabled, it makes sense to use boolean values QAPDEBUG_ENABLED and QAPDEBUG_DISABLED.

Further Thoughts

If you later decide to implement more states, switching to an enumerated type would be a good idea.

Of course, if you prefer, you might implement QAPDebug as a class, with methods. With a class based implementation, you can instantiate a local instance of QAPDebug in each file, configuring debug messaging at a local level.

By using compiler constants, you can allow each tester to configure for themselves whether or not they want debug messages used - setting up special opt files to handle debugging.