How to write a website bug report developers can reproduce

A useful website bug report states where the problem occurs, the steps that trigger it, the expected result, the actual result, and the conditions under which it happened. Add a focused screenshot or recording when it helps. The report should let another person repeat the experience and recognise the failure without needing to interview you first.

You do not need to identify the technical cause. “The request appears to fail after I select a delivery option” is useful evidence. “The database is definitely broken” is a diagnosis that may be wrong. Describe what you observed and let the investigation establish the cause. A bug wearing a database-shaped hat is still not proof that the database did it.

Begin with a precise title

A title should identify the affected action and the visible failure. “Contact form shows no confirmation after submission” is better than “Form broken.” “Mobile menu closes before a submenu can be selected” is better than “Urgent website issue.” A clear title helps the team search, identify duplicates, and assign the report to the right person.

Avoid including several independent defects in one title. If the form does not submit and a photograph is stretched, create separate reports. They may have different causes, priorities, and owners. Keep related symptoms together when they belong to the same sequence, such as a failed submission followed by an incorrect success message.

Do not rely on urgency words to communicate impact. Explain whether the issue blocks a purchase, prevents an enquiry, affects only a secondary page, or has a reasonable workaround. The project lead can use that information to set priority consistently across the whole queue.

Record the starting conditions

Include the page URL and the environment: production, staging, or a local preview. Identify whether you were signed in and which general role you were using. Do not include credentials or session tokens. If a test account is required, refer to the approved test-account process instead of placing access details in the report.

Record the browser, operating system, and device when relevant. For a visual issue, include the approximate viewport or a screenshot that preserves its dimensions. For an intermittent issue, note the time and whether it happened on a slow or unstable connection. These details help establish a pattern without claiming certainty about the cause.

Mention prerequisites that are easy to miss. A basket may need to contain two items. A form may require a particular option. A page may behave differently after navigating from another screen. Reproduction steps that begin halfway through the real sequence can make a genuine problem appear impossible to reproduce.

Write short, numbered steps

Each step should describe one action. Start from a state another person can reach, such as opening a named page while signed out. Include the specific selections or sample values needed to trigger the failure. Use safe test data and avoid real customer information unless the team's approved process requires it.

• Open the contact page while signed out.
• Choose “Commercial project” from the enquiry type list.
• Enter the supplied test details in the required fields.
• Select the consent checkbox and press “Send enquiry.”
• Observe the button state and the message below the form.

This sequence is easier to follow than a paragraph describing everything that happened during a fifteen-minute session. Remove unrelated actions, but do not omit a step simply because it seems obvious. If refreshing or revisiting the page changes the result, include that observation separately.

Separate expected and actual results

State what should have happened based on the agreed requirement or the interface's promise. For a contact form, the expected outcome may be a confirmation message and a recorded enquiry. For a navigation link, it may be the correct destination. If the expected behaviour is uncertain, label the report as a question rather than treating a personal assumption as a defect.

Then describe the actual result. Quote the visible error message accurately when it is safe to do so. Explain whether the page froze, returned to an earlier state, showed a spinner indefinitely, or completed the action without confirmation. These are different failures and may require different investigations.

Avoid inferring invisible outcomes. If you cannot see whether a message reached the server, say that the interface did not confirm delivery. A developer can inspect authorised logs or test records. Reporting only what you can verify keeps the evidence reliable and prevents an investigation from starting with a false premise.

Add evidence that answers a question

Attach a screenshot when it clarifies location, layout, or a visible error. Use a short recording when timing or a sequence matters. Include enough context to identify the page, but remove unrelated private information. An attachment should support the written report rather than force the recipient to decode the entire problem from a video.

For visual bugs, annotate the affected region and explain the expected layout. For example, “The error text overlaps the submit button at this width.” Do not cover the problem with the marker. If the screenshot comes from a capture tool, confirm the same issue occurs in the actual browser so you do not report a capture artifact as an application defect.

Technical details such as console messages can be helpful, but review them for sensitive data before sharing. Do not paste entire logs indiscriminately. Provide the relevant message and the time of the action, then allow the authorised developer to investigate further in the appropriate environment.

Report frequency and workarounds honestly

