The Anatomy of a Perfect Bug-Repro Recording

Every engineer has been on both sides of this:

• Send side: “There’s a bug. The button doesn’t work.” (One sentence, no context.)
• Receive side: “What button? On what screen? What did you expect to happen? What browser?” (Five questions. Three days of email.)

A 90-second screen recording fixes that, but only if it’s structured. Here’s the playbook.

The five things every bug repro must show

In order, on tape:

1. The state going in — what page / view / object you started on.
2. The action you took — exactly what you clicked, typed, or scrolled.
3. The expected result — say it out loud. “I expected to see X.”
4. The actual result — point to it on screen. “Instead I see Y.”
5. The console / network / logs — open DevTools while recording.

If you skip any of these, the engineer will ask. If you nail them, you’ll often get a fix in the same day.

Before you press record

Three setup tasks. They take 20 seconds and save 20 minutes:

• Open DevTools first. Cmd+Option+I in Chrome, then click the Console tab. Set it up before recording so you don’t waste tape on opening it.
• Reproduce it once silently. Verify the bug actually happens. Nothing kills a repro faster than the bug not reproducing on tape.
• Have a fresh tab. Don’t record over your messy tab bar. Open a new window if you need to.

The 90-second script

Time-boxed, in order. Watch yourself stay under 90 seconds:

1. 0:00–0:10 — State. “I’m on the dashboard, here’s the URL. I’m logged in as user 1234.”
2. 0:10–0:25 — Action. “I’m clicking ‘Export CSV’ here.” (Click slowly, hover, then click — let the viewer’s eyes catch up.)
3. 0:25–0:35 — Expected. “I expected the file to download.”
4. 0:35–0:55 — Actual. “Instead the button spins forever. Here’s the console — there’s a 500 error from /api/exports.”
5. 0:55–1:30 — Reproduction. “I can do it again.” (Reload, click, watch it fail.)
6. 1:30 — Stop.

That’s it. Don’t narrate your theories. The engineer can read the console.

Common mistakes

Recording in 4K

A bug repro doesn’t need to be cinema. Half-resolution, 15 fps, GIF — all fine. The smaller the file, the more likely it gets watched.

Hiding the cursor

Your cursor is the visible proxy for what you did. Make sure cursor display is on. Most apps default to it; some (like QuickTime) hide it by default.

Forgetting the URL bar

The URL is half the context. If the recording crops out the address bar, the engineer can’t recreate the page state. Always include browser chrome unless you have a specific reason.

Long pauses while you think

Edit them out. A bug repro with three “uhhh, let me check” pauses is a 3-minute video. The same content trimmed is 45 seconds.

Format: GIF or MP4?

Our GIF export guide covers the conversion details if you don’t have a recorder that exports natively.

Redacting sensitive data

If the bug shows real customer data, an API key, or anything you don’t want on tape:

• Pixel-blur over the field. Most recorders have this. (Zenguy includes a draggable redact tool.)
• Stop / re-record in incognito with seeded test data. More work, cleaner result.
• Don’t post and apologize. Once the GIF is in a Slack channel, it’s effectively forever.

A real example

Here’s a real bug repro we received recently — anonymized:

“Trying to reorder columns in the table. URL: app.example.com/projects/42/board. Expected: column moves to new position. Actual: column snaps back. Console shows ‘PATCH /api/columns/123 → 422 Unprocessable Entity, position must be unique’. Reproduces every time. (15-second GIF attached.)”

That ticket was diagnosed in 4 minutes and fixed within an hour. The previous version of that same bug — without the recording — had been open for nine days.

The ratio is real: clear repros close fast.