How to write a bug report developers actually fix (with template)

How to write a bug report that gets fixed: the fields that matter, steps to reproduce, picking severity, what to attach, and a copy-ready template. By betatest.ing team · September 15, 2026 · 6 min read.

Key takeaways

  • One bug per report, with a title that states the symptom and where it happens.
  • Steps to reproduce start from a known state and are numbered; the last step is the one that fails.
  • Always write expected result and actual result as two separate lines.
  • Attach a screenshot with the problem marked, or a short recording for anything involving timing.
  • Severity describes impact on users; priority is a scheduling decision the team makes.

In this article

  1. Why most bug reports do not get fixed
  2. The anatomy of a report that gets fixed
  3. The template
  4. A worked example
  5. Writing reports for problems that are not bugs
  6. Habits that make the whole process smoother
  7. What this looks like with an AI beta tester

A bug report has one job: let someone who was not there see the problem for themselves. Reports that do that get fixed. Reports that do not get a polite "cannot reproduce" and a slow death in the backlog. This article covers the fields that matter, why they matter, and gives you a template to copy.

Why most bug reports do not get fixed

Developers do not ignore bugs out of laziness. They skip reports that would cost twenty minutes of guessing before the actual work starts. The usual failure modes:

  • No steps. "Export is broken." Which export, from where, with what data?
  • Several bugs in one report. The first gets fixed, the report is closed, the others vanish.
  • Opinion instead of observation. "The dashboard is confusing" may be true, but it is not a bug report.
  • Missing environment. The bug only happens on Safari, and the developer tried Chrome.
  • No expected result. The developer cannot tell whether what they see is the bug or the intended behavior.

Every field in a good report exists to remove one of those gaps.

The anatomy of a report that gets fixed

Title: symptom plus location

The title should let someone scanning a list understand the problem without opening it. A useful pattern is *what happens* + *where* + *when*:

  • Weak: "Login bug"
  • Better: "Login button does nothing after a wrong password on mobile Safari"
  • Weak: "Export broken"
  • Better: "CSV export downloads an empty file when the date filter is set"

Avoid severity words in the title ("URGENT!!!"); that is what the severity field is for.

Environment

Browser and version, operating system and device, screen size if layout is involved, account type or role, and the environment (staging or production) with the URL. For mobile apps: app version or build number, OS version and device model. This takes ten seconds to write and saves the first ten minutes of investigation.

Preconditions

The state the system must be in before the steps start. "Logged in as a workspace admin with at least one project" or "Cart contains one item with a discount code applied". If the bug needs specific data, say what it is or attach it.

Steps to reproduce

This is the core of the report. Rules that work:

  1. Start from a known place, usually a URL. "Go to /settings/billing."
  2. One action per step. Click, type, select, wait.
  3. Use the exact text on the buttons and links. "Click Save changes", not "save it".
  4. Include the data you entered. "Type [email protected] in the Email field."
  5. Make the last step the one where the problem appears.
  6. Say how often it happens if it is not every time. "Happens roughly one time in three."

If you cannot reproduce it yourself, say so and give what you have. An honest "happened once, here is the recording" is more useful than invented steps.

Expected result and actual result

Two separate lines, every time.

  • Expected: The invoice PDF downloads with the company name from Settings.
  • Actual: The PDF downloads but the company name field is blank.

The expected line is what turns an observation into a bug: it tells the developer what "correct" looks like. If you are not sure what should happen, write what you expected as a user and flag that it may be a design question.

Severity

Severity is about impact on users, not about how annoyed you are. A four-level scale that most teams agree on:

  • Critical: Data loss, security issue, payment taken incorrectly, or a core flow completely blocked for everyone. Nothing ships until this is fixed.
  • High: A core flow is blocked for a significant group of users, or there is no reasonable workaround.
  • Medium: A feature misbehaves but users can get around it; visible errors; incorrect but non-financial data.
  • Low: Cosmetic issues, typos, minor layout problems, inconsistencies.

