Mac bug report checklist: repro, evidence, and context

The short answer: summarize the failure, start from a known state, write the exact steps, separate expected from actual results, record the environment and frequency, then attach only the evidence that answers an investigation question. Use color evidence for visual failures, system trends for slow or hot behavior, and process-level tools when the report must identify an owner.

This checklist is for Mac app makers, designers, front-end developers, support teams, and indie teams who need better reports for visual regressions and performance complaints. It is not a replacement for a crash log, Instruments trace, accessibility audit, sysdiagnose, or Apple Feedback Assistant when those are the right artifacts.

Disclosure: I build TeenyApps, including TeenyColor for local color evidence and TeenyStat for first-pass system vitals. My bias is toward small native Mac utilities. Apple's tools still own deep diagnosis.

The bug-report evidence ladder

01Start from a known state, then write the repro

The repro is the spine of the report. Begin with the state that exists before step one: fresh launch or already running, signed in or signed out, document open or closed, light or dark appearance, permission allowed or denied, display connected or disconnected. Without that baseline, two people can follow the same actions from different starting points and get different results.

Write the path as actions someone else can run: open this build, choose this account, go to this screen, click this control, switch this appearance, wait this long, observe this result. Keep the first version short. "Open Settings, switch to dark mode, select Team, hover the disabled Save button" is stronger than a page of guesses about CSS, SwiftUI state, browser cache, or display profiles.

Run the exact sequence again before filing. If it repeats, say how many attempts reproduced it. If it is intermittent, record both the successful and failed attempts plus the condition that changed. Frequency is evidence; "sometimes" is not.

If the report turns into a live troubleshooting session, use the Mac support call setup to clean copied context, choose what can be shown, and set app audio before anyone joins.

Use a clean name for the artifact set. A folder called settings-dark-disabled-save tells the next person more than bug screenshots. It also makes duplicate reports easier to compare later.

02Record the environment that could change the result

Record the app name and build, macOS version, Mac model when hardware matters, and any account, permission, appearance, display, power, or peripheral state that the repro depends on. Do not paste a full hardware inventory into every issue. Include a field only when it could explain the result or help someone reproduce it.

Apple's current Feedback Assistant guidance asks reporters to summarize the technology, platform, and version; give detailed steps; separate expected and actual results; and note factors such as iCloud or Accessibility settings that may influence the behavior. That structure works for an internal issue tracker too.

A useful environment line might read: App 2.4 (184), macOS 26.5, Apple silicon, dark mode, Screen Recording allowed, external Display P3 monitor at 2x scaling. It is compact, but it preserves every condition needed for this visual repro.

03Capture the screen state without leaking private data

Apple's screenshot tools are enough for most UI reports. Capture the whole screen when layout and display context matter. Capture a portion when the bug is local to one component. Use a short recording when the bug depends on hover, loading, animation, drag, or timing.

Before you attach anything, crop or mask customer names, tokens, unreleased features, and internal dashboards. A useful bug report should not turn a UI mistake into a privacy mistake.

Give each attachment a job. A screenshot should prove the visible state. A recording should prove order or timing. A sampled value should prove a rendered color. A process view should prove which process owned a load. If an attachment does not answer a question in the report, leave it out.

04Use color values when the bug is visual

A color complaint needs more than "this looks off." Capture the rendered state, sample the actual pixel, and label what the value represents: primary label, card background, warning icon, focus ring, disabled text, selected row, or destructive button.

TeenyColor fits this first-pass job because its homepage and Swift source confirm native screen sampling with Apple's color sampler, sRGB conversion, selected copy formats, local history, names, pins, and text or JSON palette export. That is useful when you need to include the value in an issue comment without uploading a private screenshot to an online tool.

Be precise about the limit. A single sampled hex value proves what rendered at one pixel. It does not prove why it rendered, whether a design token is wrong, or whether every state fails. Pair the value with the screenshot, the role, and the state.

For deeper color evidence, use the TeenyColor guide to report UI contrast bugs with color evidence. It keeps the screenshot, foreground/background values, and WCAG threshold together.

05Report contrast with both values, not one screenshot

Contrast bugs need a pair: foreground and background. If the text is too faint, attach the sampled foreground value, the sampled background value, text size, UI state, and the standard you are checking against.

The W3C WCAG guidance uses 4.5:1 for normal text at Level AA, 3:1 for large text, and 7:1 for normal text at Level AAA. TeenyColor's source includes WCAG contrast math and the app shows badges against white and black backgrounds. That can catch common mistakes quickly, especially black or white text choices. For arbitrary foreground and background pairs, include both sampled values in the report so the reviewer can verify the exact pair.

