How to write test documents: why you need them, and how to get started

A lot of software providers forget about the importance of documenting their processes. A test document is one of those important tracking tools overlooked by many. It’s especially true when the project has no dedicated QA specialist. Yet, the benefit of a test document in place is immense for a project.

This article is useful for both customers and providers of software development services. Still, QA specialists are the target audience. So, be ready to dive deep into the details and technicalities of writing a test document. Besides, this blog post will have a part two, so stay tuned.

The first part of the ultimate guide has six chapters:

1. Checklists
2. The Reasons for Creating Test Cases
3. How to Create a Test Case
4. The Lifecycle of a Test Cases
5. Test Suits
6. Typical Errors When Creating a Test Document

1. Checklists

Starting a more or less complex task requires a checklist. You need one when you shop, plan a BBQ, and when you test your software.

seopressor.com

In a nutshell, a checklist is a set of ideas for testing, developing, planning and managing a project. You can pitch ANY idea as long as it’s sane and falsifiable.

Your checklist should additionally conform to 3 principles to work:

• Logic
• Coherence and structure
• Fullness and non-redundancy

As simple as that! The checklist is the most basic and most overlooked element of a test document. Yet, it lays the foundation for the success of your software development project.

2. The Reasons for Creating Test Cases

When you’re ready with your checklist you can assign a test case to every bullet point on your checklist. If you missed something, don’t worry. You can add and delete your test cases when you need to. Still, try not to mess the coherence and structure of your checklist. Anyways, let’s define what test case is.

A test case is a case for bug checking a software solution. Test cases always include testing steps and expected results.

The benefits of making test cases for your own project are undeniable. In short, you have 7 reasons to create a test document for your project:

1. You structure and systematize your testing approach. It’s very important for medium and large projects.
2. You increase your test coverage metrics by measuring them and taking action.
3. You follow your plan by tracking your current situation and compare it with the plan.
4. You foster communication between developers, clients, and QA specialists. In case something goes off the rails, you’ll be able to prove you’ve done everything by the book.
5. You store data for legacy use and knowledge transfer between coworkers and teams. This way, you’ll be able to bring a new coworker up to speed with your project asap.
6. You’re able to perform regression and repeated testing. It’s very useful to be able to compare your current test case with a legacy one of the same feature.
7. You increase the quality of your test requirements. Especially when your test case may show you that your expected results were off the target.

3. How to Create a Test Case

Now, you see creating a test document is definitely not a waste of time. You furthermore don’t spend that much time at all since test cases are quite simple. Below, you can see an excel file showing the structure of your typical test case.

The structure of a test case goes as follows:

1. Identifier. The field holds a unique value allowing to distinguish one test case from another.
2. Priority. The field shows the importance of a test case. To highlight the importance, you can use A-Z, 1–9, words like “high”, medium, and low or any other useful grading.
3. Requirements. It allows you to locate the main requirement you’re testing. In the example above, “R97” refers to the requirement description #97.
4. Module and submodule. The field describes elements of the software solution you should test.
5. Contents. It provides you with a gist of the test case. A tester should be laconic and to the point here. In the contents, you can find the initial data required to execute the test case. Moreover, the field contains the actions necessary to perform the test case.
6. Expected Results. The QA specialist describes the consequence of every action described in the contents.

At the end of the day, you can create a test document like the one below.

You can change the document as you and your team want. The test document should serve the software testing efforts and not be the burden. Moreover, each test case is not set in stone. You have a dynamic test document on your hand with test cases failing and succeeding.

4. The Lifecycle of a Test Case

The short but interesting life of a test case goes through different testing phases.

First, you assign ‘Created’ to all the new test cases. Then, you can move your test case to either ‘Planned’ phase or ‘Not Tested’. ‘Planned’ describes a test case included in the upcoming testing iteration. ‘Not tested’ is almost the same phase but you don’t include the test case into the testing iteration.

