Writing software defect reports is an essential skill for software testers, QA, developers, and support—essentially anyone involved in software development. Defect reports contain details of actions in the software application that don't get the expected result. Either the user receives an unexpected error, the system hangs, or expected calculations or data aren't accurate. Defect reports provide vital information for application development management and staff to fix areas of the application that don't work properly.
While QA has the specific task of uncovering software defects, QA isn't the only team that does this. Frequently, defects are reported by customers through support or service/implementation personnel. The defect report is the most effective manner of communicating, tracking, and explaining defects to managers and development staff. The more logical, organized, and detailed the report, the more likely a developer can reproduce it without assistance or without having to request more information.
However, customer defects typically get reviewed and fixed before internally reported defects. Many application development organizations tend to assume if a customer reports a defect, then that information is of higher value than defects reported internally. Granted, the point of testing is to fix defects before the customer finds them. However, the fact remains that QA-entered software defects are seen as a lower priority. In order to increase your credibility and chances of getting a defect fixed, you need to build a positive reputation for your testing skills by writing concise, detailed, and technically complete defect reports.
Details and specifics
Defect reports need to include details about the platform, code build, environment, or other technical information to create a thorough description. Your defect report needs to be clear and easy to read. Remember that the purpose of a defect report is to get an issue fixed as soon as possible so that customers will continue using the software. Consider separating the details out in the following sections:
- Summary
- Description
- Build/Platform
- Steps to reproduce
- Actual results
- Expected results
In this way, the developer or product manager can quickly get a solid idea of what the defect is, including which part of the application it affects. Software defect reviewers need to review quickly, so the easier it is to find the details, the greater the chances of the defect report being accepted the first time.
Many defects aren't initially accepted if they aren't considered to be of high severity. High severity defects are those that cause harm to a customer either directly or financially. However, there are many defects that get stored in backlog repositories because they're considered mere annoyances or have active workarounds that customers can perform. In my opinion, as a customer, it doesn't matter whether a defect is simply an annoyance or something I have to work around. Any defect that causes customers additional work needs to be accepted and fixed rather than left in storage and ignored.
Explain the workflow or path
Be careful when writing the steps to reproduce. Experienced testers tend to assume that users know certain steps, and inexperienced testers don't know what those steps may be. Write up the steps as you believe you performed them and be specific as to which button, link, or command you used and how you used it. Did you click a button, then a link, or a link, then a button, and then select the item? Whatever the sequence, write down the steps explicitly. Re-execute the steps if you need to review them. Testers should be able to reproduce the defect as entered. If not, adjust the steps until they're correct.
Take note of any configuration, user role, or setup changes that have been made to the QA system you're testing. If you've set a certain configuration, mention that up front. No one likes to dig around the vast number of endless configuration options most applications allow until they get lucky and find the right one.
As a tester, it's important to be certain the steps to reproduce are accurate and specific, so developers and reviewers learn to trust your reports. It's the surest method of gaining credibility. Once you're trusted, they'll review defect reports coming from you sooner. Respect developers and other reviewers by giving them as much information as you possibly can with detailed, specific, and accurate steps to reproduce.
Expected versus actual results: An example
You can't assume developers or other defect reviewers know how the application is supposed to work in every instance. Make sure to document both the expected result and the actual result, preferably in separate sections. For example, consider using the following format:
Summary: Allergy button fails to turn red for visual alert
Description: The allergy button on the medication entry window doesn't refresh after an allergy is entered in the same session from the enter order page.
Build/Platform: Windows 7/IE 11.3
Steps to reproduce:
- Select a patient with existing medication orders.
- Navigate to the medication entry window.
- Enter a medication such as Bactrim, 850 mg.
- In the same session, click the Allergy button in the upper right and enter an allergy to sulfa, moderate severity.
- Click Save in the Enter Allergy window to save.
Actual results: The allergy button doesn't refresh and turn red to alert users to the presence of an allergy.
Expected results: The allergy button automatically refreshes any time a new allergy is entered and saved. The button turns red to indicate an allergy exists on the patient.
Be direct and concise but describe both the result received during testing (actual) and the result you're expecting to see (expected).
Provide evidence
Let's assume you've entered a solid description, summary, and steps to reproduce with both actual and expected results. The tester can reproduce the defect using the steps, and it appears that the report is complete. However, convincing others to fix a defect sometimes requires evidence; that could be in the form of error message text or actual error log text copied at the end of the description. If you enter error text in either form, make a note preceding the text so it's easily distinguishable from the rest of your text.
Attachments in the form of screenshots or videos can be useful as well. Evidence helps display the error if it's otherwise difficult to see or as a way to show the defect response. Video is especially helpful in displaying actions that aren't described in the steps to reproduce.
Spending time providing evidence helps developers find the defect, especially when useful or relevant error logs are included. Including error logs helps developers more than anything else because they can find exactly where the problem is with a technical description. Any time you locate an actual error statement, include it in the defect report.
Boost your QA cred!
Now that your defect report is complete, always review it before submitting. Tester credibility improves when defects are clear, concise, and don't contain spelling or serious grammar issues. If you mention an attachment, make sure you add it and open it to verify it opens without error. Read over the steps to reproduce and use them to reproduce the defect. Note in the description if you're able to reproduce the error at will or on certain builds or platforms. Be concise and direct, including only relevant defect facts—your colleagues will thank you for it.
Keep learning
Take a deep dive into the state of quality with TechBeacon's Guide. Plus: Download the free World Quality Report 2022-23.
Put performance engineering into practice with these top 10 performance engineering techniques that work.
Find to tools you need with TechBeacon's Buyer's Guide for Selecting Software Test Automation Tools.
Discover best practices for reducing software defects with TechBeacon's Guide.
- Take your testing career to the next level. TechBeacon's Careers Topic Center provides expert advice to prepare you for your next move.
