For interactive or functional bugs, attach a short screencast (MP4) plus matching logs. For static visual or content bugs, attach a high-resolution, annotated screenshot instead. Either way, the attachment supports your written reproduction steps. It never replaces them. Redact or blur any private data before you upload anything to the tracker.
TL;DR:
- Attach a screencast for bugs requiring multiple actions or when timing and sequence are essential to reproduce the issue.
- Use a screenshot when the bug is immediately visible in a static view, such as a layout error or typo, and ensure the environment details are clearly shown.
- Create a new, relevant attachment for every report, include visible environment identifiers in each file, and compress large videos before uploading to avoid delays.
- Name attachments with a consistent pattern and regularly review stored files to prevent clutter and storage issues.
- Verify that captions, filenames, and timestamps align accurately before submission to enable quick and effective triage by developers.
Table of Contents
- Screenshot vs. Screencast: Which One Do You Need?
- What Are the Baseline Rules for Bug Report Attachments?
- What Should a Bug Screenshot Actually Show?
- How Do You Record a Screencast That Actually Helps?
- Which Logs and Technical Files Should You Attach?
- How Should You Name and Manage Bug Attachments?
- What’s the Last Check Before You Submit?
- How Wezard Preserves Attachment Context Automatically
- Why Most Attachment Advice Misses the Real Problem
- Try Wezard for Cleaner, Faster Bug Documentation
- Sources
- FAQ
Screenshot vs. Screencast: Which One Do You Need?
The decision is simpler than most testers make it. If reproducing the bug requires interaction, a sequence of clicks, a scroll, a form submission, a network call, record a screencast. If the bug is visible the instant the page loads, a broken layout, a typo, a wrong color, a screenshot is faster to capture and easier for a developer to scan. Roughly 90% of functional bug attachments end up being video rather than stills, because most real bugs live in a sequence of actions, not a single frame.
There are cases where one attachment isn’t enough. Intermittent bugs and race conditions often need both: a screencast to show the timing and a screenshot of the final broken state for quick reference during triage.
Run through this before you file:
- Does reproducing this require more than one action? If yes, record.
- Is the bug visible in a single static view? If yes, screenshot.
- Does timing matter (a delay, a flicker, a race condition)? Record, and note the timestamp.
- Will a developer need to see the exact sequence of events? Record.
What Are the Baseline Rules for Bug Report Attachments?
Every report needs its own fresh evidence. Copying a screenshot from an earlier, similar-looking bug is one of the fastest ways to get a ticket bounced back, because the environment, timestamp, or exact state rarely matches. Testing-platform guidance is explicit on this point: new attachment, every time, no exceptions.
Match your test-cycle language and device settings, and make sure the URL or app identifier is visible somewhere in the capture. A developer looking at a screenshot with no visible URL has to guess which environment produced it.
Platform limits matter too. Jira Cloud allows up to 2,000 attachments per issue with a default 1GB file size cap per file, though admins can adjust that. In practice, you’ll hit storage or upload-speed friction long before you hit 1GB, so compress video where you can and trim dead time from the front and back of any recording.
- Create a new attachment for every report, never reuse one from another ticket.
- Show the URL, app version, or build number somewhere in the frame.
- Compress large video files before upload rather than letting a slow upload stall your submission.
Pro Tip: If your screencast is creeping past 200MB, you’re probably recording too much idle time before the trigger. Trim it. Developers skip long videos.
What Should a Bug Screenshot Actually Show?
A screenshot that doesn’t show its context is close to useless. Follow this order every time:
- Capture the full browser or app window, including the URL bar or a visible screen identifier.
- Make sure OS, browser, and app version are visible or noted in the caption.
- Highlight the problem area with an arrow, box, or circle so the eye goes straight to the defect.
- Name the file with a consistent pattern (more on that below) so it’s identifiable outside the ticket.
- Choose PNG when text or UI fidelity matters, and JPG when you’re attaching several images in a gallery and file size adds up fast.
Skip anything with visible customer data, account numbers, or personal details in the frame. If you can’t crop it out, blur it before you upload.
How Do You Record a Screencast That Actually Helps?
Start recording just before the trigger action, not five minutes earlier while you’re still navigating menus. Nobody wants to scrub through two minutes of setup to find the ten seconds that matter. Stop the recording shortly after the bug appears. That’s it. You don’t need to narrate a full walkthrough of the app.
Use MP4 and record the whole screen, not just a cropped window; developers often need to see the whole desktop or mobile screen to spot triggers you didn’t notice, like a background notification or a second monitor cursor. Test IO’s own guidance caps bug screencasts around 60 seconds, and that ceiling is a good default even outside their platform. Keep the resolution high enough that any error text or field labels stay legible when zoomed.
If the bug is triggered by a keystroke or key combination, make sure the keyboard input is visible in the recording and note the exact keys in your caption. A silent keypress off-screen is a bug nobody can reproduce.
- Record immediately before the trigger, not earlier.
- Stop shortly after the bug is visible.
- Keep resolution high enough to read on-screen text.
Pro Tip: If your bug depends on a crash log, start the recording a few seconds before you’d normally expect the crash and check that your system clock matches the log’s timestamp. Mismatched timing is one of the top reasons developers reject a “reproduced” bug.
Which Logs and Technical Files Should You Attach?
Crash logs are non-negotiable for any crash report. For functional failures short of a crash, console logs and network request logs usually tell the story faster than a screen recording alone.
Export logs using whatever your platform provides, browser DevTools, mobile crash reporters, server-side logging, and make sure the timestamps in the log line up with the timestamps in your screencast. A log that says the error happened at 14:02:03 and a video timestamped three minutes later doesn’t help anyone.
- Attach crash logs for every crash, no exceptions.
- Attach console or network logs for functional bugs without a crash.
- Strip credentials, tokens, and personal data from any log before upload.
- Zip large log files instead of pasting raw text into the ticket description.
How Should You Name and Manage Bug Attachments?
A predictable naming pattern saves time for everyone downstream. Something like issueID_device_browser_timestamp_short-desc lets anyone scan a folder of files and know what they’re looking at without opening each one.
Lock down permissions on risky file types. Admin-level file attachment controls let teams blocklist extensions like .exe or .dll, which matters more than most testers assume once a tracker has hundreds of contributors. Living documents, specs, requirements docs, design files, belong linked externally, not attached as static files that go stale the moment someone edits the original.
- Use a consistent filename pattern across the whole team.
- Blocklist executable and script file types at the admin level.
- Link to living documents instead of attaching a snapshot copy.
- Schedule a quarterly review to clear out stale or duplicate attachments, since unmanaged attachments at scale quietly drive up storage costs and bury the files that matter.
What’s the Last Check Before You Submit?
Attachments and text need to tell the same story before you hit submit. Run through this quickly:
- Add a short caption on each attachment referencing the relevant step or timestamp, something like “00:12 — submit click triggers the error.”
- Open each attachment to confirm it loads and thumbnails correctly. A broken upload is worse than no attachment at all.
- Check that log timestamps line up with the moments shown in your screencast.
- In the ticket body, reference the attachment filename and specific timestamp rather than pasting the full log inline.
That last step matters more than it sounds. A wall of pasted log text buries the one line that matters, while a filename and timestamp reference sends the reader straight to it.
How Wezard Preserves Attachment Context Automatically
Most attachment mistakes happen because a tester reconstructs evidence after the fact, cropping a screenshot from memory or trying to recall which build a bug happened on. In-app screen recording paired with real-time transcription captures the exact context and timestamp the moment the bug occurs, so there’s no reconstruction step to get wrong. AI-based duplicate detection then flags overlapping reports before they clutter a Jira or Azure DevOps backlog, which cuts down on the redundant tickets that eat triage time.
Why Most Attachment Advice Misses the Real Problem
Most guidance on bug attachments focuses on format: use MP4, keep it under a minute, use PNG for screenshots. That’s necessary but it’s not where teams actually lose time. The real cost shows up when the attachment and the written steps tell slightly different stories, a screenshot from a different build, a log with a mismatched timestamp, a screencast that starts too late to show the trigger. Developers then spend more time reconciling the mismatch than they would have spent reproducing the bug from scratch.
The conventional advice also underrates redaction. Testers blur account numbers reflexively but forget that a full-screen recording can capture a notification banner, a second app in the background, or a colleague’s name in a chat window. Treat every recording as public the moment you hit stop, because eventually someone outside the immediate team will see it; following security-focused best practices can help safeguard sensitive information.
If there’s one thing to prioritize first, it’s timestamp consistency across every attachment in a single report. Get that right and triage speeds up on its own, no matter how polished the screenshot looks.
— Marketing
Try Wezard for Cleaner, Faster Bug Documentation
Some user acceptance testing tools offer features to record screens, transcribe issues in real time, and automatically generate structured tickets with context attached to streamline bug reporting.
AI technology can check new bug reports against existing backlogs and flag likely duplicates before they reach issue tracking systems, reducing redundant tickets for triage teams. For teams running UAT cycles with distributed testers, the Jira integration maps recordings and transcripts directly into work items without a manual upload step. See how it fits your workflow with the AI bug tracking tool, or start a trial to test it against your next reporting cycle.
Sources
- Correct Attachments: A Commonly Overlooked Requirement
- Add an attachment to a work item | Jira Cloud | Atlassian Support
- Bug Report Attachments
- Managing Attachments in Jira at Scale: How to do it effectively
FAQ
What Is an Example of a Bug Report Attachment?
A short MP4 screencast showing the exact click sequence that triggers an error, paired with a console log timestamped to match, is a typical example for a functional bug. For a visual bug, an annotated PNG screenshot with the broken element circled is more common.
Can You Give Examples of Well-Documented Bug Reports?
A well-documented report includes written reproduction steps, an environment summary (OS, browser, app version), and an attachment, screenshot or screencast, that matches those steps exactly, with no gaps in timing or state between the text and the file.
How Do I Submit a Bug Report With Attachments?
Write clear reproduction steps first, capture a screenshot or screencast that matches those exact steps, name the file consistently, then attach it to the ticket with a caption referencing the relevant timestamp or step number before submitting.
What Does “Bug Report” Mean on Android?
On Android, a bug report typically refers to a system-generated diagnostic file containing device logs, app state, and stack traces, distinct from the screenshots or screencasts testers manually attach to describe a specific issue’s visible behavior.
Should I Attach Both a Screenshot and a Screencast?
Yes, when timing matters, such as intermittent bugs or race conditions. A screencast shows the sequence and timing, while a screenshot of the final broken state gives triage teams a quick visual reference without watching the full video.