Afterward, your test case goes in one of two states either ‘Work in progress’ or ‘Skipped’. ‘Work in progress’ describes complicated test cases taking a lot of time. But, testers usually skip this phase because the typical test case doesn’t take much time to perform. As for ‘Skipped’, testers use it to skip a test case due to either lack of time or a change in the testing logic.

Next, you have three separate test case phases: ‘Failed’, ‘Passed’ and ‘Blocked’. The first one, ‘Failed’, means you’ve stumbled upon a bug, and you have some work for your developers. The second one, ‘Passed’, means you have found no bugs during the test. The final one, ‘Blocked’, means you can’t perform your test due to another, separate bug.

Finally, there are two odd phases ‘Closed’ and ‘Not Ready’. You can use the ‘Closed’ phase in those rare situations when you closed the test case and the result is not important. Otherwise, I recommend you use one of the previous states like ‘Failed’, ‘Passed’ or ‘Blocked’. As for ‘Not Ready’, you can use it for test cases with errors, inadequate requirements, or other issues.

5. Test Suits

We’ve gone through everything important about test cases. Yet, testers usually don’t work with isolated test cases but rather with a test document as a whole. So, you always have some kind of a test suite determining the order of your testing.

First, you have the option of preparing for each test separately or for the whole test suite combined. Second, you can execute tests cases either gradually or freely. You can, of course, have a mix of these different test suites. Whatever makes your project succeed. Still, you’ll end up with 4 distinct types of test suits. Choose wisely!

6. Typical Errors When Creating a Test Document

Software testers distinguish between two types of errors when creating a test document.

The first type of errors are formatting and descriptive ones. These mistakes are inaccuracies leading to misinterpretations and the consequent test fails.

The second type of errors includes logical mistakes. The source of this type of testing mistakes is a fundamental misunderstanding of a test case. So, if you don’t understand a test case, I recommend that you address your co-workers for clarifications. And don’t take “no” for an answer!

Possible formatting and descriptive mistakes:

1. A test case has a deficient title or no title at all. A tester should make the title as concise as possible because coworkers often don’t read the full description.
2. Test case steps have no enumeration and no list of expected results. This error can lead to a test case performed all wrong and even submitted as well performed.
3. Writing the same test case information twice or more. The same information in different places is a misleading practice.
4. Using imperative verbs. Use “should”, “must”, “ought to”, and “will” instead, as people are often irritated by imperative verbs.
5. Writing in either a past or a future tense. The use of incorrect tenses may distract people from a test case they are performing right now.
6. Using words like “check” and “test”. These words don’t specify what exactly should a tester do. So, the tester can perform an action different from the one needed.
7. Describing standard interface elements in your own words instead of using conventional terminology. This practice makes a tester look unprofessional and makes the test document complicated.
8. Grammar mistakes. I hope I don’t have to explain this one. 🙂

Possible logical mistakes:

1. Linking for information to other test cases. This is a misleading practice. A tester should copy paste the required info into the current test case.
2. Describing features irrelevant to your testing. In other words, you should be laconic, and write to the point.
3. Defining expected results and action descriptions badly and ambiguously. Again, this can lead to misinterpretations and test fails.
4. Inventing an app feature necessary for the project. Sometimes, testers think a certain feature is a must for an application without even bothering to look into the technical documentation.
5. Misunderstanding the app functionality and thus the test case. This error is severe and can lead to inadequate results for the whole testing project.
6. Considering an incorrect app behavior to be the expected result. In other words, if you get 404 page, you don’t describe it as a result. You describe it as a fail.
7. Distributing data suits into equivalence classes incorrectly.

So, that sums it up! Thanks for making it to the end, and I hope you find the first part of the article useful.

My company DevCom has solid experience with software support and stress testing. In case you need the following services, Contact Us.

How to Do a Proper Website Stress Testing Using JMeter | DevCom

Written by Romanyuk Oleg, Marketing Manager @ DevCom.

Originally published at devcom.com on August 7, 2018.