-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
How to make a great reproduction case
When we triage issues, one of the first things we do is try to understand the problem and reproduce it. The best way to make it easy is to make a great reproduction case.
A reproduction case is usually composed of three things: a demonstration page (demo), steps to reproduce (STR), and an expectation. To verify and reproduce the issue, all one has to do is to open the demonstration, and execute the steps to reproduce, and verify the expectation.
There seems to be a lot of confusion about what 'Steps to reproduce' are. Simply put, they are the actions that you take once the page has loaded, code included. The code you are using, for example the Selectize options, the HTML tags or the JQuery library, are not part of the STR, but rather part of the demonstration.
Here's what a great reproduction case looks like:
(taken from #1172)
Demo: https://jsfiddle.net/sturchyn/z8wt3zdd/
- Open demo.
- Click on the first select tag
- Type 'a'
Expected: See the letter 'a' in the select box
Actual: Nothing is seen in the select box.
Why is it good? When reading the report, I only have to click the link and follow the steps one by one. At the end, if I'm seeing 'Actual' behavior like the reporter, the report is probably good. Total time, a few seconds. I don't have to make a new pen, copy-paste code, do anything but check the reproduction case. People can also right away break out the debugger and start debugging code to find the cause! This makes the job easy and allows us to process more issues and get them fixed faster.
If your issue can be demonstrated with executing some steps on the official Selectize page, great! No need to make a demonstration, just copy-paste the URL to that and mention which example. Done.
If not, don't fret. Create a Jsfiddle/Codepen, add the right dependencies [steps here should be expanded], and create a minimal example. In your real application, you probably have lines of code and context. Try to make the simplest Selectize possible with the least options and see if you can reproduce the issue. Once that's done, try to remove options that are not useful to showing the issue.
You have your demonstration. Using 1-2-3 step numbers, start writing down the simplest way you can demonstrate the issue. Reminder, at step one, we usually assume the page has been loaded. You can also say something like "load page" on step 1. Do not include your Selectize options or any code, because those belong in your demo.
Common actions will include "click" somewhere, "type" something, "select" an option, and so on. No need to go crazy specific, just use plain language and actions. As long as it's easy to understand when doing it again/reproduction, you're fine.
The last step is usually the one that leads you to your expectation/triggering the issue.
Also called "expected/actual". That's where you highlight that there's an issue. In it's own paragraph, write "Actual:", and what actually happened. Skip two lines (new paragraph), write "Expected:", and what should happen if Selectize worked perfectly. It might sound stupid and trivial, but it helps in making a clear case.
Putting this all together, let's make an example.
If I make a <select> into a Selectize and the dropdown doesn't open when I click on it, here's what I would submit:
Demo: http://selectize.github.io/selectize.js/, "Single Item Select"
STR:
- Click on select tag
Actual: Dropdown doesn't open
Expected: Dropdown opens
That's it. You've got something understandable that's easy to triage!