Unit tests as API usage examples

Abstract

This study aims to find out if API unit tests can provide good usage examples, and if so, what prevents developers from finding and using those examples. The results of an experiment we performed with two groups of developers showed that unit tests can be very helpful, especially when the task is complicated and involves multiple classes and methods. Well-written tests proved to be a good source of examples, but finding the relevant examples using the standard tools might be very difficult. We propose to supplement the standard API documentation with relevant examples taken from the unit tests. To further improve the learnability of the API, presentation of the documentation and examples has to be tailored in a way that separates or hides advanced usage scenarios from the commonly used ones.