How to create a minimal complete reproducible example

General
, ,
1

About

Creating a minimal complete reproducible example (MCRE) of a code issue.

(Also known as a minimal reproducible example (MRE), minimal working example (MWE), minimal verifiable example (MVE) and minimal complete verifiable example (MCVE))

Who is this for?

Anyone who is asking for help with a coding issue.

Why bother creating an MCRE?

  1. It makes it easier for anyone who is trying to assist. It is in your best interests to do this as it makes it more likely people will help you.

  2. It clarifies the problem for yourself. It can make it clearer where the problem lies which can sometimes lead you to a solution without needing to request help.

  3. It is polite. You’re asking for others to take time out from their work to assist with yours. The least you can do is make that as easy as possible for them.

Resources

There are some excellent resources to assist with creating an MCRE:

  • Stackoverflow has guidelines for creating a minimal complete reproducible example
  • Matthew Rocklin (principal author of dask the engine behind parallelisation in xarray) has written an excellent guide to writing effective minimal bug reports with example python code:
  • The scikit-learn documentation includes information on python utilities for creating synthetic test data sets as well as scikit-learn specific utilities:

Summary

Please do read the above resources, but the TL;DR summary for creating an MCRE:

  1. Ensure it includes the failing test case
  2. Demonstrate the steps necessary to reproduce the bug
  3. Be as simple as possible, including using smallest possible generic data sample
  4. Clearly describe the expected result of the test case, and what should happen when the code is executed
  5. Verify the bug by running the test case and observing the actual results
  6. Describe what actually happened when the code was executed, and how it deviates from the expected result
  7. Provide any necessary context, such as the environment in which the code is running, or any other relevant information that may help to understand the bug, including full error messages/stack traces
2 Likes