THE SHORT VERSION
Start before the failure. Describe the setup, repeat the actions that trigger the issue, and separate what you expected from what you observed. Keep the evidence that makes those steps easier to follow.
A useful report gives someone else a starting point. It does not need to guess the root cause.
Capture what was true before the first click.
Before refreshing the page or clearing its data, note the conditions you found it in. A fresh tab may skip the earlier actions that made the issue possible.
- Page & version
- Page URL and app build or deployment, if known.
- Account & test data
- The role, permissions, and sample data needed for the flow. Leave out credentials.
- Browser & display
- Browser version, operating system, and viewport or zoom when relevant.
- State before the first step
- Earlier navigation, selected items, active filters, or an already-open dialog.
In the renewal example, “start with 1 seat” matters. Opening the page with 3 seats already saved would describe a different path.
Write the sequence someone else can follow.
A short report can still be precise. Use the labels your teammate will see on the page, and keep the order of actions intact.
Name the starting point.
Say which page to open and what should already be on it. Include any setup outside the browser.
Write one action per step.
Use the control’s visible label and the value you entered. “Click Calculate renewal” is easier to follow than “check billing.”
Keep the actions that change the state.
A second click, a return from another page, or a changed filter may be the step that makes the bug appear.
Repeat, then shorten the path.
Where it is safe to repeat the action, try the same setup again. Remove steps one at a time and check that the issue still occurs.
For the reporting fundamentals, see Mozilla’s bug-writing guidelines.
Show the first mismatch.
“The renewal is wrong” leaves the reader with work to do. This sample report connects a specific sequence to a result they can compare.
Renewal quote uses 2 seats after adding a third.
Starting point: seat renewal is open with 1 seat.
- Click Add seat. The page shows 2 seats.
- Click Add seat again. The page shows 3 seats.
- Click Calculate renewal.
The quote includes every seat shown on the page.
The quote uses two seats while the page still shows three.
The mismatch is an observation. “The quote might use an earlier seat count” is a hypothesis to investigate, not a confirmed cause.
Explore this recording exampleCopy a report your teammate can work from.
Start with the blank template, or use the filled example to see how the details fit together. Copy it into your issue and replace the placeholders with your observations.
- Summary
- [Action or condition] causes [specific unexpected result].
- Starting state
- Page URL: App build/version: Browser/version and OS: Account role, test data, and any earlier actions:
- Steps to reproduce
- 1. [Open the page in the starting state.] 2. [Perform the first action.] 3. [Continue to the action that exposes the issue.]
- Expected result
- [What should happen after the final step, and why.]
- Actual result
- [What happened instead. Include the exact message or value.]
- Repeat attempts
- [Occurrences / attempts, starting conditions, and what changed between attempts.]
- Evidence & access
- [Reviewed recording or screenshot, relevant moment, selected diagnostics, and who can open the evidence.]
When the bug won’t happen again.
Keep the original observation. A failed attempt to repeat the bug is useful information, but it does not establish that the issue has disappeared.
It works after a refresh.
Write down the path before the refresh: earlier pages, filters, selections, and repeated actions. Try that sequence again in a test environment before reducing it to a fresh-page example.
It happens only sometimes.
Record occurrences and attempts separately. Compare what changed between a passing and failing attempt, including the order of actions and any loading state. Keep unknowns explicit.
Your teammate can’t reproduce it.
Compare the starting state, app build, account permissions, and test data. Then check browser and viewport differences. Change one condition at a time so the comparison remains useful.
Add diagnostics when the UI doesn’t explain enough
For a suspected request failure, open Chrome DevTools → Network before repeating the flow. Turn on Preserve log if navigation clears the requests you need. Attach the relevant request status and timing with the corresponding step.
If you export a HAR, use the sanitized option and still review its contents before sharing. Request URLs and bodies can contain information the default header exclusions do not remove.
Chrome DevTools network referenceInvestigating an automated failure? Start with the test run’s evidence in the flaky Playwright tests workflow.
Read it once as the person receiving it.
Before handing over the issue, check that your teammate has enough context to begin.
- The starting page, relevant environment, and required setup are written down.
- Every action needed to trigger the issue is included, including repeated actions.
- Expected and actual results are separate and describe a specific difference.
- Repeat attempts are reported honestly; an unknown frequency stays unknown.
- The evidence points to the relevant moment and has been checked for sensitive content.
- The receiving teammate has the access and test data needed to investigate.
After a fix, repeat the documented path in the fixed build and compare the result with the expectation. Viewing the earlier recording alone does not verify the fix.
KEEP THE BROWSER PATH
Keep the steps with the report.
Start a recording before you repeat the issue. Replay the path, pause at the relevant moment, and inspect the affected element with the Samelogic extension.
Check the replay and written steps before sharing. Input values are masked by default, but other page content can still appear.
Free extension for desktop Chrome. Try it before signing up.A few common questions.
What does it mean to reproduce a bug?
It means reaching the same unexpected behavior by following a described setup and sequence of actions. A recording documents an observed run; another attempt checks whether the behavior happens again.
What if I can’t reproduce it a second time?
Report the observation and say that another attempt did not reproduce it. Include the time, page, environment, earlier actions, and any evidence you kept. Record attempts separately from occurrences instead of calling the issue fixed or inventing a success rate.
Do I need a recording, a screenshot, or both?
A screenshot can show a layout issue or a final error. A recording can make the preceding actions and transitions easier to follow. Choose the evidence that explains the issue and include written setup and steps either way.
Does every frontend bug need a selector?
No. A visible label and a clear screenshot may identify the affected control. A selector is useful when your teammate needs to locate a specific element, but it does not explain earlier page state or prove the cause of the bug.
Does replaying a recording reproduce the live bug?
Replaying the capture helps you inspect what happened in that recorded run. It does not establish that the live application will produce the same result now or restore its server data. Verify the behavior in an appropriate test environment.
Can Samelogic show what happened before I started recording?
No. You deliberately start and stop a Samelogic recording. Start before the actions that lead to the issue, then review the replay and written steps. Earlier actions need to be described or captured in a new attempt.
Sources & further reading
The report structure follows established bug-reporting guidance. The renewal scenario is an authored example; it is not customer data or a measured product result.