How to write test cases developers will love reading

This blog is a followup to How to write a bug report developers will love reading. It stems from mixed experience reading bug reports, unit test messages, and feature requests on various OSS on Github and developers' blog posts.

Following in the footsteps of other blogs in these series, we will focus on asking basic questions, as opposed to prescribing some magic solution, in a way that triggers a rethink on state of test cases and/or user story(JTBD).

If you haven't already, read the “How to write User Stories developers will love”

The idea is to challenge our thinking into discovering improvements on the messaging, to make test cases actually validates, and ideally, prevent bugs from happening in the first place.

In this article we will talk about:

Even though this blog post was designed to offer complementary materials to those who bought my Testing nodejs Applications book, the content can help any software developer to tuneup working environment. You use this link to buy the book. Testing nodejs Applications Book Cover

What to expect from test cases

It has been said that the best way to document any code block, is via its test cases. However, it is also true that some test cases do not provide a clear messaging around what the code blocks the are about to test do, or supposed to do. That is where the reflections in this blog are supposed to address. Moreover, there is little to no convention around writing such messages, which sometimes makes reading test reports quite futile if not un-readable.

This article tends to suggest the kind of message format to follow when we need our test message to make sense for us in the future, and for first-time readers. The message is based on observations found in popular open-source frameworks. To limit the scope, our observations are going to be based on the following frameworks: mochajs, sinonjs, expressjs and nodejs.

When writing the test case blueprint, we will have to answer thoroughly following questions in plain English. Our final product has is a mold test case that has to fit in, or blueprints our bug reports have to built around.

To start this exercise, let's take our typical test case, and verify if it satisfies the questions below.

Answers to this kind of question provide a starting point to create a blueprint of test cases other developers will love.


In this article, we revisited how to write test cases that convey a clear message on what is wrong with the system, in a way that developers may correct the course with effective tests. As always, there are additional complementary materials in the “Testing nodejs applications” book, about how to write test in a nodejs environment.


tags: #bugs #bug-report #QA