How to Annotate a Screenshot in a Bug Report (Testers)

To annotate a screenshot in a bug report, circle the broken element, blur anything private, and add one sentence saying what you expected. That takes under thirty seconds and saves the developer a round trip of questions.

Most testers do the opposite. They paste a full-screen image, write "it's broken", and leave the developer to hunt for the problem. Here is how to make annotated screenshots work for you, whether you ask testers to do it by hand or let your tooling do it.

Why a plain screenshot is not enough

A screenshot shows the result, not the problem. On a busy screen, the developer has to guess which of forty elements is wrong. Is it the misaligned button, the empty list, the toast in the corner? Each guess costs a message and a day of waiting.

An annotation answers the one question that matters: where should I look? A red circle around the pay button and the words "spinner never stops" turn a vague complaint into a starting point.

Even a perfect annotation still cannot show what happened underneath. It will not tell you about the failed request or the exception in the console. That is why annotation works best as the first layer of a report, not the whole report. If you also need the technical side, see how to get console logs from a user without DevTools.

What to mark, and what to leave out

Keep annotations small and few. Three tools cover almost every case:

• A rectangle or circle around the exact element that is wrong.
• An arrow when the problem is a gap, a missing element or an ordering issue.
• A blur over names, emails, tokens, card numbers or anything the tester would not want in a ticket.

Then add a single sentence in the form "I did X, I expected Y, I got Z". Skip the paragraph. If the tester needs more room than that, the steps belong in the report text, not on the image.

Do not annotate everything. Five arrows on one screenshot say "the whole page is wrong", which is the same as saying nothing. One screenshot per problem is a good rule: if there are two bugs, send two reports.

A template testers will actually follow

Testers skip long instructions. Paste this at the top of your feedback channel or test invite:

1. Open the screen where it goes wrong.
2. Take a screenshot.
3. Circle the problem. Blur anything private.
4. Write: "I did ___, expected ___, got ___."
5. Mention your device and app version.

Step five is the one people forget, and it is the one that explains why a bug appears on an iPhone 15 and not on the developer's laptop. For a fuller structure, our bug report template for testers goes further.

Doing it by hand vs. building it into the app

Asking testers to screenshot, open an editor, annotate, export and attach the file to an email is five steps too many. Each one loses a few testers. The usual outcome is a long thread of "can you send a screenshot?" replies.

The better pattern is to put capture and annotation inside the app, behind one gesture such as a floating button, a keyboard shortcut or a shake of the phone. The tester draws on the live screen, blurs, types a sentence and sends. The device, version and locale travel with the report automatically, so nobody has to type them.

That is what Tracebird does on web and Flutter: the annotated capture arrives together with console logs, network calls and a session replay, and duplicate reports are grouped so you triage one bug instead of twenty. If your testers use Flutter, shake to report a bug shows what to capture on mobile.

Checklist before you ask testers to annotate

• Decide which three tools they get: shape, arrow, blur. More is clutter.
• Mask text inputs by default so a password never lands in an image.
• Keep the sentence field short, with the "did, expected, got" prompt visible.
• Send device and version automatically instead of asking.
• Group identical reports, so ten annotated screenshots of the same bug become one ticket with a count.

An annotated screenshot is the fastest way to say "look here". Make it a ten-second habit for testers, and let the rest of the context travel with it.