A bug report is a description of a defect you found. Its quality determines the fate of the bug: a clear report lets the developer reproduce and fix it in minutes, while a poor one comes back with the comment "cannot reproduce" — and everyone loses time.

A good bug report is not a creative exercise — it follows a strict structure. Reading it, the developer should be able to reproduce the problem step by step without asking you anything. Let's break down what a report consists of and how to write one that leaves no questions.

What a bug report consists of

The standard set of parts:

  • Title — short and specific about the problem.
  • Steps to reproduce — a numbered path to the bug.
  • Expected result — what should have happened.
  • Actual result — what actually happened.
  • Environment — where it occurred: browser, device, build version, test or production environment.
  • Attachments — a screenshot, video, and for technical bugs — errors from the console or network tab.
  • Severity and priority — severity and priority.

The core without which a report is useless: steps to reproduce + expected result + actual result. Everything else helps, but those three are where it all starts.

Title: short and to the point

The title is read first and used to search for duplicates. It should answer "what, where, and under what condition." Compare:

  • Bad: "Error in cart," "Doesn't work!" "Bug."
  • Good: "Cart: total does not reset to zero when the last item is removed."

A good title is understandable without opening the report. The rule: if you can't tell what the bug is from the title alone, rewrite it.

Steps to reproduce: the heart of the report

This is the heart of the report. Write it so that someone who has never seen the product before can follow the path without guessing:

  1. Open the product page example.com/product/123.
  2. Click "Add to cart."
  3. Go to the cart.
  4. Remove the only item using the "Remove" button.

Expected result: the cart is empty, total is 0. Actual result: the item disappeared, but the total still shows 1500.

Rules for steps:

  • Start from a point everyone can recognize (which URL, which user account) — not from the middle of your scenario.
  • One step — one action. Not "log in and complete the whole flow," but one action at a time.
  • Specifics instead of vague words. Not "enter the data" — which data exactly?
  • Minimum steps. Remove everything that doesn't affect the bug. The shorter the path, the more valuable the report.

Reproducibility and attachments

Before logging the bug, reproduce it yourself one more time following your own steps. If it reproduces consistently — great. If it only happens sometimes — say so ("reproduces roughly once out of three tries") and attach a video: intermittent bugs are harder to catch, and honesty here matters more than a clean write-up.

A screenshot or a short video saves a lot of words — attach them almost always. For technical bugs, open the developer tools: a red error in the console or a failed request in the Network tab, attached to the report, will help the developer find the root cause much faster.

Where this applies

Bug reports are what you produce every day, and they are how your work is judged. Developers, managers, and other testers all read them. A tester who writes clear reports saves the team hours; one whose reports need deciphering or keep coming back as "cannot reproduce" costs the team time instead. Without exaggeration, this is your most important documentation skill.

Where beginners stumble:

  • They write a title like "doesn't work" with no substance. You can't find duplicates or understand what the bug is about from a title like that.
  • They skip steps or start from the middle. The developer can't reach the bug and closes it as "cannot reproduce."
  • They don't separate expected from actual. "Bug with the total" tells you nothing. You need: expected 0, actual shows 1500.
  • They don't verify reproducibility before logging, and they don't attach a screenshot.

What to learn next. The report is filed — what happens next? For the bug's journey from discovery to closure and what it looks like in a tracker, read the article on bug lifecycle and trackers.