How to write a good bug report: a practical template with examples

A bug report has one job: let someone else see the problem without asking you a single question. In manual game and software testing, the difference between a report that gets fixed today and one that bounces back for "needs more info" is almost always structure. This is the template I use.

The anatomy of a good report

1. Title: what is broken and where, in one line.
2. Environment: build number, platform, OS, hardware, language, account type.
3. Preconditions: what state the game or app must be in first.
4. Steps to reproduce: short, numbered, deterministic.
5. Expected result: what should happen.
6. Actual result: what really happened.
7. Frequency: always, sometimes (for example 3 out of 5 attempts), once.
8. Severity and priority: how bad it is and how soon it should be fixed.
9. Attachments: screenshot, video, log file, save file.

Write the title last

A good title names the object, the action and the result. Compare these:

• Bad: "Game crashes"
• Better: "Game crashes when opening the Settings menu after loading a save"

A developer reading the list of titles should be able to guess the area of the code without opening the report.

Environment matters more than you think

Many bugs depend on the platform, display resolution, language, graphics driver or even whether a game was launched from a fresh install. Always write the exact build version. If you cannot reproduce a bug on another machine, say so: that is useful information, not a failure.

Steps to reproduce

Keep every step one action. Avoid words like "then somehow" or "I did stuff".

1. Launch the game and load the save "Chapter 2".
2. Press Esc to open the pause menu.
3. Click "Settings".
4. Change the language to German and press Apply.

If the bug only happens after a long session or a specific sequence, say that explicitly. If you found the minimal path to the bug, give that, not your whole play session.

Expected vs actual

Never skip the expected result. What looks like a bug to you may be intended, and what the developer expected may be different from what you assumed. Writing both lets the team decide quickly whether it is a defect, a design question or a misunderstanding.

Severity and priority

Severity is the impact on the product, priority is the urgency of the fix. A typo in the credits is low severity; a crash that loses a player's save is critical. A spelling mistake in the main menu on release day can still be high priority. Be honest and consistent: if everything is "critical", nothing is.

Attachments

• A screenshot with the problem area circled.
• A short video for anything involving timing, animation or sound.
• The log file and, for crashes, the crash dump or error code.
• The save file if the problem depends on game state.

Always remove personal data from screenshots and logs before attaching them.

A full example

Title: Quest marker disappears after fast travel from the Market to the Harbour

Environment: Windows 11, build 0.8.3.1245, 1920×1080, English, new profile

Steps:

1. Accept the quest "Lost Cargo" in the Market.
2. Open the map and fast travel to the Harbour.
3. Open the quest log and select "Lost Cargo".

Expected: The quest marker is shown on the minimap and the map.

Actual: No marker is shown. The quest log still lists the quest as active.

Frequency: 5 out of 5 attempts. Does not happen when walking to the Harbour.

Severity: Major. Players cannot find the objective without external help.

Before you press submit

• Can you reproduce it again from your own steps?
• Is it already in the tracker? Search first.
• Does one report describe one problem? Split multiple issues into separate reports.
• Would a colleague understand it without talking to you?

Good reports are a form of respect for the people who will fix the problem. You can see how I describe issues in my QA reports, and if your project needs a tester, you can contact me.

More articles

← All articles