Seven Things to do When Starting Specification by Example with Cucumber

I was asked “What to do in terms of training and practice when starting to use gherkin to define requirements?” Although I’ve written quite a lot of material on Specification by Example I haven’t written about how to start doing it.

Here is a quick reply:

  1. Read about it
  2. Get a coach
  3. Form a workgroup
  4. Start small
  5. Agree a style
  6. Keep the Gherkin clean
  7. Let me know how you get on

Read about it

There are lots of books but the essential reading list contains only two: Specification by Example (Adzic, 2011) and the Cucumber Book (Wynne & Hellesøy, 2012).

I also like to think my posts on Specification by Example offer some useful insights, particularly:


I’m a big fan of using coaches when taking a team into new territory. Specification by Example using Cucumber and Gherkin is tricky and you’ll benefit from getting advice from an expert.

Form a workgroup

Get more than one person doing it – writing the Gherkin and associated step definitions – so you can get different perspectives. Organise a regular get together to discuss. This might start out daily, go to weekly when you’re a bit more comfortable and will naturally stop when everybody is comfortable.

Start Small

Don’t try to boil the ocean. Start with one scenario in one, preferably small, feature file. You’ll expand from there but don’t try to do everything at the start.

Agree a style

You won’t have a style at the beginning, this will evolve with time. But it helps if you make that evolution explicit. This gets decisions on the table for your workgroup to talk through.

Personally I recommend Declarative and Specifying Business Rules by Example but opinions differ.

Keep the Gherkin Clean

Remember to keep the Gherkin clean and push nasty implementation details to the Step Definitions. I want the business to be able to read the Gherkin so try to Specify Business Rules by Example. However, the developers need a lot of detail to be a able to implement the tests. Business wins; push what the developer needs into the Step Definitions.

Let me know how you get on

I’m always curious how other folk are getting on with their attempts to do Spec by Example, BDD, Gherkin and/or Cucumber. Please drop me a line.

This post is part of my What do I do When … ? series. Please drop me a line or add a comment if you’ve got a question you’d like answered.


Adzic, G. (2011). Specification by Example: How successful teams deliver the right software. Manning.

Wynne, M. & Hellesøy, A. (2012). The Cucumber Book: Behaviour-Driven Development for Testers and Developers. Pragmatic Bookshelf.