I'd like to pose this question since it seems to be a point of some debate and I'd like to know the communities thoughts on it.
To give you a bit of background to the way the team I work in operates and give this question some context, we're writing cucumbers for a RESTful API at a session called 'Three Amigos'. Three Amigos basically means there will be a Tech Lead, Developer (one or more) and BA (one or more) involved in fleshing out the acceptance criteria for a story. As part of this session the BA usually drives writing the gherkins for the cucumbers.
Here's an example to kick it off. If I have a RESTful API for getting back information about a car I may have a scenario that says:-
Scenario: Engine size should appear in the car
Given a car exists
When I request the car
Then the car should have a "1700cc" engine capacity
Or you could write it like
Scenario: Engine size should appear in the car
Given a "Mazda/ModelABC" car exists with an engine capacity
When I GET "Mazda/ModelABC"
Then the response should contain "1700cc" engine capacity
Now the first one in my eyes is easier all round to read but will not promote code re-use (is this a big deal?). The second promotes code re-use and is written from the perspective of a stakeholder i.e. a developer but a Business Analyst (BA) would not write it like this so it would make a Three Amigos session fairly pointless.
Given the two approaches which is the more highly recommended choice? I have opted for the first approach in my case but I'm interested to know what the arguments for either method are or if there are some decent articles people can back up the suggestions with that would suggest which approach should really be used.
Thanks.
You can put "IMHO" after every paragraph in this answer. This is my experience after doing BDD / Specification by example for four years.
BDD is about communication. BDD is about understanding each other in the entire team.
Cucumber is (just) a tool that facilitates communication. The only reason to use Cucumber (and the extra abstractions it adds) is because it will make it easier to understand each other than other formats. If we were only developers in the team we would probably be better off using code.
So, to answer your question, if your BA's and customers understand GET, POST etc then it might be appropriate to use that in the specification. But beware that you've just tied the specification to the implementation. Changes will propagate even into the Cucumber scenarios.
More likely your first example is format that your customers and BA's can relate to and understand straight off.
But, of course, it depends on the level of technical details your non-technical team members are using. Make it easy for everyone to understand.
BDD is about communication.
Here's some presentations on the subject that I've found both useful and in one case thoroughly entertaining: