Bug Report Example: Named Elements Beat Pixel Guesses

A good bug report example tells the developer which element broke by its accessibility name and role, not "the button in the top right corner." The best reports ship the exact named UI element (AXButton "Submit Order"), its frame coordinates, and a cropped screenshot, so a human or AI agent can fix it without asking "which one?"

Most bug reports fail here. They describe position or color, the element moves in the next build, and the ticket bounces.

Developers and AI coding agents need executable data — a named target they can query in code. QA engineers who file dozens of reports a week know the pain: a vague description means a Slack ping, a screenshare, and a ticket that sits in triage.

The gap is that most tools capture pixels (CleanShot X, Jam.dev) or freeform annotations (Marker.io). They never resolve the underlying accessibility element the OS knows about.

What makes a bug report example actually good?

A good bug report gives the developer or AI agent three things: the exact UI element by name and role, repro steps tied to that element, and a screenshot cropped to the failure. If you write "the blue Submit button is disabled when it shouldn't be," the developer opens the screenshot, sees four blue buttons, and asks which one.

If you write AXButton "Submit Order" (frame: x=1142 y=687 w=120 h=36, parent: AXGroup "Checkout Footer") remains AXEnabled=false after entering a valid email, they know the target, the property, and the context.

The bug report life cycle starts when a tester finds unexpected behavior, ships a report to the tracker, a developer triages it, an engineer fixes the code, QA verifies the fix, and the ticket closes. The bottleneck is step two: if the report is ambiguous, the ticket gets labeled "needs repro" and stalls.

Named elements skip the ambiguity. The accessibility tree is the same tree the OS uses for VoiceOver, so the label and role stay stable across builds unless someone renames them.

When you learn how AI agents know which UI element you mean, you realize they need the same named data a human QA engineer should file. A screenshot alone is pixel soup to an agent.

A named element is a direct pointer.

How to make a bug report in testing: the workflow that works

The workflow that works is: see the bug, circle or point at the broken element, speak the issue, and let the tool resolve the element and file the ticket. This is how to make a bug report in testing when you are filing twenty bugs a day.

Here is the manual baseline most QA teams use today:

1. Reproduce the bug in the app.
2. Take a screenshot (⇧⌘4 or CleanShot X).
3. Open the screenshot, annotate the broken element with an arrow or rectangle.
4. Open Linear, GitHub, or Jira, create a new issue.
5. Write a title, describe the repro steps, paste the screenshot, fill severity and labels.
6. Submit, then ping the dev team in Slack with a link.

The failure mode: the annotation is a red box around "the button," the developer sees three buttons in that box, and asks which one. The report goes back to you.

The point-and-speak workflow on macOS:

1. Hold ⌥⌘A, circle or point at the broken element, speak the issue.
2. PinVari resolves the AXButton "Submit Order" with its role, label, frame, enabled state, and parent chain, plus a confidence score.
3. The tool transcribes your speech on-device, crops the screenshot to the circled region, and hands everything to your tracker or AI agent.
4. If you have configured Linear or GitHub, it files the ticket with the named element as a structured field.

The developer opens the ticket and sees a named target plus your spoken description. No ambiguity.

What is a bug report in mobile vs desktop testing?

What is a bug report in mobile testing is usually a combination of device logs, a screen recording or screenshot, and written repro steps. Mobile bug reports often include device model, OS version, and network state because the same bug behaves differently across phones.

The tooling is more fragmented: TestFlight for iOS beta feedback, Firebase Crashlytics for crash reports, manual screenshots pasted into Jira.

Desktop testing, especially macOS, has an advantage: the Accessibility API is a first-class tree of every UI element. You can query the element under any point with AXUIElementCopyElementAtPosition and get its role, title, value, frame, and parent chain.

Mobile platforms have accessibility APIs too (UIAccessibility on iOS, AccessibilityNodeInfo on Android), but third-party bug-capture tools rarely expose them. They ship pixel screenshots and logs instead.

The gap is that developers and AI agents need the named element, not a crop. If you file a mobile bug as "the login button doesn't respond," the developer searches the view hierarchy near the coordinates you described.

If you file it as UIButton "Login" with a frame and action, they jump straight to the code.

AI bug report tool for developers: what agents need

An AI bug report tool for developers must give the coding agent three things: the named UI element, the spoken or typed instruction anchored to that element, and a screenshot cropped to the region. The agent then writes a test, proposes a fix, or asks a clarifying question.

Here is why the named element matters. If you hand Claude Code a full-window screenshot and say "fix the Submit button," the agent sees many buttons and guesses based on position or OCR.

Can Claude Code see my screen? Yes, via screenshots you attach — but screenshots are unstructured pixels.

The agent doesn't know which rectangle is the button you meant.

If you hand the agent AXButton "Submit Order" with role, title, frame, parent, confidence, and provenance, it knows the exact target. It can write a Playwright click or search the codebase for "Submit Order".

Named elements give agents executable hooks, not pixel archaeology.

The MCP layer is how agents consume this data. PinVari runs a local MCP server on 127.0.0.1 that exposes pinvari_next_instruction.

When the agent calls it, it receives the resolved element, the spoken instruction, and a crop. Then it can call pinvari_mark_done.

A paste-ready bug report example

Use this template in Linear, GitHub, or Jira.

Title: AXButton "Submit Order" stays disabled after valid email
Environment: macOS 14.5, App v2.3.1, Apple Silicon
Element: AXButton "Submit Order"
  frame {1142, 687, 120, 36}
  parent AXGroup "Checkout Footer"
  AXEnabled=false
Steps:
  1. Open Checkout
  2. Enter a valid email in AXTextField "Email Address"
  3. Observe Submit Order
Expected: Button becomes enabled
Actual: Button stays AXEnabled=false
Evidence: cropped screenshot of the footer

That is a bug report example a developer can act on without a Slack ping. Browser-only tools like Jam.dev add console logs for web apps, but they cannot see native Mac windows; the Jam.dev alternative for native Mac apps covers that gap.

A point-and-speak file to Linear and GitHub fills this template for you. PinVari is a one-time $39 launch license, on-device, with nothing uploaded by default.

FAQ

What should a bug report example include?

A title, environment, named element, steps to reproduce, expected vs actual, and cropped evidence. The named element is the piece most templates skip and the piece that stops bounce-backs.

How do I make a bug report in testing quickly?

Circle the broken control, speak the issue, and let a capture tool resolve the accessibility element and file the ticket. That is faster than screenshot, annotate, open tracker, type, paste.

What is the bug report life cycle?

Find, file, triage, fix, verify, close. Ambiguous reports stall at triage. Named elements keep the ticket moving.

What is a bug report in mobile testing?

Device logs, a screenshot or recording, repro steps, and device plus OS details. Mobile tools rarely expose the named accessibility node; desktop macOS tools can.

Can an AI agent use a bug report example like this?

Yes, if the report includes a named element, not only a picture. Agents act on role, label, and frame. They guess on pixels.

Should I still attach a screenshot?

Yes, as evidence for spacing, color, and layout. Pair it with the named element so the screenshot is proof, not the only pointer.