How to Write Bug Reproduction Steps for Games

Learning how to write bug reproduction steps for games is a common challenge for game developers. Reproduction steps are the core of every bug report. They are the instructions that a developer follows to see the bug with their own eyes. When steps are clear, specific, and complete, the developer can reproduce the issue in minutes and start fixing it immediately. When steps are vague, incomplete, or assume too much, the developer spends hours guessing, and the bug may never get fixed at all. This guide breaks down the craft of writing reproduction steps that work on the first try.

The One-Action-Per-Step Rule

Each numbered step in your reproduction should describe exactly one action. Not two actions, not a sequence of actions, and not a general description of an activity. One step, one action.

This rule exists because compound steps hide important details. When a step says “Open the inventory and equip the fire sword,” it looks simple, but it actually contains multiple actions: open the inventory, navigate to the weapons tab, find the fire sword, and equip it. If the bug is triggered by a specific action within that sequence — say, the equip action when the inventory is scrolled to a certain position — the compound step obscures the trigger.

// Bad: compound steps hide the trigger
//
// 1. Open inventory and equip the fire sword
// 2. Go to the cave and fight the ice boss
// 3. The boss health bar disappears
//
// Good: one action per step, specific names
//
// 1. Launch the game and select "Continue" from the main menu
// 2. Press I to open the Inventory panel
// 3. Click the "Weapons" tab
// 4. Click "Fire Sword" to select it
// 5. Click "Equip" in the item detail pane
// 6. Press I to close the Inventory panel
// 7. Walk north to the Ice Cavern entrance
// 8. Enter the boss arena through the blue door
// 9. Attack the Ice Lord with the Fire Sword
//
// Expected: Ice Lord health bar decreases and remains visible
// Actual: Ice Lord health bar disappears after the first hit

Yes, the detailed version has more steps. That is the point. Each step is unambiguous. A developer following these steps will do exactly what the tester did, in the same order, with no room for interpretation.

Use Specific Names, Not Descriptions

Games have names for everything: levels, items, NPCs, UI elements, abilities, menus. Use those names in your reproduction steps instead of generic descriptions. “The sword” could be any of dozens of swords. “Fire Sword” is unambiguous. “The boss” could be several encounters. “Ice Lord in the Ice Cavern” is one specific boss in one specific location.

If you do not know the in-game name of something, describe it with enough specificity that the developer can identify it. “The third option in the settings menu under Graphics” is better than “one of the graphics settings.” “The NPC standing next to the well in the village square” is better than “some NPC in the village.”

For UI elements, describe them by their label text and position. “Click the ‘Apply’ button at the bottom-right of the Settings panel” leaves no room for confusion. If the element does not have visible text, describe it by its icon and location: “Click the gear icon in the top-right corner of the HUD.”

Make Assumptions Explicit

The most common reason reproduction steps fail is hidden assumptions. The tester assumes the developer knows certain things about the game state that are not stated in the steps. Every assumption about the game state needs to be written down explicitly.

Common hidden assumptions include: the character class or build, items in the inventory, quests that have been completed, settings that have been changed from defaults, the current game difficulty, whether the game is in online or offline mode, and the current time of day in the game world. Any of these could affect whether a bug occurs.

The easiest way to eliminate hidden assumptions is to start from a completely fresh state — a new game or an attached save file — and include every action needed to reach the bug from that state. If starting fresh is impractical because the bug requires significant game progress, list the prerequisites at the top of the steps: “Prerequisites: Complete the Forest quest line, have a Level 20+ character, equip the Fire Sword.”

Expected vs. Actual: The Critical Comparison

After the numbered steps, every bug report needs two sections: Expected Behavior and Actual Behavior. These are not optional, and they are not the same as the bug title.

Expected behavior describes what should happen when the steps are followed correctly. This might seem obvious to the tester, but it is not always obvious to the developer. In a complex game, the intended behavior of a system may not be clear to everyone on the team. A developer working on the rendering pipeline might not know what the intended behavior of a gameplay mechanic is. The expected behavior section tells them what the design intent is.

Actual behavior describes what happens instead. Be specific. “The health bar breaks” is vague. “The health bar disappears entirely after the first hit and does not reappear for the rest of the fight” is specific. “The game crashes” is less useful than “The game freezes for two seconds, then closes to desktop with no error message.”

The gap between expected and actual behavior is the bug. Making both explicit helps the developer understand not just what is wrong, but what “right” looks like. This is especially important for subtle bugs where the difference between correct and incorrect behavior is small.

Level of Detail: Finding the Balance

There is a tension between being thorough and being concise. Steps that are too brief miss critical details. Steps that are too verbose bury the important actions in a wall of text. The right balance depends on the audience.

For internal QA teams where the developer is familiar with the game, steps can be moderately abbreviated. “Equip Fire Sword” is sufficient if both parties know there is only one Fire Sword and one way to equip it. For external playtesters or player-submitted reports, more detail is appropriate because the developer cannot assume the reporter understands the game’s internal structure.

A useful heuristic: write steps detailed enough that a new team member who joined yesterday could follow them without asking questions. This level of detail catches most hidden assumptions while remaining practical to write.

“I tell our testers to write steps as if they are writing instructions for someone who has never played the game. It feels like overkill, but those are the reports that get fixed the fastest.”

Common Mistakes in Reproduction Steps

Starting from an unclear state: “While playing the game...” does not tell the developer where or when. Always specify the starting point.

Using relative directions without a reference: “Go left” depends on which way the camera is facing. Use cardinal directions, landmark references, or coordinates.

Omitting timing: Some bugs depend on timing. “Press jump and attack at the same time” is less precise than “Press attack, then press jump within 0.5 seconds.” If timing matters, say so.

Combining the bug trigger with the observation: “Open the inventory and the items are duplicated” mixes the action with the result. Separate them: step 5 is “Open the inventory,” and the Actual Behavior section says “All items in the inventory appear twice.”

Not verifying the steps yourself: Before submitting, follow your own steps from the beginning. If you cannot reproduce the bug from your written steps, revise them until you can. This is the single most effective quality check for reproduction steps.

Related Issues

For the broader context of writing reproducible reports including save files and seed values, see how to write reproducible bug reports for games. For a comprehensive guide to all aspects of bug reporting, read how to write good bug reports for game development. For a ready-to-use template that structures reproduction steps for you, check our bug report template for game QA testers.

Test your own steps before you submit. Follow them exactly as written, from the beginning. If you skip this check, you are trusting your memory instead of your documentation.