How to Write a Good Bug Report

A bug report is not only a note that something is broken.

At least, a good one is not.

A good bug report is a piece of communication between QA, development, product and sometimes support. It explains what happened, where it happened, how to reproduce it, what should have happened instead and why the issue matters.

That sounds simple, but in real teams this is where a lot of time gets lost.

A tester finds a bug. A developer opens the ticket. Something is missing. The environment is unclear. The steps are too vague. The expected result is not explained. There is no screenshot, no video, no logs and no account details.

Then the conversation starts:

• Can you reproduce it again?
• Which browser was this?
• What user role did you use?
• What exactly did you expect?
• Is this staging or production?
• Can you send a video?

That back-and-forth may look small, but repeated across a release it becomes expensive.

A clear bug report reduces that friction.

A bug report should help someone act

The purpose of a bug report is not to prove that QA found something. The purpose is to help the team understand and act.

That means the report should answer a few basic questions:

• What is broken?
• Where is it broken?
• How can someone reproduce it?
• What actually happened?
• What should have happened?
• How serious is it?
• What evidence supports the finding?
• What environment was used?

If a developer can open the ticket, follow the steps and see the same issue without asking extra questions, the report is already doing its job.

This is why bug reporting is part of good QA, not just administration. The quality of the report affects how quickly the issue can move from discovery to fix.

Start with a clear title

The title is the first thing people see in an issue tracker, so it should be specific.

A weak title says Login bug.

A better title says User is redirected to blank page after login with expired session.

The second title gives context immediately. It tells the reader what area is affected, what action happened and what the visible problem is.

A good bug title should usually include the affected feature and the main failure. It does not need to be long, but it should be useful.

For example:

• Checkout button stays disabled after valid card details are entered
• Admin user can open deleted team invite link
• API returns 200 when required email field is missing
• Mobile menu overlaps checkout form on iPhone SE

These titles are much easier to scan during triage than vague labels like Issue, Bug, Not working or Broken flow.

Explain the problem in plain language

After the title, the report should briefly explain what the issue is. This does not need to be a long essay. A few clear sentences are usually enough.

For example:

When a user with an expired session submits the profile form, the app redirects to a blank page instead of showing a session expired message or sending the user back to login. This blocks the user from completing the profile update and may look like the application has crashed.

That gives the reader context. It explains the behaviour and why it matters.

The description should be factual. It is fine to mention a likely impact, but avoid guessing too much about the root cause unless you have evidence.

A bug report should separate observation from assumption. The user is redirected to a blank page is an observation. The auth token refresh is broken may be true, but unless you confirmed it, it is a guess.

Write steps to reproduce that someone can actually follow

The steps to reproduce are often the most important part of the bug report.

Good steps should be clear, ordered and specific. They should start from a known state and lead the reader to the bug without unnecessary noise.

Weak steps:

Log in and try to update profile. It breaks.

Better steps:

• Open the staging environment.
• Log in as a standard user.
• Go to Account Settings.
• Change the phone number field.
• Wait until the session expires or use an expired session token.
• Click Save changes.
• Observe the result.

The second version gives the developer something they can follow.

Good reproduction steps should include relevant data when needed. If the issue only happens with a specific user role, account state, plan type, browser, currency, product ID, API payload or permission level, include it.

At the same time, do not add twenty steps if only five are needed. Too many unnecessary steps make the report harder to use.

The goal is simple: another person should be able to reproduce the issue without needing the tester beside them.

Clearly separate actual result and expected result

A bug report should always explain both what happened and what should have happened instead.

Actual result describes the observed behaviour.

Expected result describes the correct behaviour.

For example:

• Actual result: After submitting the form, the user is redirected to a blank page and no error message is shown.
• Expected result: The user should see a clear session expired message and be redirected to the login page.

This difference matters because developers cannot always know what the tester expected.

Sometimes the system behaves exactly as coded, but the product expectation is different. Sometimes the expected result is not documented clearly. Sometimes QA finds a requirement gap rather than a pure implementation bug.

Writing the expected result forces the team to clarify the intended behaviour.

If the expected result is based on a requirement, design, API contract or previous product behaviour, link it or mention it. That makes the report stronger.

Add the environment details

A bug is much easier to investigate when the environment is clear.

Depending on the product, environment details may include:

• Environment: staging, review app, production, testnet or local build
• Browser and version
• Device and operating system
• App version or build number
• User role or account type
• Test account used
• API endpoint or request payload
• Feature flag status
• Network condition, if relevant
• Date and time of occurrence

