How to Write a Good Bug Report

A bug report is only valuable if it helps the developer reproduce and fix the issue. This guide covers what to include, how to describe severity, and common pitfalls to avoid.

For Beta Testers

8 min read

Last updated April 2026

What Makes a Bug Report Useful?

The difference between a useful bug report and one that gets ignored comes down to reproducibility. If a developer can't recreate the issue, they can't fix it. Your job as a tester is to give them everything they need to see exactly what you saw.

A good bug report answers three questions: What did you do? What did you expect to happen? What actually happened instead? Everything else—screenshots, severity, component tags—is supporting evidence for those three answers.

Golden Rule

Write your bug report as if you're explaining it to someone who has never used the system before. No assumptions, no shortcuts, no "it just broke." Clear steps, clear expectations.

The Anatomy of a Bug Report

Every bug report you submit through the portal follows the same structure. Here's what each field is for and how to fill it out effectively.

Component

Which part of the system is affected. Examples: Case Intake Form, Dashboard, Settings Page. Be specific—"Login" is better than "Auth System."

Severity

How badly this breaks the workflow. Use the guidelines below—severity drives prioritization, so be honest but not dramatic.

Steps to Reproduce

Numbered list of every action you took before the bug appeared. Start from a known state: "From the dashboard, clicked New Case…" Include clicks, inputs, and waits.

Expected Behavior

What should have happened. "The case should save and show a success message." Base this on the spec or normal behavior you've seen elsewhere.

Actual Behavior

What happened instead. "The save button grays out but nothing happens. No error, no success message." Be precise—exact error text, what changed on screen.

Screenshot

Visual proof. Capture the broken state, error messages, or unexpected UI. Annotate if needed—circle the problem area. Screenshots are optional but highly recommended.

Severity Levels

Severity determines how quickly a bug gets addressed. Use these definitions to classify accurately. When in doubt, go one level lower—it's better to under-promise than over-hype.

Severity Guide
 Critical: 
System completely unusable. Data loss, crashes, security holes. Example: Login broken for all users, database write failures, exposed credentials.
 High: 
Major workflow blocked, no workaround. Example: Can't submit cases, payment processing fails, arbitrator assignments won't save.
 Medium: 
Feature broken but workaround exists, or cosmetic issue affecting usability. Example: Search returns wrong results but manual lookup works, buttons misaligned on mobile.
 Low: 
Minor annoyance, cosmetic flaw, edge case. Example: Tooltip text typo, incorrect label color, inconsistent spacing.

Pro Tip

If you find yourself saying "everything is critical," you're diluting the signal. Reserve Critical for genuine showstoppers. Developers will trust your severity ratings more if you're calibrated.

Steps to Reproduce: The Most Important Field

This is where most bug reports fail. Vague steps like "I clicked around and it broke" are useless. Follow this format every time:

Good Steps Template
 Start state: 
Where you began. "Logged in as admin, on the Dashboard."
 Actions: 
Numbered list of everything you did. "1. Clicked 'New Case'. 2. Selected Harris County. 3. Entered appraisal value $250,000. 4. Clicked Save."
 Trigger: 
The exact moment it broke. "5. After clicking Save, the button grayed out and nothing happened."
 Environment: 
Browser, OS, screen size if relevant. "Chrome 131, Windows 11, 1920×1080."

A developer should be able to copy-paste your steps and see the same bug. If they can't reproduce it, they can't fix it. Test your own steps—try following them yourself before you submit.

Common Pitfalls to Avoid

Here's what not to do when filing a bug report. These are the patterns that get reports closed as "Cannot Reproduce" or "Need More Info."

Don't Do This
 Don't assume context:"The save bug is back" tells us nothing. Which save? Which form? When did you see it?
 Don't lump multiple bugs together: 
One bug per report. If you find three issues on the same page, file three reports.
 Don't skip steps:"I filled out the form" isn't a step. List every field you filled, every dropdown you changed.
 Don't editorialize:"This feature sucks" isn't helpful. Stick to observable facts. Your opinion goes in feedback, not bug reports.
 Don't report features as bugs: 
If the system is working as designed but you think it should work differently, that's a feature request. Use the Feedback Form.

Screenshots: When and How

Screenshots are optional, but they dramatically increase the chances your bug gets fixed quickly. Here's when to include them:

When to screenshot: Error messages (capture the full text), layout bugs (show what's broken vs what's expected), missing elements, broken styling, unexpected UI states. Any time the words "look at this" would clarify your point.

When not to screenshot: Functional bugs where the UI looks fine but behavior is wrong (e.g., calculations are incorrect), data issues where a screenshot won't show what's in the database, timing bugs where a still image doesn't capture the problem.

Screenshot Tips

Capture enough context to show what page you're on. Full-window screenshots are better than cropped regions. If you're showing an error, include the button or action that triggered it. Annotate if needed—a red arrow pointing to the problem saves everyone time.

After You Submit

Once you file a bug report, it goes into the Submissions queue where John can review it. If more information is needed, you'll see a note in your assignments or get a message. Keep an eye on your volunteer dashboard for follow-ups.

Good bug reports get fixed. Great bug reports get fixed fast. The clearer and more detailed you are, the less back-and-forth is needed, and the faster the system improves. That's the whole point of beta testing.