Do not round away the evidence. "Gray text on white fails" is weaker than "disabled label sampled as #8E8EA0 on #FFFFFF in light mode; normal-size body text reads below AA." The second version points to a fix.

06Capture system trend before blaming the app

Performance reports get noisy fast. A Mac can feel slow because the app is doing real work, another process is busy, memory pressure is high, a browser tab is misbehaving, a video export is running, or a fanless Mac is thermally constrained.

TeenyStat is useful as a quiet first signal. The homepage and source confirm CPU usage, memory usage, fan speed when available, per-core CPU view, 60-point sparklines, session high and low values, and threshold alerts. Its source reads CPU through host_processor_info, memory through host_statistics64, and fan values through SMC keys where the Mac exposes them.

The boundary is important. TeenyStat does not tell you which process is guilty. If the report needs a process name, memory-pressure details, CPU history, swap, or a quit path, use Activity Monitor. A good report says when the symptom started and what the system trend looked like before anyone started closing things. The TeenyStat guide to capturing CPU and memory evidence for Mac bug reports turns that into a tighter issue template.

07Match the escalation artifact to the owner

Activity Monitor is the right tool when the next decision depends on process-level evidence. Use it when the app is not responding, CPU stays high after the repro, memory pressure is suspicious, or the same helper process appears every time.

Do not attach Activity Monitor out of habit. A giant process table can distract from a simple UI bug. If you do include it, crop to the relevant tab and columns. For CPU, show the process and timing. For memory, show memory pressure or the process-level memory column that explains the symptom.

For an Apple platform or framework issue, Feedback Assistant is the owning path. Apple's Feedback Assistant app automatically attaches a sysdiagnose, while UI issues benefit from screenshots or recordings and app issues may benefit from a minimal sample project. Apple also asks for a Mac System Information Report for crashes, kernel panics, hardware bugs, and printing issues. Those artifacts are deeper than a normal product ticket, so collect them when that path owns the diagnosis.

Apple documents that Activity Monitor can quit a process, including one in a loop or not responding. Treat quitting as an action step, not a screenshot decoration. If it can lose work, say so before someone repeats the repro on a real project.

Copyable Mac bug report template

1. Summary: name the app or technology, platform, version, symptom, and triggering condition.
2. Starting state: record account, document, permission, appearance, display, power, or hardware state only when relevant.
3. Steps to reproduce: list the shortest numbered path you repeated.
4. Expected result: what should happen.
5. Actual result: what happened instead.
6. Frequency: record attempts and results, plus the condition that changed when it did not reproduce.
7. Environment: app build, macOS version, Mac model when relevant, and connected display or peripheral details when relevant.
8. Focused evidence: attach a screenshot, recording, color pair, system trend, process view, log, or diagnostic only when it supports a named claim.
9. Privacy check: remove customer data, credentials, private paths, and unreleased information that the owner does not need.

Five checks before you file

1. The title identifies the product area, failure, and condition without opening the attachments.
2. The repro begins from a known state and records whether the same sequence repeated.
3. Expected and actual results describe observable behavior, not a guess about the cause.
4. Every attachment answers a question named in the issue.
5. The report routes deeper evidence to the tool or team that can act on it.

Sources checked

• TeenyColor claims were checked against the TeenyColor homepage and local Swift source for screen sampling, sRGB conversion, copy formats, local history, names, pins, export, and WCAG contrast badges against white and black.
• TeenyStat claims were checked against the TeenyStat homepage and local Swift source for CPU reads, memory reads, fan speed reads, per-core CPU, sparklines, session high/low values, thresholds, and fanless-Mac behavior.
• Apple Support: Take a screenshot on Mac.
• Apple Developer: Feedback Assistant for report summaries, reproduction steps, expected and actual results, contextual factors, sysdiagnose, System Information, sample projects, screenshots, and recordings.
• Apple Support: View CPU activity in Activity Monitor on Mac.
• Apple Support: View memory usage in Activity Monitor on Mac.
• Apple Support: Quit an app or process in Activity Monitor on Mac.
• W3C WCAG 2.2: Success Criterion 1.4.3 Contrast (Minimum).

FAQ

What should a Mac bug report include?

A useful Mac bug report includes a concise summary, known starting state, exact reproduction steps, app and macOS versions, expected and actual results, frequency, and only the screenshots, logs, or performance evidence needed to investigate the issue.

Should I attach Activity Monitor to every Mac performance bug?

No. Start with the symptom and a short system trend. Open Activity Monitor when you need process names, memory pressure, CPU history, or a safe quit decision.

Can a color picker prove a UI bug?

It can prove the rendered color value you saw. For contrast bugs, include the foreground, background, UI state, and relevant WCAG threshold instead of sending a lone hex value.