Developing on Staxmanade

Spend the Effort to Make Your Tests Better Documentation


You may be writing tests, but are they describing the behavior well enough to know what business case it's covering a year from now?

Today's lesson or re-lesson. Don't just write your tests, write it so you can understand the intricacies a year from now.

The other day I was pairing on a what we first thought was a bug in our software. I was explaining something we saw.. "oh yea, that's a bug, oh and look at these tests, they look wrong also. Why is this so wrong? How did we not catch this last year? Something is off here... etc..."

While I had some tests to cover a business requirement a year ago when we wrote the software, I had not properly described the business case within the test to document it's purpose.

The subtle, bug-look-a-likes turned out to be proper behavior. If only I had not just documented the expected behavior via a test, but had properly describe WHY this behavior existed within the test, we could have avoided potentially breaking it (by "trying to fix it") and the test could have better communicated the WHY of this strange case.

This is just a reminder to myself to write better tests. Doing tests, great. Well documented, business explanation of the WHY in the tests? Way better!

Happy testing!