March 14 18:10~19:02; 20:28~23:23
▲Figure 1: ezSpec domain model
foreword
Behavior-Driven Development (BDD) and Specification by Example are two mainstream test-driven development methods. By discussing requirements (collaborative modeling) with domain experts or stakeholders, as well as specific examples representing requirements, and expressing them in automated test cases, the effect of Living Documentation can be achieved.
In the process of developing ezKanban, Teddy made ezSpec in 2021—it is an Internal DSL written in Java, which can simplify the trouble of using tools such as Cucumber or JBehave (please refer to < Painless writing acceptance test files in test cases > ). Teddy originally developed ezSpec because he wanted to do research on Living Documentation. Later, he was too busy with ezKanban. After completing ezSpec, he could only use it in ezKanban. He had no time to further make it fully support Living Documentation. For some reason, ezSpec was taken out for “active development” for some time, and after a while, it was developed to a stage where it was ready to be open-sourced. Write a few articles to introduce ezSpec before open source.
***
Domain model and usage examples of ezSpec
Figure 1 is the domain model of ezSpec. Basically, ezSpec is designed with reference to the Gherkin syntax. The difference is that ezSpec can describe Story and execute steps synchronously. These details will be described in detail later, and the meaning of each object in the domain model will be introduced first:
- Feature : Function, which represents a unit that can provide user value. There are different usages of the “granularity” of a Feature. Some people regard the “whole functional module” as a Feature, and then cut it into smaller functions through Story or Scenario. For example, consider “checkout” as a Feature, which includes cash checkout, credit card checkout, xxx Pay, etc. Some people use Feature as a separate function, and the granularity is equivalent to the traditional use case (Use Case).
- Story : The story is the User Story often used by the agile community. Gherkin/Cucumber itself does not support Story, but JBehave does. Some people argue that Story is just a task assignment unit used to “cut requirements” during the development process, and the final delivery to users is Feature. Since Gherkin is a grammar used to describe requirements, there is no need to use Story to record the “temporary product” of the development process. But many people in the traditional agile community may be used to using Story as the smallest unit of requirement communication, so they think it is better to have Story. ezSpec supports Story, and a Feature can have one or more Stories.
- Scenario : Scenario. Basically, a Scenario can be imagined as an Example in Specification by Example, communicating requirements through examples. What exactly does a Feature or Story do? Using examples to express, more specific and clear, can also reduce misunderstandings. After listing several representative scenarios for a Feature or Story, if the team feels that they can already understand the content of this feature, these examples become the acceptance conditions for this feature. If these examples (that is, Scenario) can be turned into programs for automatic execution, they become automated acceptance tests. Figure 2 shows a scenario example of ezSpec. Since ezSpec is an Internal DSL (Domain Specific Language), using ezSpec to describe a specification is similar to writing a program, directly writing Gherkin’s Given-Then-Then content in lambda.
▲Figure 2: ezSpec Scenario example, pending() indicates that the Step has not yet been implemented
Figure 3 is the report generated by ezSpec executing the Scenario in Figure 2.
▲Figure 3: Scenario execution result report generated by ezSpec
***
- Scenario Outline : Scenario Outline: After giving a few examples for a Feature or Story, if you find that the execution steps of these examples are the same, only the input data and execution results are different, you can organize these individual Scenarios into a Scenario Outline. Scenario Outline is basically “parametric testing” or “data-driven testing” in traditional software testing. In Gherkin, the way to provide different data is to specify a set of Examples . Please refer to the example of ezSpec ScenarioOutline in Figure 4, and the content of the example form is from https://reurl.cc/qkrL9y .
▲Figure 4: Example of ezSpec ScenarioOutline
Lines 160 to 177 in Figure 4 are where Examples are specified. There are five test data in total for the two sets of Examples. A Scenario Outline is added in lines 179~187. The entire Scenario Outline is written in the test method of JUnit 5. The execution result is the same as a general test case and can be seen in the JUnit report, as shown in Figure 5.
▲Figure 5: Scenario Outline execution results
ezSpec can generate text reports for the execution results of the entire Feature. Figure 6 is the report generated by the above Scenario Outline execution results. You can see the input data of each round of execution and the execution results of each step (Step, please refer to the description below). .
▲Figure 6: Scenario Outline execution result text report generated by ezSpec
***
- Runtime Scenario : Scenario is an abstract category in ezSpec. During execution, each Scenario and Scenario Outline will generate a Runtime Scenario object for each execution after the Scenario Outline is expanded, which is used to record input data and execution results.
- Background: background, please refer to Figure 7, similar to JUnit’s @BeforeEach, you can define the common steps of multiple Scenarios in the Background, and then reuse them. Although Background achieves the benefit of reducing repeated description steps, it will make Scenario less easy to read, and you need to make a trade-off when using it.
▲Figure 7: Example of ezSpec Background
- Step : Step, a Scenario can contain multiple Steps. Given, When, Then, And, But all belong to a type of Step.
- Given : Used to describe the preconditions for executing a function.
- When : Used to describe the execution function, which is what traditional testing calls “executing the program under test”.
- Then : Used to verify the result after the execution of the result function.
- And, But : After Given, When, Then, And and But can be added as the next step.
- Concurrent Group : Gherkin’s Step only supports sequential execution, that is, you cannot use Gherkin to describe the specification of synchronous behavior. Teddy’s advisor, Mr. Zheng, directed a group of students who research IoT to develop a tool called concurrentSpec in Python, which can originally use Gherkin’s grammar to describe the synchronous behavior specification of the IoT system. Originally, ezSpec only supported sequential Steps, but only in the last month did it refer to concurrentSpec, adding the ability to describe synchronous behavior.
***
epilogue
The traditional use of Cucumber, SpecFlow or JBehave is to first use Gherkin to write a feature file (or story file) in plain text, and then generate Step Definition Method/Function through the tool, and then the developer will do these Step Definition Method when going Specifications become executables.
In this way, it was originally hoped that domain experts or stakeholders could directly use Gherkin to describe requirements with examples, and then hand them over to developers to convert them into automated acceptance tests. The concept is very good, but this method has a big problem, that is, the Step Definition Method is difficult to write, and it is not easy to read and maintain. Because many regular expressions are used to pass the content described in the feature file to the program, you must first learn the tedious writing specifications of different tools for Step Definition. It is easy to make mistakes in actual use, which prevents developers from concentrating on describing specifications and examples. .
Switch to the Internal DSL method, directly remove the annoying Step Definition and regular expressions, and the entire BDD/SBE/TDD process becomes very smooth. The way of using Internal DSL was not invented by Teddy. Someone did it with Ruby, but Teddy didn’t trigger himself to use Java until he saw a similar example in the book ” Living Documentation: Continuous Knowledge Sharing by Design ” in 2021. Idea for developing similar tools.
The results of Teddy’s own use show that it is really much more convenient. This episode comes here first, and then introduces each function of ezSpec in detail one by one.
***
You Zang’s inner monologue: The software has not been opened yet, the file must be opened first.
This article is transferred from https://teddy-chen-tw.blogspot.com/2023/03/ezspec1.html
This site is only for collection, and the copyright belongs to the original author.