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:
- Choosing the right wording when writing test cases, requires getting into how developers think and approach problem-solving.
- The best test case depending on the best user stories. For that, the reports are based on GivenWhenThen, in case user stories are.
- Choosing the right template for test cases, for new and regression cases
- Writing a testing message that aligns with features
- Writing informative testing message(on reports and logs)
- Case > Feature > Expectations
Even though this blog post was designed to offer complementary materials to those who bought my Testing
nodejsApplications book, the content can help any software developer to tuneup working environment. You use this link to buy the book.
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.
- How much does a bug costs
- How do you define a test case
- What should go into a test case
- What should NOT go into a test case
- How can my testing messaging aligns with feature requests under test
- How can I evaluate if my testing message is informative enough for those needing to read test reports or assertion logs
- How to link test cases to acceptance criteria- How to model test cases around: (Use Case > Feature > Expectations)
- How to model test cases: (Given > When > Then)
- How to model test cases after JTDB (Jobs to be done)
- How to model test cases after user stories
- Is it OK to refactor test cases
- How do go about refactoring test cases
- Why messaging matters when crafting test cases
- What are the pros and cons of TDD vis à vis BDD test case
- Is it possible to use both TDD and BDD approaches in the same project
Answers to this kind of question provide a starting point to create a blueprint of test cases other developers will love.
Conclusion
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.