From BDD Specs to Use Case Specs (Part 1)
About Use Case Specs
What is a use case specs?
Use case specs is a readable document that derived from the BDD Specs. This document is more technical, so it is more suitable for developers. the use case specs reflects the precondition, steps, happy path (if success), and sad path (if error or any fail condition). Usually, it has input part, process, and output.
Why we need this?
The use case specs can helps the developers, more easier to understand the feature, since the terms is more technical. By creating this, developers can get more clear requirement in exact steps or types. This documents can further improved as a use case / interactor component, represented by an object.
Where to put it?
A use case specs is a feature documented in a certain format. I personally put the document as close as possible to the project. If I have one Xcode project, I usually put on the Readme.md file. But, you can put it anywhere you want.
A use case can be represented as code components. If it is,iIn the famous circle uncle bob diagram, use cases belongs to the inner circle. In this case, we can can immediately see there is no additional framework inside the core layer. In the case, the business logic is a component that separate from any framework infrastructure layer. It does not belongs to the UI, which mean not importing UIKit for example. It does not know the Database, which mean it doesn’t import CoreData. and etc. Just pure Logic.
When to use this?
Of course it depends on the team, app size and complexity, and etc. But, my advice is, create this as early as possible. make it as an habit. because the use case specs, which be created as an object, — which mean a separate component for business logic for the app — can be reused across the applications. If we want to create a new feature, it is a good place to start, to look at the use case specs document.
Who create the use case specs?
Usually, the business analyst is responsible to documenting the BDD specs, or write the requirement in Gherkin. But, the more technical roles needs more technical documents. So, Use case specs and the use case class mapping are more to technical person, the developers.
Converting BDD Specs into Use Case Specs
We can map the requirement from seeing the BDD specs, or the Gherkin. Let’s analyze the BDD specs that used on the previous article.
Scenarios (Acceptance criteria)
Given the customer does not have connectivity
And there’s a cached version of the transactions
When the customer requests to see their transactions
Then the app should display the latest transactions from localGiven the customer does not have connectivity
And the cache is empty
When the customer requests to see their transactions
Then the app should display empty transactions
Let’s breakdown it into a use case specs :
Load Transactions From Cache Use Case
Input:
- no data needed
Primary course:
- Execute “Load Transactions” command with above data.
- System retrieves transaction data from cache.
- System creates transaction from cached data.
- System delivers transactions.
Retrieval error course (sad path):
- System delivers error.
Empty cache course (sad path):
- System delivers no transactions.
This use case specs above, called Load “Transaction From Cache Use Case”, is created based on the BDD specs created before. This document is become more technical, since it knows the technical terms like execute, cache, delivers, error, etc.
Conclusion
Use case specs is derived from BDD specs, is a more technical documents that can helps developer to create a real use case object or class representation in the code. The document plays an important role in clean architecture requirement, so that everyone, especially the developers, will not having many assumptions to the feature.
The next thing to do is converting the use case specs into code. If you want see how to convert the use case specs into use case object, you can see in the following article in the next month since this published.
References :
Object Oriented Software Engineering — A Use Case Driven Approach (Ivar Jacobson)
Robert C Martin — Clean Architecture and Design (https://www.youtube.com/watch?v=Nsjsiz2A9mg)
