In summary, instead of using the categorization “nonfunctional requirements” to avoid a dificult conversation, teams should ensure they have a shared understanding of what their business users expect out of a system, including cross-cutting concerns. Even if the resulting examples aren’t easy to automate later on, having an up front discussion and using examples to make expectations explicit and precise will ensure that the delivery team focuses on building the right product.

Remember

•Using a single set of examples consistently from speciication through development to testing ensures that everyone has the same understanding of what needs to be delivered.

•Examples used for illustrating features should be precise, complete, realistic, and easy to understand.

•Realistic examples help spot inconsistencies and functional gaps faster than implementation.

•Once you have an initial set of examples, experiment with data and look for alternative ways to test a feature to complete the speciication.

•When examples are complex and there are too many examples or too many factors present, look for missing concepts and try to explain the examples at a higher level of abstraction. Use a set of focused examples to illustrate the new concepts separately.

On the other hand, just recording the key examples we want to keep without any explanation won’t allow us to communicate the speciication effectively to anyone who hasn’t participated in the discussions.

Successful teams don’t use raw examples; they refine the specification from them. They extract the essence from the key examples and turn it into a clear and unambiguous deinition of what makes the implementation complete, without any extraneous detail. This acceptance criterion is then recorded and described so that anyone can pick up the resulting speciication and understand it at any time. This speciication with examples captures the conditions of satisfaction, the expected output of a feature, and its acceptance test.

Specifications with examples are acceptance tests

A good specification, with examples, is effectively an acceptance test for the described functionality.

Ideally, a speciication with examples should unambiguously deine the required functionality from a business perspective but not how the system is supposed to implement it. This gives the development team the freedom to ind the best possible solution that meets the requirements. To be effective in these goals, a speciication should be

•Precise and testable

•A true speciication, not a script

•About business functionality, not about software design

Once the functionality is implemented, the speciication that describes it will serve a different purpose. It will document what the system does and alert us about functional regression. To be useful as long-term functional documentation, the speciication has to be written so that others can pick it up months or even years after it was created and easily understand what it does, why it’s there, and what it describes. To be effective in these goals, a speciication should be

•Self explanatory

•Focused

•In domain language

This chapter focuses on how to reine speciications to achieve all these goals. But irst, to put things into a more concrete perspective, I show examples of good and bad speciications. At the end of this chapter, we’ll reine the bad speciication by applying the advice given in this chapter.

116 Speciication by Example

An example of a good speciication

An example of a very good speciication with examples is shown here.

Free delivery

•Free delivery is offered to VIP customers once they purchase a certain number of books. Free delivery is not offered to regular customers or VIP customers buying anything else than books.

•Given that the minimum number of books to get free delivery is ive, then we expect the following:

Examples

This speciication is self-explanatory. I often show this example to people at conferences and workshops, and I’ve never had to say a single word to explain it. The title and the introductory paragraph explain the structure of the examples so that readers don’t need to work back from the data to understand the speciied rule. Realistic examples are also there, to make the speciication testable and explain the behavior in edge cases, for example, what happens when someone buys exactly 10 books.

This is a speciication, not a script for how someone might test the examples. It doesn’t say anything about application worklow or session constraints. It doesn’t explain how the books are purchased, just what the available delivery mechanism is. It doesn’t try to talk about any implementation speciics. That’s all left to the developers to work out in the best way possible.

This speciication is focused on a particular rule for free delivery. It includes only the attributes relevant for that rule.

118 Speciication by Example

This document has a lot of seemingly incidental complexity—names and addresses aren’t really used anywhere in the document apart from the setup. Database identiiers appear in the tables, but they’re irrelevant for the business rules. The database identiiers are used in this example to match employees with the Paycheck Inspector, introducing technical software concepts into the speciication.

The Paycheck Inspector was obviously invented just for testing. When I read this for the irst time, I imagined Peter Sellers in a Clouseau outit inspecting checks as they go out. I’m sure that this isn’t a business concept.

Another interesting issue is the blank cells in the assertion part of this speciication, and the two Paycheck Inspector tables seem unrelated. This example is from FitNesse, and blank cells in that tool print test results for troubleshooting without checking anything. That effectively makes this speciication an automated test that a human has to look over—pretty much defeating the purpose of automation. Blank cells in FitNesse are typically a sign of instability in tests, and they’re a signal that something is missing. Either the automated test is hooking into the system in the wrong place, or an implicit rule is hidden there that makes the test results unrepeatable and unreliable.

The language used in the speciication is inconsistent, which makes it hard to make a connection between inputs and outputs. What is the 1001 value in the table at the bottom? The column header tells us that it’s a number, which is a technically correct but completely useless piece of information. The second box has a check number, but what kind of a number is that? What’s the relationship between these two things?

Presuming that the addresses are there because checks are printed as part of a statement with an address for automated envelope packaging, the test based on this speciication fails to verify at least one very important thing: that the right people got paid the right amount. If the irst person got both checks, this test would happily pass. If they both got each other’s salaries, this test would pass. If a date far in the future was printed on the checks, our employees might not be able to cash them, but the test would still pass.

Now we come to the real reason for the blank cells. Ordering of checks is not speciied. This is a functional gap that makes the system hard to test in a repeatable way. The author of this FitNesse page decided to work around that technical dificulty in the speciication, not in the automation layer, and created a test that gives false positives.

Without more context information it’s hard to tell whether this test is verifying one thing only. If the check printing system is used for anything else, I’d prefer to pull out the fact that check numbers are unique and start from a conigured value in a separate page. If we only print salary checks, it’s probably part of salary check printing.

We’ll reine this horrible document later in this chapter. But irst, let’s irst go over what makes a good speciication.