Say whether the problem happens every time, sometimes, or only once so far. If you tested it three times and saw it twice, report that observation without turning it into a broad statistical claim. Intermittent bugs are still real, but the team needs to know the limits of the evidence.

Record any workaround. A user may be able to complete the action after refreshing, choosing another browser, or taking a different route. A workaround helps assess urgency and can assist support while the underlying issue is investigated. It should not become a reason to dismiss a problem that affects the normal expected journey.

Do not repeatedly submit transactions or forms containing real data merely to reproduce a bug. Use an approved test environment or coordinate with the owner. Reproduction should not create duplicate orders, send unwanted messages, or change production data without a clear plan.

Distinguish severity from priority

Severity describes the effect of the failure. Priority describes when the team should work on it. A defect that blocks all enquiries may be severe and urgent. A visual problem on a rarely visited page may be less urgent. A minor typo in a scheduled campaign can still have a high delivery priority because of its timing.

Agree simple categories with the team. For example, a blocker prevents a core task, a major issue significantly degrades it, and a minor issue has limited impact with an acceptable workaround. Avoid using elaborate labels that reviewers interpret differently. The explanation of impact matters more than the label itself.

Let the responsible project owner make the final priority decision when several issues compete for attention. A reviewer should provide evidence and business context, not silently assign every report to the highest category. If everything is a fire, the team eventually starts treating the alarm as background music.

Keep clarification in the same thread

When a developer asks for more information, reply where the report lives. Add the missing device, sample input, or reproduction detail to the existing conversation. Separate email replies and chat messages are easy to lose, particularly when someone else takes over the investigation.

JotPins can keep the page annotation, discussion, and revision progress together. Use the note to identify the affected element and the conversation to refine the report. Do not claim a problem is fixed solely because a status changed. The person implementing the change should explain what was updated and where it is available for verification.

If two reports describe the same underlying problem, connect them while retaining useful differences. One may show the issue on mobile and another on desktop. Merging should reduce duplicate work without deleting evidence about affected conditions. A similar-looking symptom can also have a different cause, so let investigation guide that decision.

Verify the fix and check nearby behaviour

Repeat the original reproduction steps against the updated version. Confirm the expected result, then check a nearby valid case and an invalid case. For a form validation fix, test both a complete submission and a missing required field. For a menu fix, check opening, selecting an item, closing, and returning to the page.

Record the version or deployment used for verification. If the problem persists, explain whether the result is identical or has changed. New evidence can narrow the investigation. Avoid simply replying “still broken” when a brief description would show that the original failure is fixed but a different issue remains.

Close the report when the agreed outcome is verified, or document an accepted limitation with the appropriate owner. Keep unresolved defects visible. A tidy issue list is not a useful goal if it hides problems that users will encounter immediately after launch.

A copyable report structure

Title: name the action and failure. Location: provide the page and environment. Conditions: describe the device, browser, account state, and relevant prerequisites. Steps: list the actions in order. Expected: state the agreed successful behaviour. Actual: describe the observed result. Evidence: attach a focused image or short recording. Impact: explain the blocked task and any workaround.

Use this structure as a prompt, not a bureaucratic form. A simple defect may need only a few lines. A difficult intermittent problem deserves more detail. The aim is to reduce uncertainty while respecting the time of both the reporter and the person investigating.

Frequently asked questions

Can nontechnical clients report useful bugs?

Yes. Accurate observations, clear steps, and an explanation of the expected result are more valuable than technical guesses. A client can describe what prevented an enquiry or purchase without knowing how the application is built. The developer's role is to investigate the cause.

What if I cannot reproduce the issue again?

Record the original conditions, approximate time, visible result, and any evidence you already have. Say clearly that it happened once and has not repeated. Do not invent missing steps. The report may still help when combined with other observations or authorised diagnostic information.

Should every bug include a video?

No. Use the lightest evidence that explains the problem. A screenshot is often sufficient for a layout defect, while a recording helps with timing or complex interactions. Always include a written summary so the report remains searchable and understandable without watching the attachment.

Who should confirm that a bug is fixed?

The implementer should check the technical change, and an appropriate reviewer should verify the original user outcome. On a small project, those checks may involve the same people working closely. What matters is that closure reflects tested behaviour rather than an assumption.