# How to Write a Bug Report Developers Can Reproduce (With Examples)

> How to write a bug report a developer can reproduce on the first try: fields, good and bad bug titles, steps-to-reproduce examples and a copy-paste template.

Source: https://qa.tech/blog/how-to-write-a-bug-report · Published: 2026-11-16

---
A good bug report lets someone who wasn't there reproduce the bug without asking you a single question. That takes a specific title, the environment, numbered steps from a known starting state, what you expected against what happened, and evidence such as a screenshot, console errors or a failed network request. Add impact and frequency so it gets the right priority.

Below: how to write a bug report field by field, bug title examples, a full bug report example with steps to reproduce, and a bug report template you can paste into Jira, Linear or GitHub.

## Why steps to reproduce matter most in a bug report

A 2010 study of Apache, Eclipse and Mozilla still holds up on what developers need from a bug report. [Zimmermann and colleagues](https://thomas-zimmermann.com/publications/files/zimmermann-tse-2010.pdf) surveyed experienced developers and reporters on those projects and, after discarding inconsistent answers, analysed 130 developer and 215 reporter responses (IEEE Transactions on Software Engineering, 2010). Steps to reproduce stood out clearly as the most important item, followed by stack traces and test cases.

The same paper compared what developers rated as important with what reporters actually put in their reports. The correlation was 0.035, close to none. Yet when asked what developers needed, reporters gave answers that matched the developers' ranking closely (0.839). They supplied observed and expected behaviour and steps to reproduce, and only a few added stack traces, code examples or test cases, the last being the item the paper found hardest to provide.

Our own customer conversations point the same way. Teams describe bugs passed around in Slack threads, tickets that say what broke but not how, and fixes that wait days while someone asks for more detail. In those stories the delay sits before anyone touches the code, while the developer is still trying to make the bug happen on their own machine.

## The fields of a good bug report

### Title

The title is what people scan in a backlog, so it carries the most information per word. Name where it happens, what goes wrong and under what condition. Leave out "broken", "doesn't work" and "issue", which tell the reader nothing.

### Environment

Which app, which build or version, which environment (staging, production, a preview URL), which browser or device, and which account or tenant. That last one is easy to skip. In B2B products some bugs only show up under one customer's configuration, and a developer logged in as a generic test user won't see them.

### Steps to reproduce

Numbered, one action per step, starting from a state the reader can recreate. Include the test data you used: the email, the product, the discount code. If the bug only happens sometimes, say how many times out of how many tries.

### Expected and actual result

Write both, in plain words, as two separate lines. "Expected: total drops to $45.00 after applying SAVE10. Actual: total stays at $50.00." The expected line is where disagreements surface early, because sometimes the reporter's expectation is the bug.

### Evidence

A screenshot of the moment it went wrong, and a short video if the bug involves movement or timing. For web apps, add console errors and the failing network request, with its status code. A single 422 from the API can be the whole diagnosis. An engineering lead on one of those calls wanted video for a different reason: many of the people reading his team's bug reports aren't technical, and a recording shows them what a written description of a UI control can't.

### Impact and frequency

Who's affected, how badly, and how often. "Every user on Safari, at checkout, every time" gets a different priority from "one admin, once, after a timeout".

## Bug title examples

| Bad title | Better title |
|---|---|
| Checkout broken | Checkout: Pay button stays disabled after entering a valid card on Safari 26 |
| Login issue | Login: SSO users get a blank page after the Okta redirect on staging |
| Search doesn't work | Search: results ignore the "in stock" filter when sorting by price |
| App crashes | Notifications: app closes when opening a notification while offline on Android 15 |
| Discount wrong | Cart: SAVE10 code accepted but total not reduced for logged-out users |
| Export bug | Reports: CSV export drops rows after 1,000 for accounts in the EU region |
| Page slow | Dashboard: first load takes 20+ seconds for workspaces with over 50 projects |
| Email not sent | Invites: invite email not sent when the inviter's own email is unverified |

These are made-up examples that follow one pattern: area, then what goes wrong, then the condition that triggers it.

## Bug report example with steps to reproduce

Here's a full report for the discount bug from the table.

**Title:** Cart: SAVE10 code accepted but total not reduced for logged-out users

**Environment:** staging (build 2026.11.14-3), Chrome on macOS, logged out, US store

**Steps to reproduce:**
1. Open the staging store in a private window, without logging in.
2. Add "Canvas tote bag" ($50.00) to the cart.
3. Open the cart and enter SAVE10 (10% off) in the discount field.
4. Click Apply.

**Expected:** a confirmation that the code was applied, and the total drops to $45.00.

**Actual:** the confirmation appears, but the total stays at $50.00. Reproduced 3 out of 3 times. Logged-in users get the discount.

**Evidence:** screenshot after step 4; `POST /api/cart/discount` returned 200 with `discount: 0` in the response; no console errors.

**Impact:** every guest checkout that applies SAVE10; other codes not tested yet. Guest checkout is the default path from paid ads.

Notice what the steps leave out: how you found the bug, what you were testing at the time, your theory of the cause. If you have a theory, add it below the evidence and label it as one.

## A bug report template

```markdown
**Title:** [Area]: [what goes wrong] [condition]

**Environment:** [app/build] · [staging / production / preview URL] · [browser or device + version] · [account, role or tenant]

**Steps to reproduce:**
1.
2.
3.

**Expected result:**

**Actual result:** (how often: X of Y attempts)

**Evidence:** screenshot or video · console errors · failed network requests (method, URL, status)

**Impact:** who is affected, how badly, how often

**Notes:** workaround, first seen, related tickets, your theory (labelled as a theory)
```

In Jira, the title goes in Summary, environment can go in the Environment field if your project uses it, and the rest goes in Description with screenshots as attachments. Linear and GitHub Issues take the same structure as Markdown.

## Mistakes that send a report back

**No starting state.** "Go to the settings page and change the plan" depends on who you're logged in as, which plan you're on and what's already configured. Spell it out, or link the test account.

**Two bugs in one report.** If you found two problems, file two reports and link them. A ticket with two bugs in it can easily be closed when only one of them is fixed.

**Evidence that never made it into the tracker.** Some trackers handle video badly, and a screenshot pasted into a Slack thread can easily stay there. Attach evidence where the developer will actually work on the bug.

**Writing for yourself.** The reader may be a developer in another time zone, a product manager or a coding agent picking up the ticket. Use the product's own names for things, and skip your personal shorthand.

## When the reader is a coding agent

Some teams now hand bug tickets straight to a coding agent, and an agent is a literal reader that can't walk over and ask what you meant. It leans hardest on a clear expected and actual result, a reproducible starting state and evidence it can fetch. Those are the same fields covered in [what a coding agent needs from a failing test](https://qa.tech/blog/what-coding-agents-need-from-failing-tests), and they carry over to a bug report unchanged.

## Bug reports written by a testing agent

A testing agent that finds a bug can also write the report, and it starts with every step it took already recorded. Its report only covers what happened in the page. A 500 that the frontend swallows never makes it in, and failed network requests go into the run logs for debugging instead of becoming issues of their own. The agent also tests web apps in Chromium alone, so the Safari checkout bug from the title table would never get a report, and errors that stay on the server still show up in a tool like Sentry, not here.

When a test fails in [QA.tech](https://qa.tech/product/pr-testing), an AI testing platform, the failure becomes an issue. You choose which issues to export to Jira, Linear or Trello (nothing syncs automatically), and the exported ticket carries a summary, the test's intent, the steps the agent took, what went wrong, the evaluator's notes, evidence such as screenshots and console details, and a link back. Its title is prefixed with the issue's short ID, as in `[iss_abc] Login button stays disabled`, so you can trace it to the run.

[Vilhelm von Ehrenheim](https://www.linkedin.com/in/vilhelm-von-ehrenheim/), co-founder and Chief AI Officer, has been steering the product toward proof points and bug reports as the output of a run, with the red or green status as the summary on top.

Anything from outside the run, such as the customer who complained about the bug last week, still has to be added by a person.

## FAQ

**What information should a good bug report include?**
A specific title, the environment (build, environment, browser or device, and account), numbered steps to reproduce from a known starting state, the expected and actual result, and evidence such as a screenshot, console errors or a failed network request. Add impact and how often it happens.

**How do you write steps to reproduce?**
Start from a state the reader can recreate, such as "logged out, empty cart". Write one action per numbered step, include the exact data you entered, and stop at the step where the bug appears. If it doesn't happen every time, say how many times out of how many attempts.

**What makes a good bug title?**
It names the area, what goes wrong and the condition that triggers it, for example "Checkout: Pay button stays disabled after entering a valid card on Safari 26". Avoid vague words such as "broken" or "issue".

**Should a bug report include a video?**
Include one when the bug involves movement, timing or several steps that are hard to describe. For a static problem, a screenshot of the moment it went wrong is enough. Either way, attach it to the ticket rather than leaving it in a chat thread.

**How do you write a bug report in Jira?**
Put the bug title in Summary, choose the Bug issue type, fill in Environment if your project uses that field, and put steps to reproduce, the expected and actual result and impact in Description. Attach screenshots and logs to the issue.

**What's the difference between a bug report and a defect report?**
In practice nothing. Both describe a problem in the software so someone can reproduce and fix it. Some teams use "defect" for problems found in testing and "bug" for problems found in production, but the fields are the same.
