How to write a test case description

One of the most important skills a software quality assurance engineer can possess is the ability to write clear and concise test case descriptions. Regardless of whether the test case is to be executed programmatically or manually, a well written description will benefit all who read the description. Adhering to a consistent format and a common set of phrases across a set of test cases will enhance the comprehension of the reader and encourage anyone contributing to the suite of test cases to follow the established nomenclature.

This article provides some common sense recommendations for describing functional test cases. These recommendations are based on my over 15 years of experience reading, writing and maintaining software test cases.

Test cases typically consist of a title and a body. The test tracking tools that I’ve used (TestRail, Quality Center, home-grown tools) are designed to show a set of test case titles, usually grouped within a folder. To see the body of a test case takes either creating a report or drilling into the individual test cases.

Writing the Test Case Title
Other people will most likely read your test case titles at some point. Whether your tests are being reviewed for approval or someone else is going to take over running your tests you’ll want to compose a test case title that gives the reader a quick, clear sense of what the test does. I use this very simple format

Confirm | Verify 

• Confirm welcome screen appears when user logs in
• Confirm user credentials are saved when he has selected the save option
• Confirm when a user changes his password via the mobile app he has to use that new password to log into the web site
• Verify new content feed pop up appears when follower answers question
• Verify forgot password screen appears when user clicks on ‘Forgot password’ button
• Verify forgot password email is sent to user once he completes the forgot password form

 
I’ve found that consistently putting the action first and the expected reaction second makes understanding and assessing a group of test cases much easier than if they are inconsistent.

If I’m testing a more involved workflow, rather than just a bit of functionality I will use a slightly different format.
 
Confirm | Verify behavior | workflow

• Confirm ‘reset password’ behavior
• Verify new user sign up workflow

 
I realize not all test cases can be expressed in these simple formats. For more complex test cases it still is a good idea to express the intent of the test case in terms of actions to be taken and expected reactions. If you are having trouble expressing the test case in this manner it may be a hint that your test case needs refinement.
 
Writing the Test Case Description
Some test cases are simple enough all they need is a test case title, but most of the time more detail is needed. The description should include

• Unique prerequisites and assumptions for this test: Prerequisites and assumptions are important artifacts of a test case. Calling these out can save the tester much heartache and false negatives that they would otherwise be likely to experience. Some of these prereqs and assumptions will be unique to a specific test, but some may be common to a set of test cases. When prerequisites or assumptions are unique to a test, I call them out in the tracking tools prerequisite/setup area. If a group of tests rely on a common set of requisites, such as they all need three test accounts to exist, I prefer to not associate this prerequisite with each test. Instead, I note this prerequisite in separate file in the containing folder of those tests. In each test’s prerequisite area I simply refer the reader to that file.
   
• Steps of test case: Like the test case title, the steps of a test case should clearly call out the action to be taken by the tester. Write the step as if you were giving an order to a subordinate. That might sound harsh, but the best thing you can do is when writing a functional test case description is give clear, precise directions.
   
• Expected results of the step: A test case or a step in a test case that does not have an expected result associated with it is subject to the reader’s interpretation, which means the overall result of the test case is subject to interpretation. Call out the expected result in a way that tells the reader exactly what to look for.
   

The test tracking tools that I’ve used have all had separate areas for the steps and the expected results. I’ve always found this disjointed and difficult to manage. I’ve read existing test cases where there are cases such as having five steps but only three expected results. It gets confusing trying to match steps with expected results. Even when the number of steps and expected results match, the way the tool separates the two areas makes it difficult to match and track progress. For this reason, I don’t use the expected results area. Instead, I combine the steps and expected results in the description/steps area of the tracking tool. I put the action (the step) first, followed by the reaction (expected result).

As mentioned earlier, the recommendations here are useful for functional test cases. Other testing, such as exploratory testing or scalability testing may not lend themselves to these suggestions. If you are getting ready to write a group of test cases I believe it is worth your time to create some type of guideline for expressing your test cases. This will help you and other folks that will read your work.