How to Write a Bug Report Developers Can Reproduce

How to Write a Bug Report Developers Can Reproduce — original editorial illustration
Original AI-assisted illustration.

A useful bug report lets another person recreate an observed problem and compare it with an agreed expectation. You do not need to diagnose the code to write one. You do need a clear starting point, precise actions, the observed result and enough context to repeat the experiment.

The example below uses a fictional task-management application. It contains no claim about a real product.

Start with a title that describes the failure

“Export does not work” leaves too much unanswered. “Completed-task CSV export excludes tasks closed today” tells the reader the affected feature and the visible failure. Keep the title factual. A suspected database issue belongs in a clearly labelled investigation note, not in the title as an established cause.

Check for an existing report before creating a duplicate. If a related issue exists, add genuinely new evidence or explain why this case differs.

Record the starting conditions

State the build or release, environment, browser or device version when relevant, user role, important settings and sample data. Include the observation time and time zone if the failure may depend on dates or background processing.

Use synthetic records or approved test data. Remove tokens, personal information and unrelated customer details from screenshots and logs. A report should provide enough context to investigate without exposing information the reader does not need.

Four-step framework for How to Write a Bug Report Developers Can Reproduce
Illustrative framework; adapt to your team and agreed requirements.

A worked report you can adapt

Title: Completed-task CSV export excludes tasks closed today.

Environment: fictional staging build 2.4.0; desktop browser; project-member role.

Precondition: project DEMO contains three completed tasks. Two were closed yesterday and one today, using the project’s configured time zone.

Steps: open DEMO; select the Completed filter; confirm all three tasks are visible; export the filtered results as CSV; open the downloaded file.

Expected: the export contains the same three tasks shown by the filter, under the agreed export requirement.

Actual: the file contains only the two tasks closed yesterday. The task closed today is missing.

Frequency: observed in three attempts with the same synthetic data. This does not establish behaviour in every environment.

Evidence: attach a redacted screenshot of the filter and a sample export, with the relevant synthetic task IDs marked.

Separate observation from explanation

The missing row is an observation. “The server uses the wrong time zone” is a hypothesis until investigated. Keeping them separate helps the developer test alternative explanations such as filter logic, stale data or export timing.

Reference the requirement that supports the expected result. If no agreed behaviour exists, describe the uncertainty and ask for a product decision. A disagreement about an undocumented rule may need clarification before it can be classified as a defect.

Explain impact without guessing priority

Describe who is affected, what task is blocked, how frequently the issue was observed and whether a workaround exists. Severity describes the effect; priority concerns the order in which work is addressed. Teams use different scales, so apply your team’s definitions.

For the fictional export problem, write “a project member cannot reconcile today’s completed tasks using this export.” Do not claim that all users lose data when the evidence only shows a missing export row in staging.

A reusable report template

Summary:

Build and environment:

Role and relevant settings:

Preconditions and synthetic data:

Numbered steps:

Expected result and requirement:

Actual result:

Observed frequency:

Impact and workaround:

Evidence and related issues:

Keep one report focused on one problem unless several symptoms clearly belong to the same failure. Before submitting, follow your own steps from a fresh starting state and ask whether a colleague could do the same.

Sources and method

Reference: Atlassian’s bug report template guidance covers environment, reproduction steps and expected versus actual results. The fictional case and reporting advice here are illustrative.

Related reading

How to choose test management software for a small QA team · Software testing guides · Software buying guides

Prepared with AI assistance. Worked examples are fictional unless stated otherwise.

Comments

Popular posts from this blog

Acceptance Criteria Examples: Turn Vague Requirements into Testable Outcomes

How to Choose Test Management Software for a Small QA Team