How to Document a Bug with Step-by-Step Screenshots on Mac

A bug report is useful when someone else can reproduce the bug from it without asking you a question. Step-by-step screenshots remove most of the guessing: the developer sees each screen you saw, in order.

This post covers what a reproducible report needs and how to capture the steps on a Mac with Temposhot Action Capture.

Record the environment first

Many bugs appear only in one version, one browser or one account type. Write the environment down before reproducing, while you still remember the setup.

Detail	Example
App or site version	Build number from the About window or footer
macOS version	From About This Mac
Mac model and chip	From About This Mac
Browser and version	For web apps, from the browser's About page
Account type or role	Free, paid, admin, viewer
Language and region	If the bug involves text, dates or currency
Date and time	With time zone, so logs can be matched

Copy values as text. A screenshot of the About window is good evidence, but developers cannot search an image.

State the expected and actual result

Two short sentences frame the whole report:

• Expected: "After selecting Save, the new name appears in the list."
• Actual: "After selecting Save, the list still shows the old name. Reloading the page shows the new name."

Describe what you observe, not what you think the cause is. "The list does not refresh" is an observation. "The cache is broken" is a guess.

Reproduce from a known starting point

A report that starts with "open the app" when you were already deep in a session hides the real setup. Start from a state anyone can reach: a fresh sign-in, a new project, a specific URL.

Reproduce the bug at least twice before recording. If it appears only sometimes, note how often, for example "3 of 5 attempts".

Capture one screenshot per required action

1. Open Action Capture

   Press Command+3 and select Start Action Capture. Choose Specific Window for one app, or Active Window if the steps cross apps.

2. Perform the steps

   Each accepted click saves the window just before the click, so every page shows the control before you act on it.

3. Capture the failure

   When the wrong result appears, press Shift+Command+2 or select Capture now in the floating toolbar. The failure screen often appears without a click.

4. Finish capture

   Select Finish capture. The Document opens in the editor with one page per step.

With Parse clicked elements turned on, page titles start as Click "[[element-name]]". Turn on Show cursor on click captures and Mark clicked area under Visual Annotations so each page shows where you clicked. If the bug is in Temposhot itself, turn on Include toolbar in captures so the floating toolbar appears in the steps.

Add text that explains state changes

Screenshots show screens. They do not always show what changed between them. Use the Page description for that: "The counter should show 4 here. It shows 3."

On the failure page, draw a Rectangle (R) around the wrong value and add a Text label (T) with the expected value. Delete pages from stray clicks so the sequence contains only required actions. Edit titles into plain steps, such as "Select Save". The editor guide lists every tool and shortcut.

Protect private information

Bug reports are copied into trackers, chat threads and vendor tickets. Treat every screenshot as public within your organization.

• Reproduce with a test account and sample data when possible.
• Crop out sidebars, browser tabs and notifications with Framing (F) and Custom.
• Blur names, email addresses, tokens and IDs with Blur (B, Pro).
• Remove session tokens and API keys from any URL or log text you paste.

Use this bug report structure

1. Title: what fails, where. "Renamed item does not update in list view."
2. Environment: the table values from above.
3. Steps to reproduce: numbered, starting from a known state.
4. Expected result and Actual result.
5. Frequency: always, or how often.
6. Evidence: the exported screenshot guide, plus any logs or console errors as text.
7. Workaround: if one exists.

Export from the Document with Export PDF for one attachment, or More export formats for PNG pages that trackers show inline. Image file names follow page titles. The export guide lists all formats.

Test the report before sending it

Read the report from the top as if you had never seen the bug. Better still, ask a colleague to follow it on their Mac. If they reproduce the bug without asking a question, the report is ready.

Frequently Asked Questions

Should a bug report include video or screenshots?

Screenshots work for most bugs and are easy to scan and annotate. Video helps for timing issues and animations. See step-by-step screenshot guide vs screen recording.

How many screenshots does a bug report need?

One per required action plus the failure screen. Remove pages that do not change the outcome.

Where do the screenshots live after I send the report?

The Document stays on your Mac. Temposhot has no hosted link, so attach the exported files to the issue tracker or ticket.

Turn your clicks into a clear step-by-step guide

Action Capture records the reproduction steps as you perform them, with click marks and draft titles. Download Temposhot and attach your next bug report as an ordered guide.