How to Create Bug Reports with Screenshots
// tl;dr
- — Record the steps to reproduce a bug while Procshot auto-captures annotated screenshots at each click.
- — Export as Markdown (or PDF with Pro) and paste directly into GitHub Issues, Linear, or Jira.
// why this matters
A bug report without reproduction steps is nearly useless. Engineers need to reproduce the bug before they can fix it — which means they need to know exactly where it occurred, what was clicked, what data was entered, and in what sequence. Writing this out manually after discovering a bug is tedious and error-prone: you try to recall the steps, take screenshots separately, number them, paste them into your issue tracker. Under time pressure, bug reports end up incomplete. Recording the reproduction steps as you discover the bug — before you close the tab — produces a precise report with a screenshot for each step, without taking screenshots separately. For QA teams and developers who file multiple bugs per day, this is a meaningful workflow change.
Step-by-Step Guide
- 1
When you discover a bug, immediately open Procshot
Before closing the tab or navigating away, open the Procshot extension panel. Starting the recording at the point of discovery lets you document the state the bug occurred in, which is often the most important context.
tip: Don't try to reproduce it from memory first — record it on the spot. The first reproduction is the most accurate.
- 2
Navigate to the start of the reproduction path
Go back to the beginning of the sequence that leads to the bug. For a form submission bug, this might be opening the form. For a navigation bug, returning to the page before the problematic link. Start from a clean, reproducible state.
- 3
Start Recording and reproduce the bug step by step
Click Start Recording in Procshot and then perform every action that leads to the bug: click each element, fill each field with the exact data that triggers the issue, navigate each page in sequence. Procshot captures a screenshot at every click.
- 4
Capture the bug state — the broken or unexpected UI
When you reach the point where the bug manifests — the error message, the broken layout, the unexpected behavior — make sure to interact with it so Procshot captures that state. If the bug is a console error or a blank screen, note this in the step description after stopping.
- 5
Stop Recording
Click Stop Recording. Procshot generates a draft bug report with all reproduction steps as sequential annotated screenshots.
- 6
Edit step descriptions to add context
Review each auto-generated description. For bug reports, add context beyond what the UI element name conveys: 'Clicked Submit with the Date field empty — triggering the bug' is more useful than 'Clicked Submit'. Describe expected vs actual behavior in the final step.
tip: Add a clear 'Expected:' and 'Actual:' note in the last step description — most issue trackers expect this format.
- 7
Annotate the bug state screenshot (Pro)
On the screenshot that shows the bug (the error message, broken element, or unexpected state), use Procshot Pro's annotation tools to draw a box or arrow pointing to the specific problem area. Engineers scanning multiple bug reports will immediately see the issue.
- 8
Export as Markdown and paste into your issue tracker
Export the guide as Markdown. Open your issue tracker (GitHub Issues, Linear, Jira) and create a new issue. Paste the Markdown content into the description field — the steps, descriptions, and screenshots are included. Add environment details (browser version, OS) and severity label.
// use cases
QA Teams Filing Regression Bugs
QA engineers record the exact reproduction path for each regression bug during test cycles. Reproducible reports with screenshots cut engineer triage time and eliminate the back-and-forth of 'can you reproduce it?'
Customer Support Escalating User-Reported Issues
Support agents who can reproduce a customer-reported bug record the steps and file a precise engineering ticket, reducing the ambiguity between support and engineering about what the actual issue is.
Developer Self-Reporting During Development
Developers who discover bugs in neighboring code areas record and file them immediately rather than adding them to mental backlogs — reducing forgotten bugs and knowledge loss at the point of discovery.
// tips & best practices
- › Include environment details in the issue title or first line: browser version, OS, and app version if relevant — these aren't captured by Procshot.
- › If the bug is intermittent, note that in the description and record multiple reproduction attempts if you can replicate it again.
- › With Pro, use the blur tool on any personal user data visible in screenshots before filing in a shared issue tracker.
- › For form-related bugs, include the exact data entered in each field in the step description — the screenshot shows what was entered, but the description should make it text-searchable.
- › Add severity and priority labels in the issue tracker after pasting — Procshot's export doesn't include issue metadata.
- › Duplicate the guide before editing if you want to preserve the raw recording alongside the polished report.
// common pitfalls
Recording only the bug manifestation, not the full reproduction path
A screenshot of the error is not a bug report. Engineers need the complete sequence from a clean state to the error. Start recording at the beginning of the reproduction path, not at the point where the bug appears. If the path starts at login, include the login steps.
Not describing expected vs actual behavior
Procshot captures what happened, not what should have happened. Without an 'Expected:' and 'Actual:' note in the final step, engineers have to infer what the correct behavior should be. Always add this context — it's the most important part of any bug report.
Filing a bug report without environment information
Procshot captures UI interactions but not environment context: browser version, OS, screen resolution, user role, or data state. Browser-specific or role-specific bugs that lack this information are hard to prioritize. Add environment details manually as the first line of the issue.
// faq
Can I attach Procshot exports directly to Jira or GitHub Issues?
Yes, with one manual step. Export as Markdown from Procshot, then paste the content into the issue description in your tracker. Most trackers (GitHub Issues, Linear, Notion) render Markdown natively including image references. Jira uses a different markup language — for Jira, the PDF export (Pro) may be easier to attach as a file.
Does Procshot capture browser console errors?
No. Procshot captures visual UI state through screenshots — it doesn't access the browser console. For bugs that involve console errors, add a separate screenshot of the console (using the browser's built-in screenshot or DevTools) and reference it in the step description.
What if the bug only happens occasionally?
For intermittent bugs, record every reproduction attempt you can. Note in the description that it's intermittent and include frequency observations ('happens approximately 1 in 3 attempts with this data'). A recording of a successful reproduction is more useful than a written description of an intermittent one.
Can I include expected vs actual behavior in the Procshot export?
Yes — edit the final step description to include 'Expected: [what should happen]' and 'Actual: [what happens instead]'. This text is included in all export formats (Markdown, HTML, and PDF with Pro).
How do I share the bug report if my team uses a tool other than GitHub or Jira?
Procshot exports to Markdown (for most text-based platforms) or HTML (for web-based systems), and to PDF (for email or attachment) with Pro. If your team uses Linear, paste the Markdown. For Confluence, HTML export works well. For Notion, Markdown renders natively.
// related tools
Procshot — Free Chrome Extension
Auto-record browser actions to create step-by-step guides with annotated screenshots.
// related guides
How to Create Step-by-Step Tutorials
Chrome extension tutorial guide
How to Document Software Processes
SOPs and onboarding materials
How to Make Onboarding Guides for SaaS
Customer success workflows
How to Export Tutorials to PDF or Markdown
Format guide for technical writers
// compare procshot