How to write a good bug report

A good bug report lets a developer reproduce the problem in minutes without asking a single question. Here is what to include, how to write each part, and an example you can copy.

Who it’s for

Beta testers who want their bugs fixed
Founders and PMs writing bugs for developers
Support teams passing customer issues to engineering

Updated 2026-10-19.

Knowing how to write a bug report well is the fastest way to get bugs fixed. A good report lets a developer reproduce the problem on the first try, without a round of questions. This guide covers the parts of a report, a step-by-step process, examples, and the mistakes beta testers and teams make most often.

The parts of a good bug report

Title: what is broken, where, and under what condition. "Checkout: Pay button does nothing when coupon is applied" beats "checkout broken".
Steps to reproduce: numbered, starting from a known state (a URL, logged in or out, which account).
Expected result: what should have happened.
Actual result: what happened instead, with the exact error text.
Environment: device, operating system, browser and version, screen size, account type, build or date.
Severity: how bad it is for users (see bug severity levels).
Evidence: a screenshot with the problem marked, a screen recording for anything involving motion or several steps, and console errors if you can get them.
Frequency: always, sometimes, once.

How to write a bug report, step by step

Reproduce it once more. Before writing, try to make the bug happen again from a clean start, so you know the real steps.
Find the shortest path. Remove every step that is not needed to trigger the bug.
Note the starting state. Which URL, which account or role, logged in or out, what data already existed.
Write the steps as numbered actions, one action per line, with the exact text you typed.
Write expected and actual separately. Copy error messages word for word.
Capture evidence. Take a screenshot and mark the problem; record the screen if timing or several steps matter; copy console errors if you can open developer tools.
Fill in the environment while it is in front of you: device, OS, browser and version, screen width, build.
Set severity and frequency.
Search for duplicates, and add your details to an existing report instead of filing a new one.
Write the title last, once you know exactly what the bug is.

Writing tips for each part

Title. Put the area first, then the symptom, then the condition. Someone scanning a list of fifty bugs should understand each one from the title alone.

Steps. Write them so a person who has never seen the product can follow them. Include the data you used ("enter 'test@example' without .com"). Remove steps that are not needed to reproduce the bug.

Expected vs actual. Keep them separate and factual. "Nothing happens" is fine; "it's terrible" is not information.

One bug per report. If you found three problems, file three reports. Combined reports get half-fixed and closed.

Intermittent bugs. Say how often it happens ("3 of 5 tries"), and what was different when it did not happen.

Example bug report

Title: Signup: "Create account" stays disabled after fixing an invalid email

Steps to reproduce:
1. Open /register in a private window (logged out)
2. Enter name "Test User", email "test@example", password "Testpass123!"
3. See the "Enter a valid email" message
4. Change the email to "[email protected]"

Expected: the error disappears and "Create account" becomes clickable
Actual: the error disappears but "Create account" stays disabled until the page is reloaded

Environment: iPhone, iOS Safari, 390px width, staging build of today
Severity: Major (blocks signup for anyone who mistypes their email)
Frequency: Always
Evidence: screenshot with the disabled button circled, 12 s recording
Console: no errors

A weak report rewritten

Before:
"Search is broken on mobile, please fix ASAP!!"

After:
Title: Search: results list is empty on Android when the query has a trailing space

Environment: Pixel phone, Android, Chrome, 412px width, production
Account: logged in as a regular user with 20+ saved items

Steps to reproduce:
1. Open /items
2. Tap the search field and type "invoice " (with a space at the end)

Expected: items containing "invoice" are listed
Actual: "No results"; removing the trailing space shows 4 results
Severity: Minor (easy workaround once you know it)
Frequency: Always; also happens on desktop Chrome
Evidence: two screenshots, with and without the trailing space

The rewrite turns a complaint into something a developer can fix in one sitting, and the severity is honest rather than "ASAP".

Bug report checklist

Before filing

Reproduced at least twice from a clean start.
Searched for an existing report.
Only one problem in this report.

In the report

Title names the area, the symptom and the condition.
Starting state given: URL, account, logged in or out.
Steps numbered, minimal, with exact input data.
Expected and actual written separately.
Exact error text copied.
Device, OS, browser and version, screen size and build listed.
Severity and frequency set.
Screenshot marked; recording attached if steps or timing matter.
No passwords, payment card numbers or personal data in the report or screenshots.

Prioritizing the bugs you report

Severity tells the team how bad the bug is for users; priority is when they will fix it. As a reporter, help them decide by stating the impact plainly: who is affected, can they finish the task, is there a workaround, is data or money at risk. Bugs that block signup, login, payment or the main flow, or that lose data, get fixed first. Cosmetic issues wait.

Common mistakes

Vague titles like "bug" or "doesn't work".
Missing starting state, so developers cannot reproduce it.
Several bugs in one report.
Opinions instead of facts in the actual result.
No environment, especially for layout bugs that only happen at one screen size.
Screenshots without marking, so nobody knows what to look at.
Inflated severity. If everything is critical, nothing is.

