repro.fyi — The Art of the Minimal Reproduction

2 min read Original article ↗

A minimal repro is the smallest set of steps that reliably reproduces your bug.

Why bother?

1. You need it anyway. Without a repro, how would you know when the bug is fixed?

2. It's your job, not theirs. When you ask for help with a messy codebase, you're asking someone to clean your room before they can help you find your keys. First clean your room. You might find your keys while you do! If not, then ask for help.

3. You'll probably fix it yourself. If you can reproduce the bug in a fresh environment with minimal code, it's the platform's fault. If you can't... it's yours. The process of minimizing is isolating the bug, which is key to debugging, regardless of who's fault it was.

How to make one

Start fresh: Create a new file or sandbox. Add only what's needed to show the bug. If you can't reproduce it in isolation, that tells you something — the bug is in the stuff you left out.

Or strip down: Copy your project, delete half. Still broken? Delete half again. Fixed? The bug was in what you deleted — put it back, delete the other half. Repeat until nothing's left to remove.

When to ask for help: Keep isolating until you hit someone else's black box — a platform, library, or API you can't see inside. That's when you've earned the right to ask.

Good vs bad

Chrome, macOS.

To Repro:

  1. Open /dashboard
  2. Click "Export"
  3. Select CSV

Expected: File downloads.

Actual: Console shows TypeError: Cannot read property 'map' of undefined

vs.

"File exports are broken, please fix ASAP"

Common mistakes

  • Sharing your whole codebase. The goal is to get someone into the bug as fast as possible. A fresh sandbox with just the error beats a link to your repo.
  • Skipping the steps. "It's broken" isn't actionable. Include a list of numbered steps to repro the bug.
  • Not including versions. Or not upgrading first. Half of all bugs are fixed in the next release.
  • Browser extensions. Try incognito mode before reporting. Extensions break more things than you'd think.

Further reading

Edit on Val Town →