How to reproduce a frontend bug.

A screenshot shows where a bug ended. The next person also needs where it began and how it got there. The packet groups that evidence into three parts, one for each question they’ll ask.

1. Starting state

   Understand where it began.

   1. 01Environment and build
   2. 02Test data, account, and role
   3. 03Flags, locale, and configuration
   4. 04State before the first step

2. Failure path

   Follow what happened.

   1. 05Ordered actions
   2. 06Expected and actual at each step
   3. 07Browser state at the first mismatch
   4. 08Console context
   5. 09Network context

3. Final result

   Inspect where it ended.

   1. 10Replay or trace
   2. 11Final-state evidence
   3. 12Last known passing

Fill in every part or write “unknown.” An honest unknown tells the next person where to look. A guess sends them somewhere else.

Someone else needs to begin where you began. Write down what was true before the first action, while it’s still true.

1. 01

   Environment and build

   The environment and URL, the build or commit, when it was deployed, the browser and its version, the operating system, and the viewport or zoom when layout matters.

   “Works for me” often means a different build. Copy the build from the app’s version endpoint, footer, or deploy log instead of writing it from memory.

2. 02

   Test data, account, and role

   The account or records you used, the role and permissions behind them, the plan or entitlement, and any seed or fixture name. Use IDs. Never paste passwords or tokens.

   Name the data so someone else can find it or recreate it. “My test account” stops being useful when two accounts have different roles.

3. 03

   Flags, locale, and configuration

   Feature flags and experiment variants, language and locale, time zone, currency, and region. Include browser settings that change behavior, such as blocked cookies.

   Record the value your session actually received. A flag’s default can differ from what your account saw.

4. 04

   State before the first step

   The page you started on, whether you were signed in, how you got there, and anything already selected, open, filtered, or unsaved.

   Write this down before you refresh. A fresh tab can skip the earlier path that made the bug possible.

In the renewal example, “start with 1 seat” matters. Opening the page with 3 seats already saved would describe a different path.

List what you did, what you expected after each action, and what happened. The first step where those differ is where the investigation starts.

1. 05

   Ordered actions

   One action per step, in order. Use the label on the screen, the value you entered, and a time or replay timestamp. Keep repeated clicks, waits, and back navigation.

   “Click Add seat again” may be the step that matters. Don’t fold a repeated action into the one before it.

2. 06

   Expected and actual at each step

   After each action, what should be true and what was true. Mark the first step where they differ, and say where the expectation comes from: a spec, a ticket, or a previous build.

   Compare specific values. “The quote is wrong” leaves the comparison to the reader.

3. 07

   Browser state at the first mismatch

   What the page showed at that moment: the URL, the visible values, the affected element and its label, focus, loading indicators, and open dialogs. Add a screenshot with its timestamp.

   The first mismatch usually says more than the final error screen. A selector helps someone find the element. It doesn’t explain how the page got there.

4. 08

   Console context

   Errors and warnings near the mismatch, with the step they follow. Note which log levels were visible and whether Preserve log was on. If the console was clean, say so.

   “No errors from 00:00 to 00:14” is evidence too. It tells the next person where not to start.

5. 09

   Network context

   The requests tied to the failing steps: method, path, status, duration, and order. Add the one field that matters from the payload or response, when it’s safe to share.

   A 200 response can still carry the wrong value. Remove tokens, cookies, and personal data before you paste anything.

Where it’s safe to repeat the flow, run it again and remove one step at a time. Keep the shortest path that still fails, and note the steps you removed.

Show where things ended, on screen and in saved data, and when the same path last worked. This is what lets someone check your conclusion without running the flow again first.

1. 10

   Replay or trace

   A link to the recording or trace, the timestamp of the first mismatch, and what it covers: when it started, which tab, and what it leaves out.

   Start recording before step 1. A replay that begins after the important click shows the result without the path.

2. 11

   Final-state evidence

   The final screen, plus what was saved, sent, or charged. Read it back from the API, an admin view, or the database instead of trusting the screen. Note where you stopped.

   Say what you didn’t do. “Stopped before Confirm renewal; no payment taken” saves someone a refund check.

3. 12

   Last known passing

   The last build, date, or run where the same path worked, and what changed since: deploys, flags, data, or browser. If you don’t know, write unknown.

   Two known points turn a search into a comparison. With a good commit and a bad one, git bisect can narrow the range.

Choose a replay or trace that fits the failure.

Each kind of record answers a different question. Pick the one that shows the path, and say what it leaves out.

• Screen video

  Shows

  What the reporter saw, including visual glitches and timing.

  Leaves out

  You can’t inspect elements, requests, or console messages inside it.

• Session recording

  Shows

  The recorded page, step by step. Pause at a moment and inspect the elements on it.

  Leaves out

  It replays the recorded page, not the live app or its server data. Pair it with console and network notes.

• Playwright trace

  Shows

  An automated run’s actions, DOM snapshots, console, network, and source in one file.

  Leaves out

  It exists only when tracing is on, and only for the automated run.

• HAR file

  Shows

  Every request the Network panel kept, with timing, in a file others can import.

  Leaves out

  No page or console state. It can hold cookies, tokens, and personal data until you sanitize and review it.

For automated runs, keep traces for failures. Playwright’s retain-on-failure records each test and removes the trace when it passes.

import { defineConfig } from "@playwright/test";

export default defineConfig({
  use: {
    // Keep traces from failed tests only.
    trace: "retain-on-failure",
  },
});

// Open a saved trace locally:
// npx playwright show-trace path/to/trace.zip

Here’s the renewal bug as a full packet. Every part is filled in, including the ones that found nothing.

The stale quote request is an observation. “The new build drops the second seat update” is a hypothesis to test, not a confirmed cause.

Start with the blank packet, or open the filled example to see how the parts fit together. Copy it into your issue or download it as Markdown. Both include the handoff checklist.

A good packet narrows the search. It doesn’t finish it. Keep these limits in the report so nobody reads more into it than it holds.

Can showWhat happened in the observed run, in order.

Does not proveThat the same thing will happen on the next run.

Can showThe first step where expected and actual differ.

Does not proveWhy they differ. The root cause is still a hypothesis.

Can showThe requests, errors, and values present near the mismatch.

Does not proveThat a nearby request or error caused it.

Can showHow the final state compares with the last passing run.

Does not proveThat a change, a rerun, or a replay has fixed it.

Label explanations as hypotheses. After a fix, repeat the documented path on the fixed build and compare the result with the expectation. Watching the earlier recording again doesn’t verify the fix.

Keep the original observation. A failed attempt to repeat the bug is useful information, but it does not establish that the issue has disappeared.

Investigating an automated failure? Start with the test run’s evidence in the flaky Playwright tests workflow.

Before handing over the issue, check that your teammate has enough to begin.

• Every part is filled in or marked unknown. Nothing is blank by accident.
• The steps start from the written starting state and include repeated actions.
• Expected and actual results name specific values, and the first mismatch is marked.
• Observations are kept separate from guesses about the cause.
• Attempts are reported honestly. An unknown frequency stays unknown.
• Screenshots, logs, requests, and replays were checked for tokens and personal data.
• The receiving teammate can open the evidence and use the same test data.

This packet supports investigation. It does not prove the root cause, confirm a fix, or guarantee the bug will happen again.