How to Report a Bug | spriteCloud

Let’s start with how not to do it.

So how do you report a bug?

Guiding Principles

Generally speaking, follow these rules:

• Be precise
• Be clear: explain how to reproduce the problem, step by step, so others can reproduce the bug
• Include only one problem per report

The purpose of a bug report isn’t for you to lodge a complaint or get help using software; the purpose of a bug report is for programmers to reproduce it. Not only does this allow the programmer to decide whether your report is a legitimate complaint, or whether you’re better helped by being pointed towards documentation. More importantly, without being able to reproduce a bug, a programmer and/or tester can never verify it is indeed fixed after appropriate changes to the software have been made.

Environment

Given the purpose of a bug report above, a bug report must capture all relevant and/or known information about the environment in which a bug was encountered. That will typically be a list of:

1. The version of the software you’re testing. If not available, provide the date and time at which the bug occurred.
2. The operating system on which you’re running the software, with version number and what service packs/updates are applied.
3. If the software is a web application, include also the exact browser version you’re using when you encounter the bug.

Steps to Reproduce

The steps you take to reproduce this bug should be completely listed. Be short, but precise, e.g.:

1. I log in with my business account.
2. I click on the “foo” tab in the left-hand navigation.
3. I select “bar” from the “quux” drop-down list.

Include everything that is necessary to reproduce the bug in full.

There are often several paths through a software to reach a particular point, and that makes error reporting harder. Should you list them all? Is one enough?

Unfortunately, there’s no good answer here. Ideally software is written such that the path you take to reach a certain piece of functionality makes little difference to whether the functionality works as expected. However, not all software is written this way, and sometimes for good reasons. You, as the user, cannot know whether that is the case.

From that point of view, reporting all paths is ideal. However, it is also a lot more work for you the bug reporter, and for the developer who will try to reproduce it.

The best guideline is to:

1. Report the shortest path you need to take, for easier reproduction.
2. Mention after the steps you documented whether there are other paths that lead you to the bug. If necessary, the developer can ask you for feedback on them.

Expectations vs. Reality

One of the most important aspects of a bug report is the contrast between what you expected to happen, and what actually happened, e.g.:

ExpectedThe main document view should show the “quux” data.ActualThe main document view shows an endless loading animation.

Extra Information

There is always going to be extra information that you have at hand that the developer might find useful.

1. Take a screenshot of the error and attach it. A picture says more than a thousand words.
2. If you need to use file data in your error case, make sure all those files are attached. There may be sensitive information in the files; if so, try reproducing the error with a file that does not contain sensitive data.
3. Report anything else that’s unusual. Does the error only occur on certain days or at certain times? Is there something else that you’re always doing when the bug occurs?
4. Are there any error messages or error information outside of the app you’re using? Do you have a crash report? Add all of that.

Structured English/Gherkin

There is a form of structured English called “Gherkin” that you can use to help guide you towards writing brief but information dense reports. Instead of enumerating the steps to reproduce, prefix them with one of the keywords such as in this example:

Given I logged in with my business account 
When I click on the "foo" tab in the left-hand navigation 
And I select "bar" from the "quux" drop-down list 
Then the main document view should show the "quux" data 
And the main document view should not show an endless loading animation

1. Use Given to list preconditions.
2. Use When to list all actions you take.
3. Use Then to list your expectations and the outcome.
4. Finally, use And whenever a precondition, action or expectation/outcome consists of multiple parts.

Final Thoughts

Writing good bug reports is a skill anyone can learn, but it is a skill. Don’t be daunted when people ask you for more information; all they’re doing is trying to fill in the details listed above.

Thanks for reading! If you enjoyed what you just read or found it useful, let us know by clicking the 👏 below! Follow us for more articles.

Originally published at www.spritecloud.com.