The guide to bug severity levels has examples at each level, and the bug severity calculator asks four questions and suggests one. Note that severity is not priority: a low-severity typo on the pricing page might be fixed before a medium bug in an admin screen. Priority is a scheduling call the team makes; severity is a description you provide.

Evidence

  • Screenshot for anything visual, with the problem marked (a box or arrow is enough). Crop to the relevant area but keep enough context to recognize the page.
  • Screen recording for anything involving timing, animation, or several steps. Keep it short and start a step or two before the problem.
  • Console errors and network responses for web apps: open developer tools, copy the red lines. For a failing request, the status code and the response body help enormously.
  • Logs or crash reports for mobile apps.
  • The exact input that caused it, as text, so it can be pasted.

Workaround

If you found one, include it. It changes the severity conversation and helps support in the meantime.

The template

Copy this into your tracker's issue template or your beta feedback form.

Title: [symptom] [where] [when]

Environment:
- Browser / app version:
- OS and device:
- Screen size (if layout):
- Account / role:
- Environment and URL:

Preconditions:
-

Steps to reproduce:
1.
2.
3.

Expected result:

Actual result:

Frequency: always / intermittent (about x in y)

Severity: critical / high / medium / low

Evidence: (screenshot with the problem marked, recording, console errors)

Workaround (if any):

The bug report template guide has filled-in examples, and the free bug report generator turns a rough description into this format.

A worked example

Here is a mediocre report and the same bug written properly.

Before: "Can't save my profile, keeps erroring. Please fix asap."

After:

Title: Saving profile shows "Something went wrong" when the display name contains an apostrophe

Environment: Chrome 130, macOS 15, staging (https://staging.example.com/settings/profile), role: member
Preconditions: Logged in as a member with an existing profile.

Steps:
1. Go to /settings/profile.
2. In Display name, type: O'Brien
3. Click Save changes.

Expected: Profile saves and the toast "Profile updated" appears.
Actual: Red banner "Something went wrong" appears; name is not saved. Console shows a 500 from POST /api/profile.

Frequency: always, with any name containing an apostrophe. Names without one save fine.
Severity: medium (workaround: remove the apostrophe; affects anyone with such a name).
Evidence: screenshot of banner, console error attached.

The developer can reproduce this in under a minute, and the apostrophe detail points straight at the likely cause.

Writing reports for problems that are not bugs

Beta testers also find friction: places where the product works but people do not understand it. Report those too, but label them. A pattern that keeps the two apart:

  • Bug: The product did something other than what it was designed to do.
  • Friction: The product did what it was designed to do and the design was the problem.

Write friction reports with the same steps and evidence, replace "expected result" with "what I was trying to do", and skip severity in favor of how many testers hit it.

Habits that make the whole process smoother

  • Search before filing. A duplicate costs triage time. Add your environment to the existing report instead.
  • One bug per report. If you find three on a page, file three. Link them if they seem related.
  • File the same day. Details evaporate overnight.
  • Stay neutral. "The button does nothing" lands better than "the button is useless". The report is for the person fixing it.
  • Follow up on "cannot reproduce" with a recording. It is almost always an environment or data difference.
  • Close the loop. When a fix ships, re-run your own steps on the same device and say so in the ticket. A bug that is verified by the person who found it stays fixed; one that is closed on the developer's word has a way of returning in the next release.

What this looks like with an AI beta tester

Every bug betatest.ing files follows the structure above by default: title, environment, numbered steps, expected vs actual, severity from a fixed scale, a screenshot with the problem annotated, and a recording of the run. Reports export to PDF or Excel so they drop straight into your tracker. If your human testers' reports are thin, running the AI tester over the same flows gives developers the reproducible version.

Start for $1 and get your first set of properly written bug reports within the hour.

Related guides

Each ends with a test task you can send to your AI beta tester.

All beta testing guides

Keep reading

All articles