Not every bug needs every detail. A typo in a button label does not need the same environment detail as an intermittent payment issue.

But if the issue may depend on browser, device, role, data state or environment, include that information.

Environment details prevent one of the most common problems in bug triage: I cannot reproduce it.

Sometimes the bug is real, but only in one browser. Sometimes it only happens with old data. Sometimes it appears only in staging because a configuration is missing. Without environment details, the team has to guess.

Include useful evidence

Evidence helps people understand the issue faster.

For UI bugs, a screenshot may be enough. For flow bugs, a short screen recording is often better. For API bugs, include request and response details. For frontend bugs, console errors may be useful. For backend issues, logs, timestamps or correlation IDs can save a lot of time.

Good evidence can include:

• Screenshot with the issue clearly visible
• Short video showing the reproduction flow
• Browser console errors
• Network request and response
• API payload
• Server error message
• Logs or trace IDs
• Related ticket, requirement or design link
• Before and after comparison if behaviour changed

Evidence should support the report, not replace it.

A video alone is not enough if the steps are unclear. A screenshot alone is not enough if nobody knows how the user reached that state.

The best reports combine clear written information with useful proof.

Explain impact, not drama

Severity and priority are often confused.

Severity is about how bad the issue is for the product or user. Priority is about how soon the team should fix it.

A spelling mistake on the homepage may be low severity but high priority if a marketing campaign goes live today. A rare crash in an internal admin flow may be high severity but lower priority if only one test user can trigger it in a non-production environment.

A good bug report should help the team understand impact.

Instead of writing This is critical!!!, explain the actual risk.

For example:

This blocks all standard users from completing checkout in staging. The issue appears on Chrome and Safari and reproduces every time with valid card details.

That is more useful.

Impact can include user blocking, revenue risk, data risk, security risk, broken core flow, customer confusion, compliance concern, support load or release risk.

The clearer the impact, the easier prioritisation becomes.

Mention frequency and reproducibility

Some bugs happen every time. Some happen sometimes. Some are hard to reproduce but still important.

A good report should mention frequency when possible.

For example:

• Reproduces 5/5 attempts on staging.
• Reproduces only on Safari mobile.
• Observed twice during checkout testing, but not yet consistently reproducible.
• Appears after refreshing the page during payment confirmation.

This helps developers understand whether they are dealing with a consistent logic problem, a browser-specific issue, a race condition, a data issue or an intermittent failure.

Intermittent bugs should not be ignored just because they are harder to reproduce. But they need stronger evidence: timestamps, logs, user actions, environment details and anything that helps narrow the cause.

Keep one report focused on one issue

One bug report should usually describe one problem.

It is tempting to group several related problems together, especially when testing one flow. But this often makes fixing, assigning and retesting harder.

For example, these should probably be separate reports:

• Login button is disabled after valid input
• Password reset email is not received
• Error message has the wrong text
• Mobile layout overlaps the input field

They may all relate to authentication, but they are different issues. They may have different causes, different owners and different priorities.

There are exceptions. If several symptoms clearly come from the same root problem, one report may be enough.

But in general, focused reports are easier to manage.

Avoid emotional or vague wording

A bug report should be direct and factual.

Avoid wording like:

• This is completely broken.
• This makes no sense.
• Developer missed this.
• Bad implementation.
• Everything is wrong.

Even when the issue is frustrating, the report should help the team move forward.

Better wording:

• The checkout page does not load after the user selects PayPal as payment method.
• The error message does not explain why the action failed.
• The API allows the request even when the user does not have permission.
• The current behaviour does not match the acceptance criteria.

Clear language creates less friction.

QA is there to protect product quality, not to blame people. A good bug report should be firm when the issue is serious, but still professional.

Add technical context when it helps

A bug report does not need to be overly technical every time. But technical context can be very useful when the issue involves APIs, backend behaviour, logs, permissions or data.

For example, if the UI shows a generic error but the network tab shows a 500 response, include that. If the API returns 200 when it should return 400, include the endpoint and payload. If the frontend blocks a button but the backend still accepts the request, mention both sides.

This is especially useful for API-driven products.

A report like this is much stronger:

UI blocks the Save button when the email field is empty, but the API still accepts the same request when sent directly and returns 200. Expected result: backend should reject the request with a validation error.

That gives developers a clearer starting point.

