Documenting Badboy Scripts

Today I thought I would write about something that many people would rather avoid, but which can be essential in larger projects – making documentation that explains what your test scripts are doing and how and why they work.

Why Write Documentation?

For someone starting out or working on a relatively simple project, making documentation can seem like a bit of a nicety rather than a “must have”.   However, as anyone who engages in a non-trivial amount of quality assurance work knows, your library of automated test scripts soon represents a significant value that needs to be preserved and understood by more people than just yourself, or even your team.   Sometimes it even needs broader exposure to people who understand automated testing tools.

This problem was brought home to me recently very sharply when I engaged in a project to build FDA regulated software for managing medical images and health records.   All of a sudden the problem of correctly documenting QA assets goes from being a nicety to a necessity mandated by law.   In this kind of situation it is not good enough that tests exist – they have to be “seen” to exist, traced to requirements and even be able to be understood by external third parties such as an auditor.  During this project several lesser known features of Badboy proved extremely useful for helping to keep these problems under control and, to my surprise, they turned out to be useful beyond just the purpose of automated testing and as a general library of information about how to navigate and use the web application.

Adding Documentation to Your Scripts

Every item in a Badboy script automatically gets a field for documentation text that can be used to write notes about what it does, how it works, which requirements it is testing or what bugs are related to it.  This text is completely free form and supports simple formatting such as bold, underline, italics and bullet lists.   It also supports adding links to external content so that you can easily open up any web based resource that might be related such as a wiki, project management software or a bug tracker straight from Badboy.
There are several shortcuts for adding documentation that make it a bit easier.   The simplest is just to select the item in the Script Tree and press Ctrl+Shift+D.  This will pop you straight into the Documentation section of the item ready to start typing.  From there you can type to your heart’s content:


To create links in your text, select the text and then press Ctrl+K and a small window will pop up to let you enter the URL that you want to point the link at.

Using Documentation

Once you’ve added some documentation, Badboy uses that documentation in several ways.  The most obvious is that it shows the documentation in the Summary pane inside Badboy so that it’s always there for quick reference as you scan your script:


A much more interesting use of the documentation comes, however, when you Export it using Badboy’s Export HTML Documentation feature which is found in the “Save As” menu.


Upon exporting like this we get a nicely formatted report showing all of our Steps with excerpts from the documentation included for reference:


This is a nice simple HTML document that you can save on your hard drive, email to your boss, or – perish the thought – even print out and put in a filing cabinet!

An intriguing about this kind of export is that not only is it nice documentation about the test, but (assuming you documented it well), it contains most of the essential information for a manual tester to reproduce the test.   This means that you can grab any test you like, export documentation, print it out, and you have in your hand something that a human being can process to perform the test.    This raises a rather interesting possibility of reversing the usual process of writing test specifications – why write a test plan, then implement it with Badboy, when you could do it the other way?  Record your test, add documentation and export it and there you have your test specification!

As counter-intuitive as it seems, there are lots of reasons to like having human readable and manually executable versions of your automated test scripts.    The simple fact is, as useful as automated tests are, they are never as good as a real person carefully looking at the page and assessing it.    Of course you want to offload as much of your manual testing into automated means as you can – but when you need to look deeper – whether it is because things are failing and you need to know why, or whether it is because you just want to do a “final” pass check, having a way to export your test sequence in a human readable form is extremely powerful.

In Conclusion …

These documentation features of Badboy are, in my opinion, greatly under utilized.   The world would be a better place if more people made more documentation of their test scripts.   I would love to hear via the Badboy Feedback Page or comments how usable people find the documentation features of Badboy to be and what we could do to make them even easier to work with.