BDD — A short tale of what drove us to adopt it in our mobile team

Rony Brosh

Published in

Tide Engineering Team

8 min readJun 6, 2023

Hi fellow engineers 👋

My name is Ron. I’m a mobile staff engineer and tech owner in the onboarding team at Tide.

This article is for both technical and non-technical people working together to deliver value to their members. I won’t dive into technical details about how to implement Behaviour Driven Development (BDD) but I’ll leave links to a few resources I find helpful.
I still recommend reading this short article to get some context.

Let me share with you the path that drove us to adopt BDD in my team.

We’ll talk about:

The challenges we had
Why I think BDD is the solution and how specifications relate to it
Actual examples from our POC (proof of concept)
And finally the outcome and next steps

Let’s start!

Challenges

The first challenge we had was to migrate all the existing features from the native iOS and Android apps to a new shiny Flutter app.

The problem was that no one really knew what the actual requirements were. Unfortunately, we didn’t have any useful documentation so we had to DIG the requirements from the CODEBASE!

Think about it. My team is responsible for the onboarding flow. That’s probably one of the first features we ever developed!
You can imagine how painful it was to read a years-old code base…
Check out this screenshot, it’s from our native repository, 7 years old!

What made it hard to dig the native repository is that the coding language is completely different. In the iOS project, we used Swift and Objective-C, for Android, we used Java and Kotlin whereas for Flutter we use Dart.

Also, the architecture is different between the projects.
In the native projects we used MPV and MVVM whereas in the Flutter project, we use the Bloc pattern which is similar to MVI.

Also, new engineers, some with no native background, and product managers joined the company so there is barely anyone, if any, who remembers the requirements.

Because of that, it took us a long time to develop existing features.
Not new!
That’s not good!

As we’ll see in the next section, that wasn’t even our last migration.
How can we prevent such long development times?
Moreover, how can we prevent misinterpreting the requirements caused by a lack of documentation?

Challenges (continue)

Like most tech companies, we also started with a single market and hoped to expand one day and reach multiple markets.

During the above Flutter migration, we opened more markets and created new apps for them. Talking about migration, we also had to migrate our authentication mechanism and switch to new endpoints and contracts.

Because of time concerns and strict timelines, we worked in silos. One or two engineers were dedicated to a single market.
During that time we accumulated duplicated screens and functionality and tech debt started to pile up.

Also, we couldn’t cover or help each other because of a lack of domain knowledge between markets.

Moreover, each market has its own unique requirements which makes it complicated. Some markets have different orders of screens, sets of features, and even endpoints!
That’s not good!

We knew that we wanted to support multiple markets using a single codebase and reusable code, create a culture where anyone in our team can work on it, and easily scale up and create new markets on demand.

But how can we have confidence that a change in one market won’t break another? How can we easily test it?

This is when I suggested trying BDD practices as a way to document the specifications and make them accessible to everyone.

Specifications

Or in simpler words: How to verify that we know what to build before we rush into it?

So what is BDD?
You probably already know it means Behaviour Driven Development.
What does behaviour mean? We have so many abstract abbreviations and buzzwords in our industry, don’t we?

I find it easier to be explained as a practice for Documenting specifications through collaboration.

Let’s see how specifications relate to BDD.
According to the Oxford Dictionary specification means:

A detailed description of the dimensions, construction, workmanship, materials etc., of work done or to be done, prepared by an architect, engineer etc.

Let’s break this definition.

“…A detailed description of the…”
That resembles the requirements.

“…prepared by an architect, engineer, etc…”
That sounds kind of like the Three Amigos isn’t it?
(The Three Amigos is a BDD practice where people from different functions of the team sit together to discuss the features)

“…of work done or to be done…”
That resembles the Acceptance criteria.

It sounds like there’s a connection between specifications and BDD.
So why should we use it?

