Stories
A story, simply put, is a script which tells how to run your code. It’s where you do all the setup work and kick off execution.
Cover edge cases
A story represents an instantiation of your code. You are free to create as many as you want.
Each story, tells a different about your code, your design. This is where you comprehensively communicate all the edge cases, all the “What If?” questions and let your audience see every angle of the designed system.
Let’s look at an example. Say we have an authentication system where the db can fail, and does things differently if it indeed fails. To capture this, we can write the following code:
class AuthenticationService {
isDatabaseDown = false;
authenticate(sessionToken: string) {
if(this.isDatabaseDown) {
return {
type: 'error',
message: 'Database is down!'
}
}
return {
type: 'response',
message: 'User is authenticated!'
}
}
}
Here we are being very explicit, and saying that to simulate an error behaviour isDatabaseDown
should be true
.
You can always make it more real by adding methods that mimic real world systems. At the same time, you always have these escape hatches at your disposal. You can just use flags as railway switches and change tracks.
Now, to cover both the cases, we can create two stories!
One where isDatabaseDown
is false
and anothere where it’s true
.
Here’s another example of a system which depends on a payment gateway(of sorts). The first story showcases how a particular condition can cause
two different entries in our system for the same payment.
From the ‘Stories’ dropdown, choose the other story to see how the system behaves normally.
In the first story we see that the poller and webhook align perfectly to create a blind spot. Both start working on the same payment, not knowing that the other is doing the same. This leads to our system capturing the same payment twice!
Click here to open in a tab
Things might be squished here!
Advantage
Each story, is the exection of same underlying code but under different conditions.
Just write a script, change the initial conditions, and you get a completely new perspective of the design, without repeating yourself.
But what was that std.flow
business in the script? What does it do? Why does it have that weird syntax?
Well, let’s find out in the next section!