Format of Bug Report: Fields, Template, Examples
The format of bug report writing is a title, the environment, steps to reproduce, the expected result, the actual result, and evidence. A strong format of bug report adds one field most templates leave out: the exact named UI element that failed, written as its accessibility role and label rather than "the blue button on the right." Most guides on the format of bug report writing stop at the six standard fields, which is why so many tickets still bounce back with "which element?" or "how do I reproduce this?"
QA engineers file dozens of these a week, and every bounced ticket is a Slack ping, a screenshare, and a lost afternoon. The report that lands names the target, ties the steps to it, and ships visual proof, so the developer or coding agent reads it once and fixes the right thing.
What is the standard format of bug report writing?
The standard format of bug report writing is six fields: a descriptive title, the environment, numbered steps to reproduce, the expected result, the actual result, and evidence such as a screenshot or log. Each field answers one question the receiver would otherwise have to ask you.
The title states the target and the condition in one line. The environment pins down the OS version, app build, and hardware, because a bug on Apple Silicon may not repeat on Intel. The steps let anyone reproduce the failure without a call, and the expected-versus-actual pair defines what "broken" means precisely.
Evidence is where most reports stop, and it is not enough on its own. A screenshot is proof, not an instruction, because a picture still forces the developer to figure out which control you meant and how to trigger it.
The single biggest upgrade to any bug report format is naming the failed element by its accessibility role and label instead of its color or position. Named elements stay stable across builds; "the button on the right" moves the instant the layout changes.
Which fields does every bug report format need?
Every bug report format needs the six standard fields plus the named element and the severity. The named element is the field that turns a description into a target a developer or an AI agent can act on without guessing.
On macOS, every control is already a named object. The Accessibility API exposes it through AXUIElementCopyElementAtPosition, which returns the element's role, title, value, frame, and parent chain. That means the "which element" question has a factual answer the operating system will hand you, if your tooling reads it.
Here is what each field carries and why it matters.
| Field | What it captures | Why it gets skipped | Cost of skipping |
|---|---|---|---|
| Title | Element + condition in one line | Rushed | Triager can't prioritize |
| Environment | OS, build, chip | "Everyone knows" | Intel vs Silicon regressions hide |
| Named element | AX role, label, frame, state | Hard to get by hand | Developer edits the wrong control |
| Steps to reproduce | Numbered path to the failure | Tedious | Ticket sits in "needs repro" |
| Expected vs actual | Definition of "broken" | Assumed obvious | Debate replaces a fix |
| Evidence | Cropped screenshot or log | Full-window PNG pasted instead | Reader hunts the pixel |
| Severity | Impact and urgency | Left blank | Wrong queue order |
The two fields testers skip most are the named element and the environment. Without the element, the developer guesses; without the environment, nobody can tell a version regression from a hardware quirk. Those two omissions cause most bounced tickets.
A worked bug report example shows the gap plainly: "the blue button is broken" versus AXButton "Submit Order" (AXEnabled=false, frame {1142,687,120,36}). The second version is something a developer greps for.
A copy-paste bug report template
A reusable bug report template or bug report form enforces the format so nothing important gets dropped under deadline pressure. Paste this into any tracker and fill it top to bottom.
Title: [Named element] [what's wrong] [under what condition]
Environment: macOS 14.5, App v2.3.1, Apple Silicon
Element: AXButton "Submit Order"
(frame {1142,687,120,36}, parent AXGroup "Checkout Footer")
Steps to reproduce:
1. Open Checkout
2. Enter a valid email in AXTextField "Email Address"
3. Observe the Submit Order button
Expected: Button becomes enabled (AXEnabled=true)
Actual: Button stays AXEnabled=false
Evidence: screenshot cropped to the button + footer
Severity: HighThe template works because it puts the named element in the title, not buried in the body. A triager reading AXButton "Submit Order" stays disabled after valid email knows the target and the trigger before opening the ticket.
Store the template as a saved issue form in your tracker so it is one click, not a memory test. Most bug reporting software supports templated forms for Jira, GitHub, and Linear; use them so the format is the default, not a discipline you have to maintain.
If you are choosing where these reports go, the comparison of bug reporting software for QA teams walks through which tools capture the element for you and which leave you typing it by hand.
What does a good bug report example look like?
A good bug report example reads as a factual, reproducible instruction rather than a complaint. It names the element, states the environment, numbers the steps, and pairs expected with actual, so the receiver never has to interpret intent.
Compare two versions of the same defect.
The weak version: "The submit button doesn't work on checkout. Tried a few times, still broken. Screenshot attached." This forces four follow-up questions before anyone can act.
The strong version follows the template above. It says the AXButton "Submit Order" stays AXEnabled=false after a valid email is entered on macOS 14.5, app v2.3.1, with numbered steps and a cropped screenshot. A developer reads it once and reproduces it in under a minute.
The difference matters more when an AI agent receives the report. How AI agents know which UI element you mean comes down to whether you handed over a resolved target or a picture to guess against. A named element as structured data lets Claude Code or Cursor look the label up in the codebase; a free-text description plus a full-window image forces an OCR-and-guess pass that often edits the wrong control.
Be wary of "AI bug report" tools that only OCR a screenshot. OCR reads visible text; it does not resolve an element's role, enabled state, or parent chain. When the accessibility tree is available, resolving the real element beats guessing from pixels, and a low-confidence match should prompt a confirm rather than a silent guess.
How do you file a bug report in ten seconds?
You file a bug report in ten seconds by capturing the named element, the spoken instruction, and a cropped screenshot in one action instead of assembling them across four apps. The manual path, screenshot then annotate then open the form then paste, runs two to four minutes and is exactly the friction that makes testers skip small bugs.
Point-and-speak capture collapses that. You hold ⌥⌘A, circle or point at the broken control, and say the issue, for example "Submit Order stays disabled after a valid email." The tool resolves the AXButton "Submit Order" with a confidence score, transcribes your speech on-device, crops the screenshot to the region, and files everything to your destination.
The routing is where the time is actually won. A point-and-speak bug report filed to Linear or GitHub puts the named element in a structured field so the developer clicks straight to the code, and the same capture can go to an MCP-connected agent that drafts a regression test before a human triages it.
For QA engineers who want named, reproducible reports without the manual overhead, PinVari files this format at a one-time $39 launch price, with on-device transcription, no API keys, and nothing uploaded by default. It reads the macOS Accessibility API, so it works in native apps, Electron windows, and browsers alike, not only in a Chrome tab. One capture, filed in about ten seconds, replaces the whole screenshot-annotate-paste ritual.
FAQ
What is the standard format of a bug report?
The standard format of a bug report is a title, environment, steps to reproduce, expected result, actual result, and evidence. The strongest reports add the named UI element by its accessibility role and label, so the developer or AI agent has an executable target rather than a description to interpret.
What fields should a bug report template include?
A bug report template should include title, environment, named element, numbered steps, expected versus actual, evidence, and severity. The two fields most often skipped, the named element and the environment, are the two that cause the most bounced tickets, so keep them mandatory in the form.
How do I write a bug report an AI agent can act on?
Include the named UI element as structured data, the instruction tied to that element, and a screenshot cropped to the failure. Agents like Claude Code and Cursor can consume an MCP payload with the element role, title, frame, and confidence, then find the label in the codebase instead of guessing from a full-window image.
What is a good bug report example versus a bad one?
A bad example says "the blue button is broken" with a full-screen PNG. A good example names AXButton "Submit Order" (AXEnabled=false), pins the environment, numbers the steps, and crops the screenshot to the button, so the reader reproduces the defect without asking a single follow-up question.
Should the element name go in the title or the body?
Put the named element in the title. A title like AXButton "Submit Order" stays disabled after valid email tells the triager the target and the condition before they open the ticket, which cuts triage time and keeps the report out of the "needs repro" pile.
How long should filing a bug report take?
A manual screenshot-and-form workflow runs two to four minutes per bug. A point-and-speak workflow that resolves the element and files it for you runs about ten seconds, and that saved time is what lets testers file the small bugs they would otherwise skip.
Hand your agent the exact element
PinVari resolves what you point at into a named, executable instruction — on-device, no keys, your own agent. If you run Claude Code, it is one command.
claude mcp add pinvariGet PinVari — $39 →
