First off I want to make it clear that I’m not a guru on the topic, but I do find it interesting. The topic of course is Context Based Specifications. I’ve seen an emergence in interest in writing context based specifications lately on the blogosphere. However, everyone seems to be advertising it slightly differently…
Making Specs Human-Readable
One of the things that our team tries to aim for is to keep technical language out of our specifications. They should be human readable sentences, not “Yoda” speak. This is crucial if we want non-technical people to actually read our specs to make sure the code is inline with what the business is attempting to do.
The goal, in our humble opinions, is to work closer towards the ubiquitous language. The benefit is that documentation is updated along with the code, because it is the code.
Technical vs. Business Language
Something that reads like this:
when_the_account_controller_is_given_valid_arguments_on_the_register_account_action
Doesn’t read as easy as:
when_registering_a_new_account
The first example is full of technical implementation details - controllers, actions, arguments. The second focuses on what the user is actually trying to accomplish. Which one would a business analyst prefer to read?
Structure: Specs First, Context Second
Another subtle change that our team made was to put the specs above establishing the context. In some cases it just seems to read better from top to bottom:
when_creating_a_new_account_for_a_user_with_a_valid_submission
- it_should_inform_the_user_that_the_account_was_created
- it_should_save_the_new_account_information
under_these_conditions
- user_provides_valid_email_address
- user_provides_strong_password
- terms_and_conditions_are_accepted
because_of
- business_requirement_to_validate_new_users
“It” being the system under test.
This reads more like a story: “When this happens, the system should do these things, given these conditions, because of these reasons.”
Why This Matters
We don’t always get it right, but by trying to drop the technical language we force ourselves to step away and think about the problem that we are ultimately trying to address.
Are we building software to test controllers and validate arguments? Or are we building software to help users register for accounts? The language we use in our specs reflects which perspective we’re taking.
When we write specs that sound like business requirements, we’re more likely to catch cases where our technical implementation doesn’t match what the business actually needs.
The Real Benefit
The biggest win isn’t just readable specs - it’s that this approach forces better conversations between developers and business stakeholders. When a product manager can read your test names and understand what the system does, you know you’re on the right track.
Plus, when someone asks “What does this feature do?” six months from now, your specs can actually answer that question in plain English.
Again… this is just my our 2 cents.