Menu
I'm trying to improve the number and quality of tests in my Python projects. One of the the difficulties I've encountered as the number of tests increase is knowing what each test does and how it's supposed to help spot problems. I know that part of keeping track of tests is better unit test names (which has been addressed elsewhere), but I'm also interested in understanding how documentation and unit testing go together.
How can unit tests be documented to improve their utility when those tests fail in the future? Specifically, what makes a good unit test docstring?
I'd appreciate both descriptive answers and examples of unit tests with excellent documentation. Though I'm working exclusively with Python, I'm open to practices from other languages.
840
Unit tests should aim to be self descriptive, but there will always be cases where this goal cannot be achieved and thus description of what has been written is due. In other words, try to make your unit tests so they don't need documentation, but if they need it, write it!
The purpose of a unit test in software engineering is to verify the behavior of a relatively small piece of software, independently from other parts. Unit tests are narrow in scope, and allow us to cover all cases, ensuring that every single part works correctly.
Every single unit test should be self-contained and not depend on others. Don't repeat yourself.
I document most on my unit tests with the method name exclusively:
testInitializeSetsUpChessBoardCorrectly() testSuccessfulPromotionAddsCorrectPiece() For almost 100% of my test cases, this clearly explains what the unit test is validating and that's all I use. However, in a few of the more complicated test cases, I'll add a few comments throughout the method to explain what several lines are doing.
I've seen a tool before (I believe it was for Ruby) that would generate documentation files by parsing the names of all the test cases in a project, but I don't recall the name. If you had test cases for a chess Queen class:
testCanMoveStraightUpWhenNotBlocked() testCanMoveStraightLeftWhenNotBlocked() the tool would generate an HTML doc with contents something like this:
Queen requirements: - can move straight up when not blocked. - can move straight left when not blocked. If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
