Description
Have you ever needed to understand a new project and started reading the tests only to find that you have no idea what the tests are doing? In this talk we will discuss how to write great test documentation to make this a thing of the past! Writing great test documentation as you are writing tests will improve your tests and help you and others reading the tests later. We will first look at why test documentation is important both when writing tests and for future readers, then look at a framework that helps give some structure to your test documentation. Next, we will look at a showcase of the flake8-test-docs tool that automates test documentation checks to ensure your documentation is great! Finally we briefly discuss how this framework would apply in more advanced cases, such as when you are using fixtures or parametrising tests.