What makes developers fix bugs faster

Clear reproduction steps and a recording. A bug that can be reproduced on the first try gets fixed; a bug that needs three rounds of questions waits. A copy-ready version is on the bug report template page.

Writing bug reports manually vs with an AI beta tester

Writing good reports by hand takes discipline, and most beta testers and busy teams skip parts of it. betatest.ing's AI beta tester files every finding in this format by default: title, steps to reproduce, expected vs actual, environment, severity with a reason, an annotated screenshot and, when useful, a screen recording and the console errors. It does this the same way on every run, including scheduled smoke and regression tests, so reports stay consistent across releases.

It reports what it can observe in a real browser or on test devices. Bugs that depend on real-world conditions such as a flaky network, camera, location, push notifications or real payments still need reports from people, and so does feedback about whether the product is worth using.

The test task

What you send your AI beta tester. It works out the steps and tests like a real user.

I have a bug I cannot describe well on [YOUR APP URL]: [WHAT YOU SAW, IN YOUR OWN WORDS]. Reproduce it: start from a clean, logged-out state (then use the saved test login if needed), find the shortest sequence of steps that triggers it, and try it on desktop and at phone width. Record the reproduction and capture the console errors and failed requests. Then file one finding per distinct bug in this format: a clear title (area, symptom, condition), numbered steps to reproduce, expected result, actual result with exact error text, environment (browser, viewport, account), severity with a one-line reason, frequency, an annotated screenshot of the broken state and the recording. If you cannot reproduce it, tell me what you tried.

Fill in your details

Here, or later in the chat with your tester.

[YOUR APP URL] Where the bug happens.
[WHAT YOU SAW, IN YOUR OWN WORDS] e.g. "sometimes the save button spins forever on the settings page".

What the AI beta tester checks

The shortest steps that trigger the bug
Whether it happens on desktop, phone width, or both
Logged-in versus logged-out behavior
Console errors and failed requests at the moment it breaks
Whether it is one bug or several
Frequency: always or intermittent

What you get

A developer-ready bug report with steps and expected vs actual
An annotated screenshot of the broken state
A screen recording of the reproduction
Console errors and environment details

How to run it with betatest.ing

Add your app as a project with a test login.
Describe the bug in your own words in the task and send it.
Forward the finding to your developer or tracker.
Ask the tester to re-test once the fix is deployed.

Tips

Start every report from a known state, such as a URL and an account.
One bug per report; split combined issues.
Include exact error text, not a paraphrase.
A short recording often replaces a page of explanation.

How to write a bug report: FAQ

What should a bug report include?

A clear title, steps to reproduce, expected and actual result, environment, severity, frequency and evidence such as a screenshot, recording and console errors.

What makes a bug report good?

A developer can reproduce the bug on the first try without asking questions.

How do I write steps to reproduce?

Start from a known state, number each step, include the exact data you entered, and remove any step that is not needed to trigger the bug.

Should I report several bugs together?

No. File one report per bug so each can be prioritized, fixed and verified on its own.

What is the difference between severity and priority?

Severity is how badly the bug affects users; priority is how soon the team will fix it. A minor bug on the pricing page can still be high priority.

How do I report a bug I can't reproduce?

File it anyway, but say clearly that it happened once or intermittently. Include everything you remember: the time, what you were doing just before, the environment, and any screenshot or error text. A recording or console log from the moment it happened is the most useful evidence.

Should I include screenshots or a video in a bug report?

Include a screenshot with the problem marked for almost every bug. Add a short screen recording when the bug involves several steps, animation or timing. Remove any passwords or personal data before attaching them.

How long should a bug report be?

As short as possible while still letting someone reproduce the bug without asking questions. Usually that is a clear title, a few numbered steps, expected and actual results, the environment and evidence. Leave out the story of how you found it unless it matters.

Related beta testing guides

Bug report template — A good bug report lets a developer reproduce the problem on the first try. This template has every field that matters and nothing extra. Give it to your beta testers, or ask your AI beta tester to file every bug in exactly this format.
Bug severity levels — A shared severity scale lets beta testers, developers and product managers agree on how bad a bug is in seconds. Here is a simple four-level scale with examples, plus how severity differs from priority.
How to run a beta test — A beta test works when it has a goal, the right testers, a way to collect bugs and a clear finish line. Here is a practical step-by-step process you can follow for a website, web app or mobile app.
Broken links checker — Broken links and JavaScript errors are cheap to fix and expensive to leave: they break flows, hurt trust and waste crawl budget. This page shows what to collect, how to group it, and a task your AI beta tester can run across your site.
Free tool: Bug report generator — Clean bug reports with steps, expected vs actual and environment, formatted for GitHub, Jira or Linear.