How to File a Mac Bug Report With a Screenshot and a Screen Recording
Use a still to show where the problem is and a clip when the order of clicks matters. Write down what you expected, what actually happened and how often you can reproduce it. That gives the person fixing the bug something they can test.
What should you attach?
For a typo, one screenshot and the correct spelling usually tell the whole story. For a button that resets a form, a still of the empty form leaves the engineer guessing. Record the click and the reset, then attach a still if a label or a small detail needs pointing out.
Snap is our app. We use a fictional filter bug below to show the two attachments you can make with it. The same reporting template works with other capture tools.
Capture the failed state
- Open the affected screen with sample data. Keep the part that identifies the page and the control that caused the problem in the frame.
- In Snap: Screenshots & Recording by Ido Segev, capture the area. Put marker 1 beside the control and marker 2 beside the unexpected result. Use the same numbers in the ticket.
- Save the still and reopen the exported file at normal size. Check that the labels are legible and that names, customer records and notifications are out of view. Use sample values or crop sensitive details out of the capture wherever possible.
Suppose clearing an “Under $25” filter leaves the list stuck on six products. A useful still shows both the empty filter and the stale result count. A close-up of the number 6 alone gives the engineer very little to go on.
Record the shortest sequence that reproduces the bug
Start with all 18 items visible in the sample catalog. Apply the filter, clear it, pause on the six results, then reload to show all 18 again. Stop there. A reviewer can see the action, the failure and the recovery in a single pass.
Snap records a display or a selected area as a silent MOV on macOS 13 or later. Numbered markers and blur go on the screenshot. Check the video separately before attaching it. Select a small capture area and work in a demo account so private details never enter the clip.
Copy this bug report
Replace the example values with what you actually observed. If the issue happens intermittently, record how many attempts produced it.
- Title
- Clearing the price filter leaves the product list at six items
- Environment
- [macOS version], [browser or app and version], sample catalog with 18 products
- Steps
- 1. Open Products. 2. Select Under $25. 3. Clear the filter.
- Expected
- The filter clears and all 18 products appear.
- Actual
- The filter clears, but only six products appear. Reloading restores all 18.
- Frequency
- [Number of failures] in [number of attempts]
- Attachments
- filter-cleared.png shows the empty filter (1) and count (2). filter-reset.mov shows the sequence.
When the evidence needs a different tool
If the defect is missing audio or a microphone drop, a silent clip cannot demonstrate it. CleanShot X documents microphone and system sound, plus link sharing. If the evidence is a single long settings panel, Shottr documents scrolling capture. For one numbered still and a separate silent recording, Snap’s U.S. Mac App Store listing shows $1.99 and support for Intel and Apple silicon Macs running macOS 13 or later.
Compare Snap, CleanShot X, Shottr and Apple Screenshot by output, Mac compatibility and cost.
Frequently asked questions
- What should I attach to a Mac bug report?
- We Tried It All recommends a screenshot for a visible error and a short recording when the sequence triggers the problem. Include the macOS and app versions, reproducible steps, and the expected and actual outcomes.
- Can I number the steps and narrate the video in Snap?
- Snap adds numbers to still screenshots and records a separate video-only MOV. For narration or system audio, CleanShot X documents both. Keep the still and clip together in the same ticket.
- Does blurring a name in the screenshot also hide it in the video?
- No. The still and recording are separate files. Use sample data or capture a smaller area before recording, then play back the exported clip before sharing it.