5 Keys to a Bulletproof Bug:
Day #3

Once you have established a definite Reproducibility, it’s time to move onto spelling out to the reader the exact Steps they will need to follow to be able to reliably replicate your bug. This Key begins with the Setup and then lists the necessary Steps to Reproduce.

Key #3: Steps to Reproduce

Your Setup should tell the reader about any conditions that must be present, any prerequisites that must be met, and/or any environmental factors that are necessary to be able to reproduce your bug.

This is separate from the Steps. This is how to Set Up so that once they follow the Steps they will be able to experience the joy that is your bug.

In your Setup, explain where the user needs to start.

For instance:

• In Windows 98SE:
• In MacOS 10.3.9:
• Using IE 5.5:
• Running AOL 10 on Win2K with Screensaver set to 1 minute:
• After spinning around in your chair three times:

All of those statements could be used as a Setup. Ok, that last one you will probably never use, but you get the idea.

Your goal when writing the Setup is to help the reader get their testing environment ready so that all they must do after the Setup is follow your Steps.

I know this sounds simplistic, and it is, but can you see what would happen if you didn’t include a Setup when one was called for? If a bug only occurs in Windows XP and the reader is attempting to reproduce your bug on a Mac – because you didn’t state that the bug only occurs in Windows XP – what will they think when the follow your Steps but your bug doesn’t occur?

The first reaction is always to question the validity of the bug. As a result of that reaction, the reader will also question the person who wrote the bug. This again is not the result you are looking to achieve on your way to becoming an elite Quality Assurance Professional.

When a developer or producer spends an hour of their time futilely trying to reproduce a bug that was written inaccurately, they will feel that their time was wasted. And since it occurred while they were trying to understand a bug you wrote, they will blame you for wasting their time. Let’s avoid this.

In order to avoid this unpleasant scenario, just include the necessary Setup when it is appropriate. When you do this, it is often not noticed initially. No one says, “Good Setup!”

But you know that you have provided the information they need to reproduce the bug…even if they don’t see it. And sometimes the reader does miss it. It’s right there in front of them, but since they are not as detail oriented as you, sometimes they miss the little things.

It can be entertaining to politely set a developer straight when they claim that they are unable to reproduce your bug. They have tried but can’t replicate it and ask you what you forgot to include.

Then you ask them if they are testing it using XP – as stated in your bug. The inevitable pause will occur…time passes slowly…then they tell you…their machine is running Win2k, not XP…and they ask, “Why doesn’t the bug happen the way you wrote it? Do I have to use XP?”

Now it is up to you to not laugh, to not say I-told-you-so. Now you politely explain that yes, indeed, the bug only occurs in XP.

They will either go away quietly and eventually notice that you had included that information in the first place, and they may apologize for the misunderstanding (and ask to borrow an XP machine). Or they might ask you right then why you didn’t include it in the bug in the first place. Again, this is your chance to not laugh.

You now should very politely, really, as politely as possible, point out where in the bug you included this information. They may now apologize, or look sheepish, or just say, “Oh” (which means “oops”). Either way, you did you job like a professional and when challenged you were able to point the questioner to the exact place they needed to find the information they were missing.

As I said before, you may not need to include a Setup. If your bug occurs on every operating system, every time – then you probably won’t need to include a Setup. But if you are in doubt, go ahead and include it.

So, you should now have a clear idea of why to write a Setup, when you would need it, and how to write it up. Let’s move to the next piece of this Key; the Steps.

The Steps to Reproduce
This is very simple, but many people still do this incorrectly. Here is the best way to write them:

1. Always number them (and start with the number “1”)
2. Make sure each step is a single action
3. As soon as the next action is needed, make another step
4. Write all steps needed until the bug occurs
5. DO NOT INCLUDE THE RESULT (THE BUG) IN THE STEPS

Your Steps to Reproduce should be simple. That is imperative!

The more complicated you make them, the more difficult your bug will be to understand. If your bug is difficult to understand, your work will look less professional – so make it simple. Remember KISS.

The Setup and Steps to Reproduce should look something like this (text in quotes to be replaced with your own specifics):
On a Mac running OS 10.3.7:

1. Launch "program name"
2. Navigate to "specific location"
3. Select "particular button"
4. When "window 'x'" appears, select "the link"

And that’s it. Just what they should do and where they should do it. As soon as all of the action Steps are listed, right up to the moment that the bug occurs, move on to the Result.

This is very important: The Steps just comprise the path that lead to the event that triggered you to write up the bug in the first place. Do not include this event in the Steps – this event is the Result.

Does that make sense?

Here is what your bug looks like so far:

• You have summarized it in a single sentence for easy scanning and understanding
• You have explained in more explicit language the full effect of the issue
• You have stated a clear frequency of occurrence
• You have listed any environmental variables that must be in place to make the bug occur
• You have walked the reader through the exact path they must follow

And tomorrow the payoff…