Writing test cases someone else can run

Think about a recipe written by somebody who already knows how to make the dish.

"Add the usual amount of stock. Cook until done." A stranger cannot follow that. The author was not writing instructions, they were writing a reminder to themselves.

Most test cases are reminders. That is the whole problem, and it is why learning how to write test cases properly matters more than any tool you keep them in. The test is whether a colleague who joined last week can run yours without asking you a single question.

The five parts of a runnable test case

• Title. What is being checked, in one line, specific enough to read in a list of two hundred. "Redeem a gift card for the full order value" beats "Gift card test 3".
• Preconditions. The state the system must be in before step one. A logged-in customer, a card with a balance, an empty basket.
• Data. The exact values. Card codes, amounts, email addresses, product IDs.
• Steps. Numbered actions, one action each, in the order a person performs them.
• Expected result. What must be true at the end. One statement, checkable, no room for interpretation.

Five things that break a test case

In practice, almost every unusable case has one of these five problems.

1. Vague steps. "Set up a customer" hides ten minutes of work and three decisions. Say which customer and how.
2. No data. The case works for the person who wrote it because they know which account to use. Nobody else does.
3. Two things at once. A case that checks the discount and the email now fails for two unrelated reasons, and the title tells you neither.
4. Dependence on yesterday. The case only passes if the previous case ran first, in order, on the same day. That works until somebody runs case 14 on its own.
5. A hidden expected result. The steps are perfect and the last line says "confirm the behaviour is correct". Correct according to what?

How to write test cases someone else can run

1. Start from the acceptance criteria, not the screen. The criteria say what the story promised. The screen shows what got built. You want to test the promise, which is where turning a story into cases starts.
2. Write the title and the expected result first. If you cannot state the expected result in one line, you do not yet know what you are testing. No amount of steps will rescue that.
3. Fill in the data before the steps. Real values, written down. This is the single fastest improvement most suites can make.
4. Keep steps to one action each. "Enter the code and click apply" is two steps, and when it fails you want to know which half.
5. Make it independent. Each case sets up what it needs and leaves the system usable for the next one.
6. Hand it to somebody and watch. Do not explain anything. Every question they ask is a defect in the case, and thirty minutes of this teaches more than any template.
7. Keep the cases where the results live. A case in a document with its results in a spreadsheet is two records. They will disagree by Friday. That is the argument for a single test record a release can rest on.

A filled-in test case example

Here is one from the gift-card release at Willow Books, a small online bookshop. Nothing elided, and short enough to copy.

Read the expected result again. Three checkable statements, with numbers. A tester who has never seen this feature can run it, and if the remaining balance shows 10.98 they know immediately that they have found something.

Where the cases should live

Cases, runs and results belong in one place, joined to the tickets they came from. That is what a test management tool is for, and the choice matters less than the discipline. A spreadsheet works until two people edit it, and then it quietly stops being true.

Two things worth deciding early. Automated checks live in the repository beside the code, because they are code. Manual cases and run history live in the tool, because they are a record. When those two get mixed up, teams end up maintaining the same case twice, which is covered in what "open" has to mean for test case management.

How to show you know it

• A case a stranger ran clean. Hand one over, say nothing, and count the questions. Getting to zero is a real skill and a good interview story.
• A rewritten case, before and after. The vague version and the runnable version side by side. It shows you know what the difference costs.
• Named data. Real values in every case. Reviewers notice this immediately.
• An independence fix. "These four cases only passed in order, so I gave each its own setup." Small change, and it is why the suite still runs next year. It also stops a case being blamed for flakiness it did not cause.