The bug report is the primary artifact of a QA engineer. A well-written bug report gets fixed fast. A poorly written one sits at the bottom of the backlog forever.
This guide teaches you to write bug reports that developers actually want to fix. Grab our bug report template to follow along.
Why Bug Reports Matter
Your bug report is your communication with the development team. It needs to answer three questions:
- What happened? (actual behavior)
- What should have happened? (expected behavior)
- How can someone else see this? (reproduction steps)
If your report answers these clearly, the developer can fix the bug without asking follow-up questions. That saves everyone time.
The Template
Here's a template that works in any bug tracking tool:
Title Short, specific, searchable. Format: [Feature] - What's broken
Good: "Login - Error message not shown for invalid email format" Bad: "Login doesn't work" Bad: "Bug in the application"
Environment - OS: macOS 14.2 / Windows 11 - Browser: Chrome 121.0.6167 - App version: 2.4.1 - Device: Desktop / iPhone 15
Prerequisites Any setup needed before starting the reproduction steps. Example: "User must have an active account with a verified email"
Steps to Reproduce 1. Navigate to /login 2. Enter "invalid-email" in the email field 3. Enter "validPassword123" in the password field 4. Click the "Sign In" button
Expected Result An error message appears below the email field: "Please enter a valid email address"
Actual Result No error message is displayed. The form submits and the page reloads with no feedback.
Severity / Priority - Severity: Medium (feature works incorrectly) - Priority: High (affects all users trying to log in with invalid email)
Attachments - Screenshot of the form after clicking Sign In - Console log showing no validation error
Common Mistakes
1. Vague titles "Something is broken" tells the developer nothing. Be specific about what feature is affected and what the symptom is.
2. Missing steps "I clicked around and it crashed" is not reproducible. Walk through the exact steps, starting from a clean state. Number each step.
3. Assuming context Don't assume the developer knows which page you were on, what account you were using, or what you were trying to do. Spell it out.
4. No expected vs actual The developer needs to know what the correct behavior should be. Don't just say "it's wrong" — explain what "right" looks like.
5. Missing environment details A bug that only happens on Safari but you don't mention the browser? The developer wastes hours trying to reproduce it on Chrome.
Tips That Make Your Reports Stand Out
Be a storyteller Write steps that anyone can follow — even someone who's never seen the app before. Pretend you're writing instructions for a robot.
Include evidence Screenshots, video recordings, console logs, network responses. Visual evidence makes bugs undeniable and easier to debug.
One bug per report Don't combine multiple issues in one ticket. Each bug gets its own report. This makes tracking, prioritizing, and verifying fixes cleaner.
Test your own steps Before submitting, follow your own reproduction steps from scratch. If you can't reproduce it from your own instructions, the developer won't be able to either.
Use consistent format Use the same template every time. Developers learn to scan your reports efficiently when the format is predictable.
Severity Guide
- Blocker: App crashes, data loss, no workaround. Release cannot proceed.
- Critical: Major feature is broken, workaround may exist. High user impact.
- Major: Feature works but with significant issues. Moderate user impact.
- Minor: Cosmetic issues, low-impact problems. Workaround is obvious.
- Trivial: Typos, minor UI polish. No functional impact.
Real-World Example
Here's a complete bug report:
Title: Cart - Total price not updated when removing an item
Environment: Chrome 121, macOS 14.2, Production (v2.4.1)
Prerequisites: User is logged in and has 2+ items in the cart
Steps to Reproduce: 1. Add Product A ($29.99) to cart 2. Add Product B ($49.99) to cart 3. Navigate to /cart 4. Click "Remove" on Product A 5. Observe the cart total
Expected Result: Cart total updates to $49.99 (only Product B remains)
Actual Result: Cart total still shows $79.98 (sum of both products). Product A is removed from the list, but the total is not recalculated.
Severity: Major Priority: High (affects all cart interactions)
Attachments: Screenshot showing cart with one item but incorrect total. Video recording of the full reproduction.
This report is clear, reproducible, and gives the developer everything they need to start debugging immediately.
Practice Exercise
Pick any website you use regularly. Spend 15 minutes exploring it with a critical eye. When you find something that doesn't work as expected, write a bug report using the template above.
Do this daily for a week and you'll have 5-7 solid bug reports for your portfolio — plus the skill that matters most in QA.