Writing good repro steps
Reproduction steps, or repro steps, are a set of instructions that anyone can follow to see an issue that you have identified. The purpose of repro steps is to help a developer reliably see the issue clearly and give some insights into what the bug is.
To do this, they should be as specific as possible. There are often many ways to accomplish the same goal, so it helps us to know the exact things you do in order to see the bug.
Here is an example from this issue.
- drag the cat partially off the stage
- Add the following stack
When green flag clickedforeverif touching mouse pointerchange color effect by 15
- place the mouse off the stage but over where the cat would be
- Note: the cat changes color
You can substitute a screenshot of a stack of blocks instead of listing them out, like this:
A picture is worth a thousand words. If the issue can be seen visually it can be very helpful to take a screenshot and include it in the issue. Windows, Mac, and ChromeOS all include a way to take a screenshot. It's best if you crop the screenshot to the region of the page that shows the issue the most clearly.
Animated Gifs are great for showing off bugs as well, especially when it comes to showing how something has changed. Just make sure that gifs are cropped to the relevant portion of the screen and are only long enough to show the issue. A good tool for taking screenshots is Licecap which you can find here.
A gif to go with the example above looks like this:
Also, remember not to include personal information in your screenshots and gifs.
Once you've written steps that that you can follow to see the issue it can be very helpful to refine them to give as much information as you can. Three questions you can ask yourself that can help with this process are:
- Is there a simpler way to see this issue?
- Is this the only way to see this issue?
- Are there other places that you would expect to see this issue but you can't?
One of the best ways to improve your repro steps is find the simplest way to see the issue. Are there any steps you can skip and still see it? If you see the issue in a big complicated project, can you make a simpler project that shows the same issue?
To try to answer the other questions you can try out a few different variations of some of the steps. For example, if you see an issue with the circle tool in the paint editor, see if you can see the same issue with the square tool. What if you draw a circle with the paint brush? Does this happen when you use a different browser?
If you can reproduce it multiple ways, try to include that in the steps. For example:
- Select the circle or square tools.
It can also be helpful to let us know if you CAN’T get it to happen in another way if the other way seems like it should produce the bug. If that's the case you could say something like:
- select the circle tool, note: you can't see this issue with the square tool.
If it makes it clearer you can write multiple sets of repro steps but always make sure that you show at least one way to see the problem.
Some issues are hard to reproduce. This could be because it only happens some of the time when you do the same steps, or because some conditions are hard to achieve. If this is the case, we recommend waiting to file the issue until you’ve at least seen it a second time.
If you see the issue multiple times but it's hard to make it happen every time it's probably still worth filing an issue. In that case write down steps for when you DID see it, but make sure you mention that you can’t get it to happen every time. Try to tell us how many times it happens out of ten tries.