I usually check bug tickets before they’re assigned to anyone, approaching them as someone without domain knowledge. Once, I asked a colleague to expand their incident report because it was missing crucial steps. He replied angrily, saying developers should already know these steps and that he sometimes feels like a babysitter writing tickets for children.
In my opinion, this is exactly the approach we need: writing bug tickets as if you’re explaining them to someone completely new to the system. As QA Engineers, we often work in a bubble of domain knowledge and application context, which can cause us to skip important steps and information in our incident reports. But how do we create bug reports from outside that bubble? Let’s explore together!
The most essential components for a bug ticket
Before creating a bug report, always check if the issue already exists in your system to avoid duplicates.
Whether your bug report is a Jira ticket, Slack/Teams message, or simple text document, it should contain all the information below.
Title/Summary
Write a concise, descriptive headline that immediately conveys the issue. Include severity level if the bug is critical. The optimal length for a bug ticket title is typically 50–70 characters.
- Poor (too short): “Login issue”
- Poor (too long): “When logging in on an iPhone using Safari and the user has two-factor authentication enabled, the login process fails with a timeout”
- Good: “Login fails on mobile Safari when 2FA is enabled”
Environment Details
Specify exactly where the bug occurs. Include all necessary information that developers need to reproduce the issue. Since bugs can take time to resolve during the SDLC, they may no longer be reproducible in later versions of the application or browser. That’s why you should always include:
- Operating system and version
- Browser/app version
- Device type (mobile, desktop, tablet)
- User account type or permissions level
- Network conditions (if relevant)
Steps to Reproduce
A good “Steps to Reproduce” section should be clear, detailed, and allow anyone to recreate the bug consistently. Here’s how to write effective steps:
-
Structure and format
Write steps as a numbered list with one action per step. Use simple, direct language and active voice. Start each step with an action verb like “Click,” “Enter,” “Navigate,” or “Select.” -
Essential Elements to Include
-
Preconditions
State the initial setup required, such as user permission, specific data that needs to exist before starting. -
Detailed Actions
Be specific about exactly what to click, type, or interact with. Instead of “click the button,” write “click the ‘Save Changes’ button in the top right corner.” -
Best Practices
Make steps atomic and sequential – each step should be a single, clear action that builds on the previous one. Include specific data when relevant, like exact text to enter or files to upload. Assume the reader knows nothing about your system. Avoid shortcuts or assumptions about familiarity with the interface. Test your steps by having someone else follow them, or by following them yourself in a fresh environment.
-
Example for Steps to Reproduce section:
Preconditions:
– User is logged in with admin privileges
– At least one product exists in the catalogSteps to Reproduce:
1. Navigate to Products > Catalog
2. Click on any product name to open the product details page
3. Click the “Edit” button in the top toolbar
4. Change the product name to “Test Product Updated”
5. Click “Save Changes”
6. Navigate back to the catalog page
Expected vs. Actual Results
Clearly state what should happen versus what actually occurs. When possible, use visual indicators – I often mark actual results in red and expected results in green to help developers immediately see the discrepancy.
Example for Actual/Expected Result:
Actual Result:
Product name still shows the original name, changes are not savedExpected Result:
Product name should display as “Test Product Updated” in the catalog list
Reproducibility
Note how often the bug occurs (always, sometimes, once) and document any patterns you’ve observed.
Supporting Evidence
Include visual elements whenever possible: screenshots, screen recordings, or error logs. Annotate images to highlight problem areas—there are many tools available for this. For crashes or errors, copy the exact error messages.
Additional Information
Consider adding other relevant details such as:
- When the bug first appeared
- Recent changes to the system
- Related issues
- Troubleshooting steps you’ve already attempted and their results
- Results of any deep investigation you’ve conducted
You can also describe the impact:
- How many users are impacted?
- Does it block critical functionality?
- Are there workarounds available?
Writing Tips
- Use clear, objective language without emotional reactions
- Stick to facts and observations
- Number your steps and use bullet points for clarity
- Proofread before submitting to ensure accuracy and completeness
The goal is to give developers everything they need to understand, reproduce, and fix the issue quickly.
Conclusion
Developers aren’t children, but remember that your audience extends beyond just developers. Think about stakeholders without technical knowledge, all team members should understand a bug’s potential risk. When you create a well-detailed and understandable bug ticket, you provide significant value to your company.
Developers aren’t the enemies of QA engineers, they’re partners working together to solve problems. Creating excellent incident reports can be “the beginning of a beautiful friendship”.
Author: Norbert Cirok