EN 
DE How to keep the customer on board
Author: Markus Unterauer, Software Quality Lab
Contribution – Embedded Software Engineering Congress 2017
Specification by Example means specifying requirements through concrete examples. A fixed sentence structure is used, which allows for easy integration of test automation. In this way, a worthless write-only document becomes a valuable, living specification.
One of the most difficult tasks in software development is figuring out what the system should actually do and be able to do. Many stakeholders are involved in this requirements gathering process. Information about the customer's requirements travels through numerous stages. The customer tells the business analyst, who passes it on to the project manager. The project manager discusses it with the architect and perhaps external consultants, and then passes it on to the developer. The developer builds the system and passes it, along with the requirements to be tested, on to the tester. Finally, the system and its specifications end up with the maintenance and operations team. At each step in this communication chain, information is lost – like in the game "Telephone" (see Figure 1)., PDFThe requirements analysis is further complicated by the fact that there is usually not just one customer, but many – and therefore the system must support many scenarios, variants and variations.
Further confusion arises when the information is not communicated verbally, but as a written specification in the form of text and models. What is perfectly clear and understandable to one person is merely a meaningless string of symbols to another. Or worse: The recipient of the specification believes they have understood everything, but in reality, their understanding of the requirements differs significantly from that of the customer.
The result is often poorly designed systems that fail to meet customer needs. In many cases, these systems are nevertheless put into operation and only corrected during operation. This is also referred to as "banana software." Like a banana, the software only ripens at the customer's site.
We are therefore looking for methods that help us gather customer requirements and communicate them to all stakeholders in such a way that no information is lost. Specification by Example is one such method.
The basic idea behind Specification by Example is to collaboratively specify requirements in the form of concrete examples and document them according to a simple scheme. The clear and consistent scheme promotes comprehensibility, while the concrete examples increase unambiguity and make it easier to check the requirements for completeness.
Specification by Example is based on 5 basic principles:
1. Derive the scope of objectives:
Each requirement is traced back to a business objective and its associated business value.
2. collaboration:
Requirements and concrete examples are developed collaboratively. The development team, product owner, and customer are all involved.
3. Concrete examples:
Requirements are specified in the form of concrete examples and not abstract descriptions.
4. Living Documentation:
By using tools, requirements formulated in this way can be tested directly and automatically.
5. Recurring Validation:
Due to the high coverage of requirements through automated tests, retesting, e.g. after changes, is easily possible.
The first step is always to define business goals and the benefits the system is intended to deliver. Part of defining these goals involves considering for whom the goal is important. This "for whom" aspect is often described using personas—fictional example users and customers. The next step involves creating stories about how these personas will use the system. For each of these stories, a sentence is written using the user story sentence template as a reminder:
„"As I would like to , with it “
For each user story, conditions are now defined that must be met for the user story to be accepted and deliver value to the customer. These acceptance conditions, also called acceptance criteria, are again described according to a defined structure, the "Gherkin" schema:
„"Given , if , then “
The content doesn't describe abstract concepts, but rather provides concrete examples. The goal is to specify enough examples for each user story to cover all possible scenarios, variations, and aspects of the story. Often, each scenario is also given a catchy title.
Example:
Goal:
Building a smart home that makes life easier for a small family.
User Story:
As a working dad, I want to be woken up in time so that I can be at work on time.
Acceptance criteria in the form of examples (see Figure 2, PDF):
- „Scenario 'normal working day':
Assuming there are no traffic disruptions, if I activate 'Workday', then the wake-up time is 8:15."‚ - „Scenario ‚traffic jam‘:
Given that I normally need 30 minutes to get to work and I have the Daily Scrum Meeting at 9am and there is a 20-minute traffic jam, if I activate 'leisurely breakfast', then the set wake-up time is 6:10.‚ - „Scenario ‚Party on the eve‘:
Given that it takes me 30 minutes to get to work and I have the Daily Scrum Meeting at 9 a.m. and there are no traffic jams, if I activate 'sleep in', then the set wake-up time is 8:15 a.m.‚
The specific examples in the acceptance criteria are intended to describe the system's behavior in all its variations. This is why it's often referred to as "Behavior Driven Development." Several best practices have emerged when writing user stories and acceptance criteria using this approach:
- Keep the scenarios short.
- Break down a complex scenario into several simple ones.
- Describe scenarios from the user's perspective.
- Keep all scenarios at the same level of abstraction.
- Avoid using technical terms (e.g., UI, REST).
- Use terms from the subject area.
- Use concrete numbers, data, facts
(so instead of "enter value", enter the specific number, e.g. "5,212.65")
By using a standardized sentence structure, user stories and acceptance criteria can serve as a starting point for automated tests. Tools like Cucumber and Fitnesse allow you to manage user stories and acceptance criteria and supplement them with test code.
Feature: User authentication
User Story: In order to protect access to the HMI
As a system administrator
I want that all users need to be authorized
Scenario: Autologin after 60 seconds
Given HMI starts with default configuration
When user waits for 60 seconds at the login screen
Then Default user should be logged in automatically
[Given(„HMI started with default configuration“)]
public void GivenTheStartedHMIWithMachineConfiguration()
{
TestBase.loginForm = TestBase.app.Start();
}
[Then(„(.*) user should be logged in automatically“)]
public void ThenLoggedInUser(string user)
{
Assert.That(frameFunctions.UserGroup,Is.EqualTo(user));
}
Some tools also allow you to display the specific values for the scenarios in a table. The scenario itself then contains placeholders. This is shorter and clearer than writing the full sentence for each scenario according to the Gherkin model. However, by moving the values to a table, a degree of specificity in the formulation of the acceptance criteria is lost.
Scenario outline: Plausibility check in manual mode
Assuming the values ' ', , in manual operation
When the operator starts the pre-calculation
Then 'UpperDeadPoint' <= 'MutePoint1'‚
And 'ClampingPoint' <= 'LowerDeadPoint'‚
And 'DecompressionPoint' <= 'LowerDeadPoint'‚
And 'ClampingPoint' – 'MutePoint1' = 'MuteDistance1'‚
Examples:
| Material | Sheet thickness | Bending angle |
| 1.0038 | 0,1 | 90,0 |
| 1.0038 | 1,0 | 90,0 |
| 1.0038 | 3,0 | 90,0 |
When requirements are linked to automatically executable test cases in this way, it is referred to as a "living specification". The entire process of creating such a specification, from requirement to test, consists of six steps:
1. Specify
2. Implement test steps
3. Run the test
4. Write program code
5. Obtain continuous feedback from the tests
6. Done!
This approach therefore supports a "test-first" approach, where a complete set of automated tests is written first, fully covering the requirement. Only then is program code written until all tests pass.
When applied correctly, Specification by Example allows for earlier and more comprehensive consideration of special cases, thereby preventing errors. Involving the customer, product owner, and team in the creation process fosters a shared understanding of the requirements. Finally, automating the tests ensures that even with changes to requirements, all scenarios will continue to function flawlessly.
Sources
Gojko Adzic, „Specification by Example“, Manning Verlag, 2011
Johannes Bergsmann, Markus Unterauer, „Requirements Engineering for Agile Software Development“, dpunkt.Verlag, 2014
Markus Unterauer, „Workshops in Requirements Engineering“, dpunkt.Verlag, 2014
Requirements – MicroConsult Training & Coaching
Do you want to bring yourself up to date with the latest technology?
Then find out more here MircoConsult offers training courses/seminars/workshops and individual coaching on the topic of requirements/embedded and real-time software development.
Training & coaching on the other topics in our portfolio can be found here. here.
Requirements – Expertise
Valuable expertise in the field of requirements/embedded and real-time software development is available. here Available for you to download free of charge.
You can find expertise on other topics in our portfolio here. here.
