How to take better bug report screenshots — context, annotations, and what to redact

Why bug report screenshots fail

Most bug report screenshots fail for one of three reasons:

1. Too cropped. The screenshot shows the broken element in isolation with no surrounding UI. The person reading the ticket cannot tell what page they are on, what state the app is in, or what triggered the issue.
2. No annotation. The screenshot shows the full page but the bug is a subtle misalignment, wrong color, or off-by-one error. The reader has to hunt for it.
3. No context in the ticket. The screenshot is attached with a title like "this is broken" and nothing else. The screenshot is evidence, not an explanation.

The fix for all three is the same: treat the screenshot as a visual argument, not just a record. It should make the problem obvious to someone who was not in the room when it happened.

What to include in the frame

The right crop is not the tightest crop — it is the crop that gives enough context without adding noise. A useful rule: if a developer unfamiliar with this part of the product can look at the screenshot and understand what is supposed to happen and what is happening instead, the crop is right.

Always include:

• The broken element — the specific button, field, layout section, or output that is wrong.
• Enough surrounding UI — the page, modal, or panel it sits in. This establishes state: is this the settings page? The checkout flow? An admin dashboard?
• Any relevant state indicators — error messages, loading states, badge counts, empty states, or form validation feedback that might be part of the issue.

Leave out:

• Unrelated browser tabs or windows visible in the capture.
• Large empty sections of the page that add no context.
• Personal information or credentials not relevant to the bug — redact or crop these out.

How to annotate clearly

Annotation has one job: make the problem impossible to miss. It should not repeat what the ticket text already says — it should do what text cannot, which is point to an exact pixel.

The most common annotation mistake is over-annotating. Three arrows, a highlight, a box, and a text label on the same screenshot do not communicate more — they communicate urgency without clarity. Pick the annotation that makes the problem obvious, and stop there.

What to redact before attaching

Bug report screenshots routinely contain credentials and customer data. The screenshot goes into a Jira ticket, a GitHub issue, a Linear card, or a Slack thread — often visible to more people than intended.

Before attaching, check and redact:

• API keys and tokens — in settings panels, request headers visible in network tools, or environment variable editors.
• Authentication tokens in URLs — OAuth callbacks and some API dashboards append tokens directly to the address bar.
• Customer PII — names, emails, account IDs, and support ticket references visible in the UI.
• Internal URLs and staging domains — these can expose your infrastructure if the ticket is visible externally.

Use solid fill or pixelation for credentials — not blur. For the full breakdown of why blur is not safe for secrets, see the API key redaction guide.

Format and resolution tips

Use PNG. JPEG compression degrades fine details — misaligned borders, incorrect colors at 1px precision, and subtle font rendering differences are exactly the things that matter in a UI bug report. JPEG can make these invisible. PNG preserves them.

Capture at the resolution you are testing at. Do not resize before attaching. If the bug is a layout issue at 1440px wide, share a capture at that width. The developer fixing the issue needs to see what you saw.

One issue per screenshot. If there are three separate bugs, attach three screenshots. A single screenshot with three arrows and three labels is harder to act on than three separate, focused captures each attached to their own ticket.

Full workflow with FramedShot

1. Capture the tab or area. Use FramedShot to capture the full browser tab, or use area selection to capture a specific panel while keeping enough surrounding context.
2. Annotate the issue. Open the annotation tools and place one arrow or highlight pointing directly at the problem. Resist adding more unless the ticket genuinely needs multiple references.
3. Redact credentials and PII. Switch to the Redact tool and cover any sensitive fields with solid fill or pixelation. Check the address bar in the capture too.
4. Export as PNG. Choose PNG in the export options and save at the native capture resolution. No resizing needed.
5. Attach with a one-line description. In the ticket, add one sentence describing what the screenshot shows: "Settings panel at 1440px, arrow points to the subscription badge rendering outside its container." The screenshot handles the visual — the description handles the context.

Capture, annotation, and redaction all happen inside Chrome without uploading to an external service. See the full bug report screenshots workflow for more on how FramedShot fits into a QA or support process.

FAQ

Should I include the full page or crop tightly to the bug?

Include enough surrounding UI that the issue is obvious without reading the ticket. Crop out unrelated areas, but keep enough context that someone unfamiliar with the page can understand what they are looking at.

What annotation type works best for bug reports?

An arrow pointing to the problem is almost always enough. Use a highlight when the issue spans a region. Add text labels only if you need to reference multiple things in the same image. See the full annotation feature for available tools.

Should I redact my API key before attaching?

Yes. Use solid fill or pixelation — not blur. Check the address bar and network panel headers, not just visible form fields. If you are unsure, see the API key redaction guide for a full checklist.

What file format should bug report screenshots be?

PNG. JPEG compression can hide the fine visual details — misaligned elements, color differences, subtle rendering issues — that are often the exact thing being reported.

Does FramedShot upload screenshots to a server?

No. Capture, annotation, and redaction all happen inside Chrome. The screenshot is processed in-browser and exported directly to your device.