How to Write a Bug Report

Anatomy of a bug report

Teams use different tools (JiraJiraA popular tool for tracking bugs, user stories and tasks.Open in glossary →, Azure DevOps, Linear, GitHub Issues, even a spreadsheet), but good bug reports contain the same building blocks.

Writing a great title

The title is the most-read part of your report. It shows up in lists, search results, sprint boards and notification emails. Many people will only ever read the title, so it has to work on its own.

Use the formula Where + What + When:

A few rules of thumb:

• Describe the symptom, not your guess at the cause. “Pay button stays disabled” is a fact. “Card validation regex is wrong” is a guess, and it might be wrong.
• Skip “Bug:” and “Issue with”. Everyone knows it’s a bug; it’s in the bug tracker.
• Keep it under about 100 characters. Details go in the description.
• No capitals, no exclamation marks. Urgency belongs in the priority field.

Try it yourself:

Steps, expected and actual

These three fields are where most reports fall apart.

Steps to reproduce

Write steps as if the reader has never opened the app. Start from a known state (that’s what preconditions are for), use one action per step, name the exact buttons, and give the exact data.

Expected vs actual

Expected is what should happen. Point to the requirement if there is one. Actual is what did happen, described as precisely as a camera would.

“Doesn’t work” could mean the app crashedCrashWhen an app suddenly closes or stops working because of an unhandled error.Open in glossary →, froze, showed an error messageError messageText that tells the user something went wrong and, ideally, how to fix it.Open in glossary →, or did nothing. Each of those points to a completely different cause.

One bug per report

It’s tempting to save time by listing everything you found in one ticket. Don’t.

If two bugs seem connected (for example, the same error appears in two places), file them separately and link them. Let the developer decide whether it’s one cause.

Severity vs priority

These two fields sound similar, and confusing them is one of the most common beginner mistakes (and a very common interview question). Here’s what you need for writing reports; the in-depth lesson, with a triage practice board, is Severity vs Priority.

• SeveritySeverityHow much damage a bug does to the product or the user.Open in glossary → describes the impact on the product or user. It’s mostly a technical judgment, and testers usually suggest it.
• PriorityPriorityHow soon a bug should be fixed, based on business needs.Open in glossary → describes the order of fixing. It’s a business decision, usually made by the product owner or lead.

Typical severity levels (scales vary by team):

The four combinations

Because they measure different things, every combination is possible:

Reproducibility

Before you file, follow your own steps again. Then write down how often the bug happened:

• 5/5 attempts (always): great, the developer will see it straight away.
• 3/5 attempts: intermittent. Still very useful; say so honestly.
• 1/10 attempts: rare. Report it anyway, with every detail you have and a recording of the time it happened.

A bug you can reproduce every time is reproducibleReproducibleA bug that happens again every time you follow the same steps.Open in glossary →. Bugs that come and go often point to timing problems such as a race conditionRace conditionA bug that depends on the timing or order of events, so it only happens sometimes.Open in glossary →, slow networks, or leftover data in the cacheCacheStored copies of data or files that make apps and websites load faster.Open in glossary →, so the number itself is a clue for the developer.

Gathering evidence

Evidence turns “I saw something weird” into a fact nobody can argue with. Aim for at least one visual (screenshot or recording) and, when you can, logs.

adb logcat -c                 # clear old logs
# ...now reproduce the bug on the phone...
adb logcat -d > bug-log.txt   # save everything logged so far to a file
adb logcat '*:E'              # or: watch only errors, live (quotes stop zsh from expanding *)

Isolating the bug

Finding a bug is step one. Narrowing it down is what makes you a tester developers love. Spend a few minutes asking “does it still happen if…?” Each answer goes into the Notes section of your report.

Don’t overdo it, though. If the bug is clearly serious, report it quickly with what you have, and add findings as comments.

How to write a bug report, step by step

Worked example

Here’s the bug from the start of this lesson, written up properly. Notice how it answers every question before a developer has to ask.

The bug life cycle

Once you file a report, it moves through a series of statuses called the bug life cycleBug life cycleThe statuses a bug goes through, from New to Closed.Open in glossary →. Exact names vary by team and tool, but the idea is the same everywhere. For every status, who moves the bug and a hands-on ticket simulator, see the Bug Life Cycle lesson.

Your job doesn’t end when you click Create. Watch your tickets, answer developers’ questions quickly, and when a bug reaches Retest (many teams call it Ready for test), verify it on a build that contains the fix. While you’re there, check the features around it too; fixes sometimes break neighbors, which is why teams also run regression testingRegression testingRe-running tests to check that new changes didn't break things that used to work.Open in glossary →.

Tone: factual, no blame

Bug reports are read by people who worked hard on the feature. A report that sounds like an accusation makes everyone defensive and slows the fix down. You’ll also be working with these developers every day.

• Describe the product, not people. “The button stays disabled”, not “you broke the button”.
• Stick to observations. Leave out sarcasm, guesses about who’s at fault, and words like “obviously” or “again”.
• Be humble about causes. “This might be related to…” is fine; “the developer forgot to…” is not.
• Say thanks when a bug is fixed. It costs nothing and builds trust.

Jira tips

JiraJiraA popular tool for tracking bugs, user stories and tasks.Open in glossary → is the most common bug tracker you’ll meet. A few habits make your reports much easier to work with:

• Choose the issue type “Bug”, not Task or Story, so it shows up in bug filters and reports.

• Search before you create. Use the search bar, or JQL (Jira’s query language), for example:

  project = SHOP AND type = Bug AND text ~ "pay button" AND statusCategory != Done

• Use the fields your team uses: Affects version (where you found it), Component, Labels, Environment, Priority. Consistent fields make dashboards and filters work.

• Link related tickets with “relates to”, “is blocked by” or “duplicates”, and link the bug to the story it belongs to.

• Format for readability. Use numbered lists for steps and code blocks for error messages and log snippets.

• Drag and drop attachments straight into the ticket, and give them meaningful names (pay-button-disabled.mp4, not IMG_4821.MOV).

• @mention people only when you need their attention, and watch your own tickets so you see questions.

• Use a template. Many teams keep a bug description template with the headings Environment, Preconditions, Steps, Expected, Actual, Notes. If yours doesn’t, suggest one.