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

This guide shows how to collect screenshot evidence for a software bug that another person can reproduce. You will record the environment, define the expected and actual result, capture the required actions, clean the evidence, and test the report once before sending it.

TL;DR: A useful bug report combines a clear starting state, exact reproduction steps, expected and actual results, frequency, environment details, and evidence of the first visible failure.

Record the environment first

The environment tells the reviewer where the bug occurs. Record the app version, macOS version, device type, account or permission state, and any setting that changes the behavior.

Keep this information specific enough to recreate the conditions. "Latest version" becomes ambiguous after the next release, while "Shotomatic 1.8.2 on macOS 15.5" remains useful later.

Include these fields when they apply:

• app and build version
• macOS version
• Mac model or processor architecture
• account type or plan
• browser and browser version
• connected display or input device
• relevant permissions and feature settings
• network state

State the expected and actual result

The result pair defines the problem before the reviewer reads the steps. Write one sentence for what should happen and one sentence for what happens instead.

Use observable results rather than a diagnosis. "The PDF export button does nothing" is evidence. "The export service is broken" assumes a cause that has not been confirmed.

For example:

Expected: Selecting Export PDF opens a save dialog.

Actual: Selecting Export PDF closes the menu, but no save dialog appears and no file is created.

Add frequency beside the result. State whether the problem occurs every time, intermittently, or only after a particular prior action.

Reproduce from a known starting point

A known starting point removes hidden setup from the report. Close and reopen the app, create fresh test data, or reset the relevant setting before you capture the sequence.

Confirm the bug once from that state before documenting it. If the problem no longer occurs, record what changed instead of forcing a confident set of steps from memory.

Capture one screenshot per required action

Each screenshot should help the reviewer repeat the next action or recognize the failure. Capture the starting state, every required click or input, the first incorrect state, and any error message that changes the diagnosis.

Skip actions that do not affect the result. Moving a window aside or opening an unrelated panel adds noise unless that action is part of the trigger.

When using Action Capture, start with the clean state and reproduce the problem at a normal pace. Shotomatic saves the target state immediately before each accepted click and marks the click location, so the captured sequence gives you a first draft of the reproduction steps. Free sessions support 5 saved steps, while Pro removes the session step limit.

Add text that explains state changes

Short text should explain what the screenshot alone cannot show. Name the control, include the value to enter, and state the expected transition after the action.

Write steps in this form:

1. Action: Select Export PDF.
2. Expected checkpoint: A save dialog opens.
3. Observed result: The menu closes and no dialog appears.

Avoid text that only repeats a visible marker, such as "click here." A click marker already shows the location. The sentence should tell the reviewer what the control is and what to look for next.

Protect private information

Private information should be removed before the report leaves the test environment. Use sample accounts and test data when possible because replacing the source data is safer than covering it later.

When real data cannot be avoided, crop irrelevant areas and blur names, email addresses, messages, tokens, license details, customer records, and notification previews. Keep enough surrounding interface visible for the reviewer to identify the screen.

See How to Redact Sensitive Information from Tutorial Screenshots for the crop, blur, and sample-data decision process.

Use this bug report structure

The following structure keeps the report complete without turning it into a long narrative:

Title:

Environment:
- App/build version:
- macOS/device:
- Account or permission state:
- Relevant settings:

Expected result:

Actual result:

Frequency:

Prerequisites:

Steps to reproduce:
1.
2.
3.

Evidence:
- Screenshot for each required action
- First visible failure
- Error message or log, if relevant

Workaround:

Additional notes:

This is a writing structure, not an importable Shotomatic template. Copy it into the issue tracker or support system your team already uses.

Test the report before sending it

A final reproduction pass finds missing assumptions. Start from the environment listed in the report and follow only the written steps without relying on memory.

The report is ready when the same sequence reaches the stated result, every required value is present, and the screenshots show the correct screen in the correct order. If a step depends on timing or motion, attach a short recording as supporting evidence while keeping the written sequence as the primary reference.

Action Capture can collect the click sequence, but the report still needs the environment, expected result, actual result, and frequency. Use How to Create a Step-by-Step Guide from Clicks on Mac for the general capture and editing workflow.