Technical context should be accurate. If you are not sure, phrase it carefully. It is better to say the network request returns 500 than to guess the database is broken.

Link related information

A bug does not exist in isolation.

If there is a related requirement, design, previous bug, test case, release task, API documentation or discussion, link it.

This helps the team understand context and avoids repeating the same conversation.

Useful links may include:

• Requirement or user story
• Acceptance criteria
• Figma design
• API contract
• Related test case
• Previous similar bug
• Release ticket
• Log dashboard
• Support report
• Customer feedback

Related links are especially useful when a bug is connected to product behaviour rather than an obvious crash.

Good bug report example

Here is a simple example of a clear bug report.

• Title: Standard user can access deleted team invite link
• Environment: Staging, Chrome 126, Windows 11
• User role: Standard user
• Account: test-user@example.com
• Feature: Team invitations
• Description: A standard user can open an old invite link after the invite has already been deleted by an admin. The invite page still loads instead of showing an expired or invalid invite message.
• Steps to reproduce: Create an invite as admin, copy the link, delete the invite, then open the copied link in a new browser session.
• Actual result: The deleted invite link still opens the invite acceptance page.
• Expected result: The user should see an invalid or expired invite message. Deleted invite links should no longer be usable.
• Frequency: Reproduces 3/3 attempts.
• Impact: This may allow access through an invite that the admin intentionally removed. Needs review before release because it affects team access control.
• Evidence: Screen recording and network response attached.

This report gives the developer a clear problem, clear steps, expected behaviour, environment, frequency and impact.

What a weak bug report looks like

A weak version of the same issue would be:

Invite link still works. Please fix.

That may be true, but it creates questions.

• Which invite link?
• Who created it?
• Was it expired or deleted?
• Which user opened it?
• Which environment?
• What should happen instead?
• Does it happen every time?
• Is this a security or permission concern?

A weak report forces the next person to investigate the report before they can investigate the bug.

A good report removes that unnecessary work.

Bug reports are also changing because of AI

There is another reason bug report quality matters now: AI tools and repair agents are starting to work from issue descriptions.

That means a bug report may no longer be read only by a human developer. It may also become the input for an AI-assisted debugging or code repair workflow.

Recent software engineering research suggests that AI repair agents benefit from concrete, well-localised and structured information, such as expected behaviour, affected areas, reproduction scripts, source-code context and fix direction where appropriate.

It also suggests that structure matters: removing headings or flattening report structure can reduce agent performance even when the same information is still present.

This does not mean QA should write bug reports only for AI. Human readability still matters.

But it does mean structured bug reports are becoming even more valuable. A clear report helps both people and tools.

A practical bug report template

A good default template can look like this:

• Title: Short summary of the issue.
• Environment: Environment, browser, device, OS, app version, user role and other relevant setup.
• Description: Brief explanation of the issue and where it happens.
• Steps to reproduce: Numbered steps from a known starting point.
• Actual result: What happened.
• Expected result: What should have happened.
• Frequency: Always, sometimes, rare, or number of attempts.
• Impact: Why it matters for the user, product or release.
• Evidence: Screenshots, video, logs, API responses or links.
• Related information: Ticket, requirement, design, API docs, previous issue or test case.

This template should be adjusted to the team. A small product does not need a huge form for every tiny issue. A regulated product, fintech flow or API-heavy SaaS platform may need more detail.

The best template is the one that captures the information your team actually uses.

Common bug reporting mistakes

One mistake is writing steps that are too vague. Go to settings and save is not enough if the issue depends on a specific field, role or state.

Another mistake is missing the expected result. Without expected behaviour, the developer may not know whether the issue is a bug, a requirement gap or a product decision.

A third mistake is attaching evidence but not explaining it. A video helps, but the written report still needs structure.

Another common mistake is mixing several bugs into one report. This makes triage, assignment and retesting harder.

A final mistake is reporting symptoms without impact. Not every bug is critical, but every useful report should help the team understand why the issue matters.

Good bug reports help teams fix issues faster

A good bug report is not about writing more. It is about writing clearly.

The best reports give developers enough information to reproduce, understand and fix the issue without unnecessary back-and-forth.

That usually means a clear title, focused description, precise steps, actual and expected results, environment details, useful evidence and a practical explanation of impact.

Good bug reports save time. They reduce confusion. They make triage easier. They help QA, developers and product teams work from the same understanding.

Finding a bug is only the first part.

Communicating it well is what helps the team actually fix it.