General Guidelines
Use clear language: simple and clear phases with proper punctuation and capitalization. Make sure to check for grammatical errors (use a spell-checker/Grammarly).
If your actions/expected results start getting long, consider breaking them into separate steps.
Use basic formatting such as bold and bulleted lists. It presents some distinction during execution. Although the test execution module doesn’t currently display this formatting, once support is added, tests will become easier to read.
Don’t use abbreviations that testers aren’t familiar with.
Don’t use the word “observe” as a separate action – it’s self-explanatory.
Avoid over-specification: The more detailed your descriptions are, the more complicated later maintenance of the test is. Specify only what’s crucial and make sure you are focusing on the app under test, instead of the system/environment functions that aren’t particularly related.
General Examples
Do | Don’t |
Ensure your language is clear and concise.
| Avoid language errors, abbreviations that aren’t self-explanatory (“sdc”), trivial explanations (it’s self-explanatory that a ‘search’ button is a button), using unusual terms (menu of variations vs. search suggestions), unnecessary use of “observe”.
|
Avoid self-explanatory actions that testers should know how to do.
Action: Go offline. |
|
Goal
Start the test case with a clear and concise goal, stating the purpose of the test case. Use an info step starting with “The goal of this test is to verify ...” This provides perspective to the tester and/or test case reviewer regarding the specific testing mission.
After completing the test case, make sure to check the test context against the goal. This helps you see whether you covered the initially intended scope.
Goal Examples
Do | Don’t |
Include enough context to be clear. The goal of this test is to cover positive flows for login with just-created and already-existing accounts. | Too generic: The goal of this test is to test login. |
Don’t include too many details to overwhelm. The goal of this test is to cover a typical purchase scenario starting with product selection and ending with a successful purchase. | Too detailed: This test covers purchasing functionality, specifically: searching for a product, choosing a quantity of this product, adding additional products to the cart, going to the shopping cart and filling out details, proceeding to the purchase step, and also verifying that the confirmation e-mail arrives. |
Prerequisites
State any prerequisites required for the test case as a separate info step after the goal.
Avoid writing unnecessary prerequisites, assuming that the tester is already onboarded to the particular workspace and has the necessary context.
Keep in mind the context to determine if a prerequisite is necessary. For example, a prerequisite to be logged in might not be needed for apps that don't offer any functions to logged-out users, others apps might have logged-out states as an area of a testing focus.
Don’t embed another test as a prerequisite.
The focus of prerequisites is to ensure a certain state before starting the test case. Asking testers to execute another step as a prerequisite may disrupt the purpose of the test case itself.
Testers don't see embedded tests as separate and so they don’t understand that a particular piece is a prerequisite.
Instead, state what needs to be achieved. If the journey is complex, include a pathway for how to do it.
Automation and Prerequisites
An underlying principle: If a freelance tester is able to read the test and understand the prerequisites, it should also apply to a QE who is scripting the test case. Don't add prerequisites just for automation context.
This applies even with complex scenarios where a particular test case can only be executed once a certain state of the system is reached. The prerequisite description should be enough to understand how to reach the particular state. The QE then chooses an appropriate method to the prerequisites (such as interacting directly with APIs to generate data in advance).
Prerequisite Examples
Do | Don’t |
Leave out unnecessary prerequisites. | Avoid self-explanatory situations, such as this for a new account registration test: User is not logged in |
Skip over details of getting to the prerequisite:
Prerequisite:
Note: If it’s not self-explanatory how to get to the prerequisite state (for example, if you need some unusual steps to get a product in the cart), then write out the step sequence without verification actions. The goal is only get to the required state. | Avoid embedded tests with detailed steps:
|
Test Flow
Begin the flow of test steps after any prerequisites.
Ensure that testers can follow the test flow without having to go back to previous steps. Returning to previous steps and re-executing them disrupts the tester’s workflow and hinders the ability to later determine which steps actually passed and failed based on which conditions.
If certain steps need to be done more than once, create an embedded test to handle those steps.
Test Flow Examples
Do | Don’t |
For short sequences, repeat the steps in the test case.
| Don’t ask tester to redo specific steps:
|
Unless a certain scenario is targeted on its own, make sure that steps progress logically so that testers don’t need to spend extra time repeating actions.
OR (combining with an extra verification):
| Don’t place steps in a random order that forces testers to take extra actions to complete tasks.
|
Info Steps
Use Info Steps to state the purpose of the test case, describe prerequisites, or provide additional context for the test case or upcoming steps.
For longer or complex descriptions, consider attaching videos or screenshots to effectively deliver the message.
Structure and outline the information in a clear and organized manner.
When considering giving the full details of a story/epic to a tester, consider the following:
Is the information relevant to testers (or is it, for example, internal client notes)? If it’s not relevant, remove it.
Will this information be used by multiple testers (such as when test cases where this is included are executed multiple times)? If yes, consider summarizing the content to reduce the total time spent by testers. For one-time tests, it might be more expensive (in client services time) to summarize than to provide the input directly to testers.
Never use Info Steps for verification. While Info Steps can draw attention to certain areas of the product, if you want testers to validate a function, you need to add a clear pass/fail step for that to the test.
Info Step Examples
Do | Don’t |
Include only what testers need for testing.
The main changes for the Shopping Cart feature are:
Cart View Enhancement:
Save for Later:
See attached screenshots. | Don’t include epic information with internal notes that aren’t relevant. The content in the Do column is also shorter, but you can shorten the text with AI once it becomes available to keep it cost effective.
Here’s an outtake of the user story for your context:
This epic entails a comprehensive set of improvements to our existing Shopping Cart functionality, aiming to streamline the purchasing process, increase customer satisfaction, and lay the foundation for future enhancements.
User Stories:
|
Present context with clear structure for easy understanding.
Here are user stories reflecting the main changes in the functionality under test:
| Avoid putting all the text into one unstructured blurb in an info step.
User Stories:
As a customer, I want to easily view and manage items in my cart. Break down the existing cart view into a clean and intuitive layout. Implement a quantity adjustment feature within the cart. Allow customers to remove items from the cart with a single click.
As a customer, I want the option to save my cart for later. Develop a “Save for Later” functionality that moves items from the cart to a separate list. Enable customers to easily move items back to the cart from the Save for Later list. |
Pass/Fail Steps
Each test step should consist of one logical action and one logical verification.
Use clear assertive language in the action step, such as “Do X” or “Do Y”.
The logical verification is the expected result, which should be the outcome of the performed action.
Please note that stating that the user has to "verify that Function X works” is not helpful for either testers or QEs automating the test. You need specify what "works" means and state the specific expected result.
If the expected result requires additional actions for verification, include them as separate steps.
If there are multiple items to pay attention to in the expected result but you still want to group them in a single verification to more easily maintain the test case, then clearly separate the items using a bulleted list for traceability.
Use this approach with caution – when one expected result has multiple verifications, testers often miss the extra verifications. A good example where such an option could be used: the user needs to verify that a menu contains specific items – all of these items are listed.
Avoid writing unnecessary expected results and consider combining actions if the expected result is trivial.
It's acceptable to treat a step as a pathway to the final outcome of a complex flow.
Step Detail for Automation
For automation, there is no need to over-specify the flow or details of a step as long as the action and expected results are clear. Do not create maintenance overhead.
For example, if the test case is about setting a date in a calendar, then it is enough to ask the user to select a date from the calendar instead of guiding them to click the top right corner, select the calendar menu item, verify that the calendar opens, and so on. That context should be self-explanatory for testers and any QEs who understand the product and the test goal.
Pass/Fail Step Examples
Do | Don’t |
Include additional actions as separate steps or, when appropriate, as a separate test.
A separate test for removing items from a past shopping session. | Don’t include further actions in the expected result.
|
Clearly define what is an action and what is a prerequisite or expected result.
| Don’t confuse actions with prerequisites or include actions in expected results.
|
Cover multiple verifications with separate test steps or potentially split into separate test cases. For example, verify the presence of fields with clear actions about those fields:
| Don’t include too many verifications in one expected result.
|
Test Case Duration
Aim for targeted execution and reusability by keeping the execution time within specific limits:
Function-based test cases should not exceed 5 minutes.
Scenario-based test cases should not exceed 10 minutes.
As a general rule, limit the number of steps in a single test case to no more than 15.
In certain scenarios, it might not be possible to achieve these targets because of the specifics of the function under test (such as complicated actions or waiting time). Still, it’s easier to estimate a shorter test than a longer one.
Test Case Data
Instead of hardcoding test data, provide context to the tester on what is considered relevant or irrelevant data and how to obtain it.
If a customer requires exact reporting on the data used, consider adding a short-answer or paragraph step after a pass/fail step asking the tester to list the data used.
Test Case Data Examples
Do | Don’t |
Describe what's necessary from the perspective of the function.
Action: Verify that the start date field accepts only upcoming dates, inclusive of the ongoing day. | Avoid specifying information that isn't relevant to the function itself.
|
Prerequisite: There are at least two products that are in-stock and at least two products that are out of stock.
|
|
What's Next
Other guidelines on writing test cases