Skip to content

Good bait catches fine fish – part 3: How to write a specification for testers

We saw in the past blogs, how a specification for customers and specifications for developers look like. But we write specifications even for testers. But what is needed for testers in a specification?

Testers are supposed to use tests to get evidence that the software behaves as expected. But it is new software. They cannot fall back to experience — they only can fall back to the descriptions in the specification. Therefore it has to be clear what the behavior should be and what is really expected.

Often that is not exactly clear and someone reads out of the specification what is not really meant. That causes a lot of discussions and bug fixes which are not even necessary. To make the borders clear and to give the testers a distinct support, requirements need clear acceptance criteria. Those criteria contain everything that is needed to determine whether a requirements can be accepted — or not.

Acceptance criteria can contain models as well – e.g. state diagrams as transfer model for business object states or even the already used mockups out of the customer specification. It is helpful to think about acceptance criteria in a form of a check list. If one point in the list is not fulfilled, the software cannot be accepted. 

User Stories for Everyone

To reduce the risk that the software isn’t accepted at the end, the software can be divided into small stories — so called user stories. The sum of those user stories is then the entire software. A user story describes a small advantage of the software which can be recognized by the user. Each of those user stories contains their own acceptance criteria. So we reach on the one hand that we can build the software step by step and on the other hand, that one user story, which cannot be accepted, doesn’t cause a non-acceptance of the entire software by the customer.

User stories are an important tool in specifications and they are understandable by all three target groups. They are written out of the user’s perspective in every case and they contain the role of the user, the function to perform, and the goal which has to be reached by performing the function:

As a bookkeeper, I  want to add an item to an invoice, so that all items are included in the invoice – even items that were ordered at a later date. The according acceptance criteria could look like this:

  • A user in the role of a bookkeeper can add an item in an invoice.
  • The position can be selected out of a catalog or can be added as a free text item.
  • After confirmation by the user, the invoice is recalculated and the new print layout is displayed to the user. …

To that belong the according mockups and the state transitions of the invoice – Draft – New Item – Recalculated – Confirmed.

Because the user stories are written in the point of view of the user, they are well understandable by the customer. Moreover, they are describing the motivation behind a function. So the customer can recognize the importance or irrelevance of single functions and in such a way prioritize them. To map the business processes it is recommended to build up the user stories along the business process steps.

Because user stores are related to the business objects, which were described in the domain model, they are understandable by developers as well. User stories contain acceptance criteria, therefore they are quite useful for testers, to give clear statements about whether the software works or not.


We write specifications for customers, developers, and testers. Each of those target groups need specific information, which are listed below:

  • Business process description as graphical and natural language description
  • Domain model as graphical and natural language description
  • User stories as user centred description of the expected functions
  • Acceptance criteria as criteria for the acceptance with following (optional) parts
    • Mockups with description of the user interface
    • State diagrams to explain state transitions of business objects
    • Activity diagrams to show complex flows easier

With this content, we are easily understood – but that does not mean that we can spare the discussions with the customer, the developers, and the testers 🙂 – but they will be more fun.

read more from