Creating a system model from gherkin

Identify entities and process of a system from gherkin

Gherkin is a human readable language which helps you to describe business behavior without going into details of implementation. With the implementation it becomes an executable specification which can be run with tools like behave automatically. This can create powerful CI/CD pipelines that are able to verify every commit against the specification.
In addition the Gherkin specification can be used in the Design phase of a software development iteration to identify the model and processes of the system. In this blog post I write about how I identified entities and process from a Gherkin specification.

Introducing irata

I recently started to reprogram the vintage Commodore 64 game M.U.L.E. . The game contains a land grant phase where players can choose a piece of land. For details see the C64 wiki page .
The first step as described above was to write down the Gherkin specification for the land grant phase or better: feature. For the start I only captured the rough outline for the land grant. The feature file I used can be found here

An example

Here is an excerpt from the specification:

Feature: Land grants let players choose a plot from the map

Scenario: Land grant
  Given I start a game
  And I create a map
  Then the map should contain 9 x 5 plots
  When I start the land grant
  Then the current plot should contain the following attributes:
    | x | y | type  | state | owner |
    | 1 | 1 | land  | free  |       |
  When I advance the land grant 4 times
  Then the current plot should contain the following attributes:
    | x | y | type  | state | owner |
    | 5 | 1 | river | free  |       |
  When I advance the land grant 19 times
  Then the current plot should contain the following attributes:
    | x | y | type  | state  | owner  |
    | 5 | 3 | store | taken  | system |
  When I advance the land grant 23 times
  Then the state of the land grant should be "finished"

It should be understandable even if you are not familiar with the game. By examining the nouns and verbs one could deduct the following entities and processes:

• Map
  • properties:
    • plots
  • methods:
    • create
• Land grant
  • properties:
    • map
    • state
  • methods:
    • start
    • advance
• Plot
  • properties:
    • coordinates
    • type
    • owner

In addition we can also see that the land grant advances from plot to plot until all plots have been traversed. So some behavior is captured as well. The rough class model deducted so far looks like this:

+---------------+
|               |
|  LandGrant    |
|               |
| state         |
| map           |
+---------------+
| start()       |
| advance()     |
+-------+-------+
        |
        |
      1 | map
+-------v-------+          +---------------+
|     Map       |          |     Plot      |
|               |     1..* |               |
| width         +--------->| coordinates   |
| height        |    plots | type          |
+---------------+          | owner         |
| create()      |          +---------------+
+---------------+

Conclusion

One might ask: What’s the big deal ? Aren’t models always created from specification ?
Well I think that there are three advantages of using this approach:

1. Gherkin specifications are located nearer (technology wise) to the model. Both could be version controlled and developed in parallel
2. The usually simple Gherkin specifications does not leave as much room to interpretation than higher level documents (e.g. Word-Documents)
3. Tests for the compliance the entities to the specification can be checked automatically at every time

So overall I think that a BDD first approach like this has some advantages…

Back to Home