Communication tool
BDD allows us to clearly communicate requirements so there’s less rework due to misinterpreted requirements and acceptance criteria
Strong collaboration
Thanks to the shared language, product owners, developers, and testers all have in-depth visibility of the project’s progression.
Are you familiar with the DOR (definition of ready) and DOD (definition of done)? (A lot of buzz word 😅)
How much time would it save us if we’ll know in advance if a ticket is really ready to be developed? How would we know when it’s done?
Shorter learning curve
Since BDD is explained using very simple language, there’s a much shorter learning curve for everyone involved
Automated tests
Compared to unit tests which focus on implementation, with BDD we can test the actual requirements
And Live documentation
I’ll talk about it more a bit later

POC

During the Flutter migration our product manager (let’s call him James), another senior mobile engineer (let’s call him Jamie), and I sat together to dig the requirements from the old native codebase and refine the first story — Sharing a referral code.

We used simple language and went through all the possible edge cases we could think of using examples and wrote them in a BDD format.

It wasn’t easy but we kept refining the story until we were all happy with it and felt confident that we knew what to implement and how to test it.

We even added the BDD scenarios to the Jira ticket so it will be visible to everyone. That felt and worked great!

Since Jamie merged this feature I don’t recall any issues around the referral code feature. It was months ago (around December 2022).

POC (continue)

Then, to work on the multi-markets initiative, I organised a BDD session with all the product managers and mobile engineers in our team.

That was probably the first time a product manager of one market talked with an engineer of a different market. I was really impressed by their engagement and willingness to cooperate. I’m lucky to have such great colleagues in my team!

We picked the very first screen in every onboarding flow.
The signup screen. You know the one with the email field.
Then we started to write the first scenario:
“Given I’m on a market”.

Then I asked our product managers “Mmm which fields should we see on the screen for each market?”

One product manager said “Email and phone number!”, another product manager shouted, “We need the same for our market too!”
Then another product manager mentioned that she also wants a referral code to be there, and the fourth product manager said that actually, they don’t need the email field for their market. The phone number and the referral code are enough.

We also mentioned that we need a different phone number prefix for each market and so forth.

That was amazing! Four product managers and five engineers sat together, discussing and communicating the requirements and how to test them while creating a common language. All of that in the same session!

After we finished refining that scenario everyone in the room knew exactly what to expect, implement, and how to test it even if they never “worked” on that market before!

What about you?
Even if you are not a mobile engineer in an onboarding team, can you guess what will happen when you’ll land on that signup screen?

Outcome

So does it work? Absolutely!

Communication tool?
Yes!
Strong collaboration?
We got it!
Shorter learning curve?
I’m sure we do and the next new joiner to our team could confirm it
Automated tests?
That goes without saying
Live documentation?
Well not yet.

Even though we document the BDD scenarios in both our Jira tickets and the codebase, there is no guarantee that what is written in the ticket is implemented correctly in the codebase.

I found a way though to connect confluence pages and our repository so we can have real live documentation. We can actually render BDD files from our repository directly into confluence using a plugin.
For me, that’s a game changer. That’s a real full cycle!

I’ll share a demo in the future which I think you are going to like!
In the meantime, you can find this confluence plugin here.

Alright. That’s our output but what about the outcome?
Well, we now have a way to deliver value to our members that is actually what our product managers planned for them.

And you know what? I don’t know what will replace Flutter in the future but I can assure you that for the next technical migration, we will only need to copy the BDD files. As soon as their tests pass we’ll know we’re done!

As for the next steps, we continue to do BDD sessions on a weekly basis.
Since we started we have had many sessions already.
With every session, we get better and better at writing BDD scenarios which also increases our productivity.

If you want to learn more about BDD here are some links for books and an article I like:

If you want to get your hands dirty, check out this BDD library for Flutter.
I use it in every project I work on and it’s written by two brilliant engineers, Oleksandr Leushchenko and Anna (Domashych) Leushchenko 👩‍💻💙📱🇺🇦, I’m lucky to call colleagues!

Now before you go, don’t just take my word for it.
I encourage you to try it yourself with your team.
That’s one of the things I like about our industry. We have the resources to learn and the opportunity to try out new tech, new strategies, and practices!

Maybe it will become part of your team’s ways of working too!

Thank you 😎