BDD with Cucumber (Ruby)

Shouty is a social network that allows people who are physically close to communicate, just like people have always communicated with their voices. In the real world you can talk to someone in the same room, or across the street. Or even 100 m away from you in a park - if you shout.

That’s Shouty. What you say on this social network can only be “heard” by people who are nearby.

Let’s start with a very basic example of Shouty’s behaviour. Something we might have discussed in a three amigos meeting:

Sean the shouter shouts "free bagels at Sean’s" and Lucy the listener who happens to be stood across the street from his store, 15 metres away, hears him. She walks into Sean’s Coffee and takes advantage of the offer.

🎬 1 We can translate this into a Gherkin scenario so that Cucumber can run it. Here’s how that would look.

You can see there are four special keywords being used here. Scenario just tells Cucumber we’re about to describe an example that it can execute. Then you see the lines beginning with Given, When and Then.

🎬 2: Highlight line 2 Given is the context for the scenario. We’re putting the system into a specific state, ready for the scenario to unfold.

🎬 3 When is an action. Something that happens to the system that will cause something else to happen: an outcome.

🎬 4 Then is the outcome. It’s the behaviour we expect from the system when this action happens in this context.

You’ll notice we’ve omitted from our outcome anything about Lucy walking into Sean’s store and making a purchase. Remember, Gherkin is supposed to describe the behaviour of the system, so it would be distracting to have it in our scenario.

Each scenario has these three ingredients: 🎬 5 a context, 🎬 6 an action, 🎬 7 and one or more outcomes.

Together, they describe one single aspect of the behaviour of the system. An example.

Now that we’ve translated our example into Gherkin, we can automate it!

Before we get started make sure you have a modern version of Ruby installed, and the Bundler gem. Open a command-prompt and check the Ruby version, 🎬 1 and the version of Bundler, Ruby’s package manager: 🎬 2

If you see an error message when you run these commands, you’ll need to fix your Ruby installation.

🎬 3 Go back to the command prompt and create a new directory for our project:

Use cd to go into that directory. 🎬 4 If you want to, you can open the directory up in your favourite text editor at this point.

🎬 5 🎬 6 First we’ll create a Gemfile that describes the Ruby gems we need for our project. 🎬 7 We’ll add Cucumber and 🎬 8 RSpec-Expectations.

Now go back to the command-line 🎬 9 and run bundle install to install those gems.

Now we’re ready! If we run cucumber at this point 🎬 10, we’ll see it’s telling us to create a features directory.

Good, we’ve installed Cucumber.

🎬 11 As instructed, we can use the cucumber --init command to create the conventional folder structure for our Gherkin specifications and the code that will let Cucumber test them:

Now we’re ready to create our first feature file.

🎬 12

Let’s create our first feature file. Call the file hear_shout.feature 🎬 1

🎬 2 All feature files start with the keyword Feature: 🎬 3 followed by a name. It’s a good convention to give it a name that matches the file name.

🎬 4 Now let’s write out our first scenario.

Save the file, switch back to the command-prompt 🎬 5 and run cucumber. 🎬 6

You’ll see Cucumber has found our feature file and read it back to us.🎬 7 We can see a summary of the test results below the scenario: 🎬 8 one scenario, 🎬 9 three steps - all undefined. 🎬 10

🎬 11 Undefined means Cucumber doesn’t know what to do for any of the three steps we wrote in our Gherkin scenario. It needs us to provide some step definitions.

🎬 11.1: 02.04.animation.mp4

Step definitions translate from the plain language you use in Gherkin into Ruby code.

When Cucumber runs a step, it looks for a step definition that matches the text in the Gherkin step. If it finds one, then it executes the code in the step definition.

If it doesn’t find one… well, you’ve just seen what happens. Cucumber helpfully prints out some code snippets that we can use as a basis for new step definitions.

🎬 12 Let’s copy those to create our first step definitions.

🎬 13 🎬 14 We’ll paste them into a Ruby file under the step_definitions directory, inside the features directory. We’ll just call it steps.rb.

🎬 15 Now run Cucumber again.

This time the output is a little different. None of the steps are undefined anymore. We now have a pending step 🎬 16 and two skipped ones.🎬 17 This means Cucumber found all our step definitions, and executed the first one. 🎬 18 But that first step definition throws a PendingException, which causes Cucumber to stop, skip the rest of the steps, and mark the scenario as pending.

Now that we’ve wired up our step definitions to the Gherkin steps, it’s almost time to start working on our solution. First though, let’s tidy up the generated code.

🎬 19 We’ll rename the int parameter to something that better reflects its meaning. We’ll call it distance.

🎬 20 We can print it to the terminal to see what’s happening.

If we run cucumber again on our terminal, 🎬 21 we can see the number 15 pop up in the output.🎬 22

Notice that the number 15 does not appear anywhere in our Ruby code. The value is automatically passed from the Gherkin step to the step definition. If you’re curious, that’s the 🎬 23{int} in the step definition pattern or cucumber expression. We’ll explain these patterns in detail in a future lesson.

🎬 1 Now that we have the step definitions matching, we can start working on our solution. We like to use our scenarios to guide our development, so we’ll start designing the objects we’ll need by sketching out some code in our step definitions.

The scenario will be failing while we do this, but we should see the error messages gradually progressing as we drive out the interface to our object model.

Our next goal is for the scenario to fail because we need to implement the actual business logic. Then we can work on changing the business logic inside our objects to make it pass.

🎬 2 To implement the first step, we need to create a couple of Person objects, with the specified distance between them. 🎬 3 We can remove the pending status now, and this puts statement,🎬 4 and write the implementation for the first step like this:

We have two instances of person, one representing Lucy, 🎬 5and one representing Sean. 🎬 6Then we call a method to move Lucy to the position specified in the scenario.🎬 7

🎬 7.1: 02.05.animation.mp4

To keep things simple, we’re going to assume all people are situated on a line: a one-dimensional co-ordinate system. We can always introduce proper geo-locations later. We’ll place Sean in the centre, and Lucy 15 metres away from Sean.

This might not be the design we’ll end up with once this is all working, but it’s a decent place to start.

🎬 8 If we run Cucumber, we’ll see a compilation error from Ruby. we need to define our Shouty module.

🎬 9 Let’s give our solution a home by creating a lib directory. 🎬 10 We’ll put our Shouty application in a Ruby file called shouty.rb in that directory.

🎬 11 Create a Shouty module, then an empty Person class inside it. 🎬 12

🎬 13 For now, we’ll just require the shouty application from our steps.rb file. In a later lesson we’ll talk more about how to organise this code a bit better.

🎬 14 When we run the scenario this time, Cucumber tells us that we’re missing the move_to method on the Person class. 🎬 15

🎬 16 We’ll add the method definition without implementing it yet.

🎬 17 When we run the scenario again, the first step is green!

We’re making progress!

We’ll keep working like this until we see the scenario failing for the right reasons.

In the second step definition, we want to tell Sean to shout something.

🎬 18 In order to send instructions to Sean from the second step, we’ve stored him in an instance variable, so that he’ll be accessible from all of our step definitions.

🎬 19 In the When step, we’re capturing Sean’s message using the {string} pattern, so let’s give that argument a more meaningful name.🎬 20

🎬 21 And now we can now tell him to shout the message:

🎬 22 If we run Cucumber, it’s telling is that our Person class needs a shout method.

🎬 23 Let’s not worry about the implementation yet. The most important thing right now is to discover the shape of our domain model.

🎬 24 The last step definition is where we implement a check, or assertion. We’ll verify that what Lucy has heard is exactly the same as what Sean shouted.

🎬 25 Once again we’re going to write the code we wish we had.

So we need a way to ask Lucy what messages she’s heard, and we also need to know what it was that Sean shouted.

We can record what Sean shouts by storing it in an instance variable as the When step runs.🎬 26 This is a common pattern to use in Cucumber step definitions when you don’t want to repeat the same test data in different parts of a scenario. Now we can use that in the assertion check.🎬 27

We also need to add a messages_heard method to our Person class.🎬 28 Let’s do that now, we’ll just return an empty array for now.🎬 29

…​and watch Cucumber run the tests again.🎬 30

This is great! Whenever we do BDD, getting to our first failing test is a milestone. Seeing the test fail proves that it is capable of detecting errors in our code!

Never trust an automated test that you haven’t seen fail!

Now all we have to do is write the code to make it do what it’s supposed to.

So we have our failing scenario: 🎬 1

Lucy is expected to hear Sean’s message, but she hasn’t heard anything: we got an empty Array back from the messages_heard method.🎬 2

🎬 3 In this case, we’re going to cheat. We have a one-line fix that will make this scenario pass, but it’s not a particularly future-proof implementation. Can you guess what it is?🎬 4

I told you it wasn’t very future proof!

🎬 5

Woohoo! Our scenario is passing for the first time. As long as this is the only message anyone ever shouts, we’re good to ship this thing!

Now, the fact that such a poor implementation can pass our tests shows us that we need to work on our tests. A more comprehensive set of scenarios would guide us towards a better implementation.

It’s also a good habit to look for the most simple solution. We can trust that, as our scenarios evolve, so will our solution.

This is the essence of Behaviour-Driven Development. Examples of behaviour drive the development. We do just enough to make the next scenario pass, and no more.

Instead of writing a note on our TODO list, let’s write another scenario that shouts a different message. 🎬 6

It fails, reminding us we need to find a solution that doesn’t rely on hard-coding the message. 🎬 7 Now when we come back to this code, we can just run the tests and Cucumber will remind us what we need to do next. We’re done for today!

Of course, if you’re in the mood, you can always try to implement a solution yourself that makes both scenarios pass. Have fun!

🎬 0.1: 03.01.animation.mp4

In the previous chapter we explored the fundamental components of a Cucumber test suite, and how we use Cucumber to drive out a solution, test-first.

First we specified the behaviour we wanted, using a Gherkin scenario in a feature file. Then we wrote step definitions to translate the plain english from our scenario into concrete actions in code. Finally, we used the step definitions to guide us in building out our very basic domain model for the Shouty application.

We tend to think of the code that actually pokes around with the system as distinct from the step definitions, so we’ve drawn an extra box labelled "automation code" for this.

Automation code can do almost anything to your application: it can drive a web browser around your site, make HTTP requests to a REST API, or — as you’ve already seen — drive a domain model directly.

Automation code is a big topic that we’ll come back to. First, we want to concentrate on step definitions. Good step definitions are important because they enable the readability of your scenarios. The better you are at matching plain language phrases from Gherkin, the more expressive you can be when writing scenarios. Teams who do this well refer to their features as living documentation - a specification document that never goes out of date.

When Cucumber first started, we used to use regular expressions to match plain language phrases from Gherkin steps.

Regular expressions have quite an intimidating reputation.

So we replaced them with something simpler, something we call Cucumber expressions. Cucumber is backwards compatible so you can still use the power of regular expressions if that’s your thing.

This chapter is all about Cucumber Expressions.

🎬 1 Let’s look at the Shouty scenario from the last chapter.

As Cucumber starts to execute this feature, it will come to the first step of the scenario Given Lucy is located 15 metres from Sean 🎬 2 and say to itself "now - do I have any step definitions that match the phrase Lucy is located 15 metres from Sean?”"

🎬 3 The most simple cucumber expression that would match that step is this one:

That’s pretty simple isn’t it? Cucumber expressions are just string patterns, and the most simple pattern you can use is a perfect match.

In Ruby, we can use this pattern to make a step definition like this: 🎬 4

We use a normal Ruby string to pass the cucumber expression to Cucumber.

🎬 1 Sometimes, we want to write step definitions that allow us to use different values in our Gherkin scenarios. For example, we might want to have other scenarios that place Lucy a different distance away from Sean. 🎬 2

To capture interesting values from our step definitions, we can use a feature of Cucumber Expressions called parameters.

For example, to capture the number of metres, we can use the {int} parameter: 🎬 3 which is passed as an argument to our step definition: 🎬 4

Now we’re capturing that value as an argument. The value 100 will be passed to our code automatically by Cucumber.

Because we’ve used Cucumber Expressions' built-in {int} parameter type, the value has been cast to an Integer data type for us automatically, so we can do maths with it if we want.🎬 5

Cucumber has a bunch of built-in parameter types: {int}, {float}, {word} and {string}. You can also define your own, as we’ll see later.

Although it’s important to try to use consistent terminology in our Gherkin scenarios to help develop the ubiquitous language of your domain, we also want scenarios to read naturally, which sometimes means allowing a bit of flexibility.

Ideally, the language used in scenarios should never be constrained by your step definitions. Otherwise they’ll end up sounding like they were written by robots. Or worse, they read like code.

🎬 1 One common example is the problem of plurals. Suppose we want to place Lucy and Sean just 1 metre apart:

🎬 2 Because we’ve used the singular metre instead of the plural metres we don’t get a match:

What a pain!

Fear not. We can just surround the s in parentheses to make it optional, like this: 🎬 3

🎬 4 Now our step matches:

This is one way to smooth off some of the rough edges in your cucumber expressions, and allow your scenarios to be as expressive as possible.

Another is to allow alternates - different ways of saying the same thing. For example, to accept this step: 🎬 5

…​we can use this Cucumber Expression: 🎬 6

🎬 7 Now we can use either 'standing' or 'located' in our scenarios, and both will match just fine:

Although you can get a long way with Cucumber Expressions' built-in parameter types, you get real power when you define your own custom parameter types. This allows you to transform the text captured from the Gherkin into any object you like before it’s passed into your step definition.

For example, let’s define our own {person} custom parameter type that will convert the string Lucy into an instance of Person automatically.

🎬 1 We can start with the step definition, which would look something like this:

🎬 2 If we run Cucumber at this point we’ll see an error, because we haven’t defined the {person} parameter type yet.

Here’s how we define one.

🎬 3 🎬 4 Let’s create a new Ruby file in features/support called person_parameter.rb:

We use the ParameterType DSL method from Cucumber to define our new parameter type. 🎬 5

We need to give it a name which is the name we’ll use inside the curly brackets in our step definition expressions. 🎬 6

We also need to define — gasp! — a regular expression. 🎬 7 This is necessary to tell cucumber expressions what text to match when searching for this parameter in a Gherkin step. We won’t go into the details of regular expressions in this video, but in this case we’re just matching on either of the names of the people we’re using in our scenario. 🎬 8

Finally, there’s a transformer block, 🎬 9 which takes the text captured from the Gherkin step that matched the regular expression pattern, and runs some code. The return value of this block is what will be passed to the step definition. In this case, the block is passed the name of the person (as a string) 🎬 10 which we can then pass to the Person class’s constructor. 🎬 11

🎬 12 All of this means that when we run our step, we’ll be passed an instance of Person into our step definition automatically.

Custom parameters allow you to bring your domain model - the names of the classes and objects in your solution - and your domain language - the words you use in your scenarios and step definitions - closer together.

🎬 0.1: 04.01.animation.mp4

In the previous chapter, we talked about the importance of having readable scenarios, and you learned some new skills with Cucumber Expressions to help you achieve that goal. Those skills will give you the confidence to write scenarios exactly the way you want, knowing you’ll be able to match the Gherkin steps easily from your step definition code.

We emphasise readability because from our experience, writing Gherkin scenarios is a software design activity. Cucumber was created to bridge the communication gap between business domain experts and development teams. When you collaborate with domain experts to describe behaviour in Gherkin, you’re expressing the group’s shared understanding of the problem you need to solve. The words you use in your scenarios can have a deep impact on the way the software is designed, as we’ll see in later chapters.

The more fluent you become in writing Gherkin, the more useful a tool it becomes to help you facilitate this communication. Keeping your scenarios readable means you can get feedback at any time about whether you’re building the right thing. Over time, your features become living documentation about your system. We can’t emphasize enough how important it is to see your scenarios as more than just tests.

Maintaining a living document works both ways: the scenarios will guide your solution design, but you may also have to update your Gherkin to reflect the things you learn as you build the solution. This dance back and forth between features and solution code is an important part of BDD.

In this chapter, we’ll learn about feature descriptions, the Background keyword, and about keeping scenarios and code up-to-date with your current understanding of the project.

First, let’s catch up with what’s been happening on the Shouty project.

While we were away, the developers of Shouty have been busy working on the code. Let’s have a look at what they’ve been up to.

🎬 1: bundle exec cucumber We’ll start out by running Cucumber.

Great! It looks like both these scenarios are working now - both the different messages that Sean shouts are being heard by Lucy.

🎬 2: open stepdef file Let’s dig into the code and see how these steps have been automated.

In the step definition layer, we can see that a new class has been defined, the Network.🎬 3 We’re creating an instance of the network here. Then we pass that network instance to each of the Person instances we create here.🎬 4 So both instances of Person depend on the same instance of network. The Network is what allows people to send messages to one another.

There are also a couple of new unit test classes in the spec directory,🎬 5 one for the Network class,🎬 6 and another one for the Person class.🎬 7

Unit tests are fine-grained tests that define the precise behaviour of each of those classes. We’ll talk more about this in a future lesson, but feel free to have a poke around in there in the meantime.

The rspec command will run the unit tests. 🎬 8: run rspec

🎬 9: open the feature file

The first thing I notice coming back to the code is that the feature file is still talking about the distance between Lucy and Sean, but we haven’t actually implemented any behaviour around that yet.

This happens to us all the time - we have an idea for a new feature, but then we find the problem is too complex to solve all at once, so we break it down into simpler steps. If we’re not careful, little bits of that original idea can be left around like clutter, in the scenarios and in the code. That clutter can get in the way, especially if plans change.

We’re definitely going to develop this behaviour, but we’ve decided to defer it to our next iteration. Our current solution is just focussed on broadcasting messages between the people on the network.

Let’s clean up the feature to reflect that current understanding.

After the feature keyword, we have space in a Gherkin document to write any arbitrary text that we like.🎬 1: feature file We call this the feature’s description. This is a great place to write up any notes or other details that can’t easily be expressed in examples. You might have links to wiki pages or issue trackers, or to wireframes. You can put anything you like in here, as long as you don’t start a line with a Gherkin keyword, like “Rule:” or “Scenario:”.

In this case, we can add a high level description of the Shouty application.🎬 2 Because Shouty doesn’t yet filter by proximity, we can also write a todo list here so it’s clear that we do intend to get to that soon.🎬 3

Changing the description doesn’t change anything about how Cucumber will run this feature. It just helps the human beings reading this document to understand more about the system you’re building.

Our two scenarios are examples of how Shouty can broadcast a shout to other users. This is one of the main business rules, which we can document using the Rules keyword.🎬 4: add Rules keyword and indent scenarios We’ll learn more about this in a later chapter.

🎬 5: shows 'Lucy is 15 metres from Sean' step definition The step “Given Lucy is 15 metres from Sean” is misleading, since the distance between the two people is not yet relevant in our current model.

The step definition calls the moveTo method on Person, 🎬 6

🎬 7: shows move_to method in Person class but the moveTo method doesn’t actually do anything.

🎬 8 Let’s simplify this code to do just what it needs to do right now, and no more. We can start from the scenario by changing this single step to express what’s actually going on.🎬 9 We’ll work on one scenario at a time, and update the other one once we’re happy with this one.

Now the scenario names make sense, and we have two steps, each creating a person. Notice we’re starting to reveal some more of our domain language here: we’ve introduced the words Person and name. Person is already a part of our domain language, so it’s nice to have that revealed in the language of the scenario. Name may well become an attribute of our person soon, so it’s also useful to have that surfaced so we can get feedback about it from the team.

One thing we’ve lost by doing this is the idea that, eventually, the two people will need to be close to each other for the message to be transmitted. We definitely wouldn’t remove detail like that unilaterally, without discussing it with the other people who were involved in writing and reviewing this scenario.

🎬 10: create new Rule and writes out two new empty scenarios for in / out of range In this case, as well as adding it to the TODO list above, we’ve decided to document the range rule, and write a couple of new empty scenarios to remind us to implement that behaviour later.

🎬 11: bundle exec cucumber Let’s press on. We can run Cucumber to generate new step definition snippets for the new steps and paste them into our steps file. 🎬 12

In the next lesson we’ll look at a couple of ways that we can implement these new step definitions.

🎬 1: broken implementation We now have two step definitions to implement, and that presents us with a bit of a problem. We need the same instance of Network available in both. We could just assume that the Lucy step will always run first and create it there, but that seems fragile. If someone wrote a new scenario that didn’t create people in the right order, they’d end up with no Network instance, and weird bugs. We want our steps to be as independent as possible, so they can be easily composed into new scenarios.

The most straightforward way to create this network instance in Ruby is to use a hook.

We need an instance of Network in every scenario, so we can declare a Before Hook that creates one before each scenario starts, like this:🎬 2 Now we can use that Network instance as we create Lucy and Sean in these two new steps.🎬 3

🎬 4: bundle exec cucumber It should be working again now. Let’s run Cucumber to check.

🎬 5: Copy and paste in feature file Good. Let’s do the same with the other scenario.

🎬 6: bundle exec cucumber

🎬 7: Delete lucy_is_located_m_from_Sean Now we can remove this old step definition. We know we’ll need something like this in the future when we implement the proximity rule, but we don’t want to second-guess what that code will look like, so let’s clean it out for now.

🎬 8: bundle exec cucumber

🎬 9: delete moveTo Now we have one last bit of dead code left, the move_to method on Person. Let’s clean that up too.

🎬 10: bundle exec cucumber

🎬 1: Freeze of code from end of lesson 4

OK, so we’ve cleaned things up a bit, to bring the scenarios, the code and our current understanding of the problem all into sync. What’s nice to see is how well those new steps that create Lucy and Sean match the code inside the step definition.

When step definitions have to make a big leap to translate between our plain-language description of the domain in the Gherkin scenario, and the code, that’s usually a sign that something is wrong. We like to see step definitions that are only one or two lines long, because that usually indicates our scenarios are doing a good job of reflecting the domain model in the code, and vice-versa.

One problem that we still have with these scenarios is that we’re very fixed to only being able to use these two characters, Lucy and Sean. If we want to introduce anyone else into the scenario, we’re going to be creating quite a lot of duplicate code. In fact, the two steps for creating Lucy and Sean are almost identical, apart from those instance variables.

On a real project we wouldn’t bother about such a tiny amount of duplication at this early stage, but this isn’t a real project! Let’s play with the skills we learned in the last chapter to make a single step definition that can create Lucy or Sean.

The first problem we’ll need to tackle is these hard-coded instance variable names.🎬 2

We can use a Hash to store all the people involved in the scenario.

Let’s try replacing Lucy first.

🎬 3: Edit Stepdefs.java, adding private instance field people, creating in @Before hook, and using for Lucy throughout We’ll start by creating a new Hash in the before hook, like this.

Now we can store Lucy in the hash. We’ll use her name as the key, hard-coding it for now.🎬 4

Finally, where we check Lucy’s messages heard here in the assertion, we need to fetch her out of the hash. 🎬 5

🎬 6: bundle exec cucumber

With that little refactoring done, we can now try and make this first step generic for any name.

Using your new found Cucumber expression skills from the last chapter, you’ll know that if we replace the word Lucy here with a 'word' expression,🎬 7 we’ll have the name passed into our step definition as an argument, here.🎬 8 Now we can use that as the key in the hash.🎬 9

🎬 10: bundle exec cucumber FAILS If we try and run Cucumber now, we get an error about an ambiguous match. Our generic step definition is now matching the step “a person named Sean”, but so is the original one. In bigger projects, this can be a real issue, so this warning is important.

Let’s remove the old step definition,🎬 11 and fetch Sean from the hash here where he shouts his message.🎬 12

🎬 13: bundle exec cucumber

Great, we’re green again.

🎬 1: Feature file Let’s switch back to the feature to show you one more technique for improving the readability of your scenarios.

When we have common context steps - the Givens - in all the scenarios in our feature, it can sometimes be useful to get those out of the way.

🎬 2: move Given steps into background We can literally move them into the background, using a background keyword, like this:

🎬 3: bundle exec cucumber As far as Cucumber is concerned, these scenarios haven’t changed. It will still create both Lucy and Sean as the first things it does when running each of these scenarios.

🎬 4: Feature file, showing Background and shortened scenarios But from a readability point of view, we can now see more clearly what’s important and interesting about these two scenarios - in this case, the message being shouted.

Notice we just went straight into When steps in our scenarios.🎬 5 That’s absolutely fine. We still have a context for the scenario, but we’ve chosen to push it off into the background.

Again, it’s debatable whether we’d bother to use a Background to do this on a real project, but this at least illustrates the technique. We rarely use Backgrounds in our projects, because although they can improve readability by removing the duplication of repeated contexts, they also harm readability by requiring people to read the Background in conjunction with each Scenario.

To maintain trust in the BDD process, it’s important to keep your features fresh. Even when you drive the development from BDD scenarios, you’ll still learn lessons from the implementation that might need to be fed back into your Gherkin documentation.

In this case, we discovered that we could find a smaller slice of this story, and defer the business rule about proximity until our next iteration. Splitting stories like this is a powerful agile technique, and one that BDD can help you to master. Now we have a clean codebase and a suite of scenarios that reflects the current state of the system’s development.

We’re ready to start the next iteration.

Welcome back to Cucumber School.

🎬 1: feature file from end of Ch 4

Last time we worked on cleaning up the Shouty features to keep them in sync with the current status of the project. We stripped the scenarios back to only specify the behaviour of passing messages between people. We made it clear that the proximity rule had not yet been implemented.

You’ll already remember from the Cucumber expressions chapter how important it is to be expressive in your scenarios, and keep them readable. In this chapter we’re going to learn some new tricks with Gherkin that will give you even more flexibility about how you write scenarios.

Once again the Shouty developers — have been hard at work implementing that proximity rule. Let’s have a look at how they got on. 🎬 2: Show chapter 5 initial checkin feature file

Right, so those two scenarios we just left as placeholders: the one where the listener is within range,🎬 3: show in feature file and the one where the listener is out of range 🎬 4: show in feature file are passing. 🎬 5: Show output from Cucumber showing the in-range/out-of-range results Fantastic! If we look at our step definitions, we can see how they have been implemented. 🎬 6: show the in-range/out-of-range scenarios in the step definitions

Let’s review the changes to the feature file in more detail.

We now have four scenarios:🎬 7 our original two from the last time we looked at the code,🎬 8 and the two placeholders we wrote as reminders.🎬 9

We used the second scenario - Listener hears a different message 🎬 10: Highlight second scenario - to triangulate and force us to replace the hard-coded message output with a proper implementation. Now we have a domain model that uses a variable for the message, there’s an insignificant chance of this behaviour regressing, so we can safely remove the second scenario. 🎬 11: removes second scenario: Listener hears a different message

Keeping excess scenarios is wasteful: they clutter up your feature files, distracting your readers. When you run your features as tests, excess scenarios make them take longer to run than necessary. The one where a "listener hears a "message" is a perfectly good way of checking that the message has been sent correctly.

The first scenario has changed since we last looked at it 🎬 1: hear_shout.feature - it now specifies the range of a shout and the location of Sean and Lucy.🎬 2: Highlight the first three line of the first scenario This scenario exists to illustrate that a listener hears the message exactly as the shouter shouted it. All the additional details are incidental and make the scenario harder to read.

🎬 3: Edit context of first scenario Let’s ensure that this scenario includes only essential information for the reader and remove all references to location and range.

🎬 4: Add Network creation We’ll need to make changes to the step definitions to make sure that a Network class is always created - which we can do using an instance variable.

🎬 5: Highlight DEFAULT_RANGE We’ve defaulted the range to 100. If a scenario needs to document specific range, that can still be done by explicitly including a "Given the range is …​" step.

We’ll also need to add a step definition that can create a person without the scenario needing to specify where they are located.🎬 6: Create new step definition The step definition gives each person 🎬 7 created this way a default location of 0.🎬 8

🎬 9: run Cucumber Let’s run Cucumber to check we haven’t broken anything…​ and we’re good!

🎬 10 Looking at the two new scenarios - Listener is within range 🎬 11 & Listener is out of range 🎬 12 - we can see that they also contain incidental details. Since their purpose is to illustrate the "Shouts should only be heard if listener is within range" rule, there’s no need to actually document the content of the shout. 🎬 13: "highlight free bagels at seans

🎬 14: Delete message text Let’s remove the details that aren’t relevant to the range rule.

🎬 15: Add new step definition Next we add a step definition that allows Sean to shout, without needing us to specify the exact message.

🎬 16 One that allows us to check that Lucy has heard exactly one shout - because she’s in range of the shouter.

🎬 17 And one that allows us to check that Larry hasn’t heard any messages at all - because he’s out-of-range.

🎬 18: Run Cucumber And finally run Cucumber - and we’re still green.

🎬 19: Show hear_shout.feature That’s better. We’ve removed inessential details, so that each scenario contains only the information needed to illustrate its business rule.

The scenarios would still run green if we removed the steps that set the range of a shout 🎬 20: Highlight in last two scenarios🎬 20b , because the range already has a default value. We’re not going to, because since those scenarios are illustrating the rule that deals with the range of a shout, it’s an essential part of context for anyone reading them.

A happy side-effect is that, in order to set the range from our scenario, we’ve had to make it a configurable property of the system 🎬 21: highlight Network constructor. So if our business stakeholders ever change their minds about the range, we won’t have to go hunting around in the code for where we’d hard-coded it.

Let’s look at the two scenarios that illustrate the rule about range again 🎬 1: show the range rule & scenarios. Notice how the steps that create the Sean,🎬 2 Lucy,🎬 3 and Larry 🎬 4 are very similar.

When we see steps like this, Gherkin’s Given When Then syntax starts to feel a bit clunky. Imagine if we could just write out a table, like this:

🎬 5: feature file

Well, we’re in luck. You can!

Gherkin has a special syntax called Data Tables, that allows you to specify tabular data for a step, using pipe characters to mark the boundary between cells.🎬 6: highlight data table

🎬 7: run cucumber🎬 8: copy snippet, paste into steps.rb

As you can see, the step definition implicitly takes a single argument 🎬 9: highlight stepdef parameters, which as this comment explains is a DataTable.🎬 10: highlight comment This object has a rich API for using the tabular data.

At its most basic, the table is just a two-dimensional array. So, Lucy’s location can be accessed 🎬 11: Print out a single cell value by getting the value from array cell (2, 1)

🎬 12: run Cucumber, highlight 'Lucy’s location'

You can also turn the table into an array of hashes 🎬 13: Print out data table, where the first row is used for the hash keys,🎬 14: split IntelliJ screen horizontally, showing feature file at top and stepdefs below. Highlight first row and each following row is used for the hash values.🎬 15: highlight second and third rows

🎬 16: run Cucumber, highlight data table output

Now we can easily iterate 🎬 17: write the loop over these hashes and turn them into instances of Person: 🎬 18

🎬 19: run cucumber — all green

With that done, we can update the other scenario 🎬 20: update other scenario …​

Now we can check that everything is still green. 🎬 21

🎬 23: run cucumber

Cucumber strips all the white space surrounding each cell 🎬 24: show lining up of pipe characters, so we can have a nice neat table in the Gherkin but still get clean values in the step definition underneath.

Notice we’ve still had to convert the location from a string to an integer 🎬 25: Conversion in step def, because Cucumber can’t know that’s the type of value in our table.

That looks much nicer - 🎬 26: hear_shout.feature data tables people positioned using a table in the feature file and 🎬 27: people_are_located_at() really clean code that creates and positions people according to the data.

🎬 1: open feature file

The way that we’ve specified this data is OK,

but your product owner would prefer you to express it like this instead: 🎬 2: edit data table to have headings in the first column

It’s always good to please the product owner, but you’re worried how we’ll handle it in our step definition? Fear not. Cucumber has you covered.

If you call the transpose method on the table 🎬 3: stepdef, Cucumber will turn each row into a column before passing it to the step definition.

🎬 4: run cucumber

🎬 5: show data tables in feature file Data tables are very useful for setting up data in Given steps, but you can also use them for specifying outcomes.

One rule that we’ve been implying but have never actually explored with an example is that people can hear more than one shout. So far we’ve only specified a single message, so let’s try writing a scenario where Sean shouts more than once: 🎬 6: write two-shouts scenario

See how natural it is to use a Data Table here? We also haven’t used any column headers in this case, since the data is all in a single column anyway.

So how do we implement this step definition? Well, the DataTable has a really handy method called diff that we can use to compare two Data Tables. diff will pass if the tables are the same, and fail if they’re different.

Let’s run Cucumber to generate the new step definition 🎬 7: run Cucumber and paste it into our step definitions file 🎬 8: paste snippet 🎬 9

We’ll need the actual messages that Lucy’s heard to be stored in an object that looks like a DataTable, so we can compare it to the ones we expect.

An array of arrays will do 🎬 10: write code to create list-of-list-of-strings, so we can just iterate over Lucy’s messages and create a new single-item array for each row.🎬 11

Now we can pass that array to the diff method on the table of expected messages passed in from the Gherkin. 🎬 12: write code to call diff

🎬 13: runs cucumber

Oops! It looks like we made a typo in our scenario. We should have included exclamation marks on the expected messages. 🎬 14 Well, at least this gives you a chance to see the nice diff output from Cucumber when the tables are different. We see the expected values prefixed with a minus, and the actual values prefixed with a plus.

Let’s fix just one of these 🎬 15: add exclamation mark so you can see how the diff output changes.

🎬 16: run cucumber The matching bagels! line no longer has a minus, and for the mismatched row, the expected value still has a minus, and the actual value has a plus.

Let’s fix this last typo 🎬 17: add another exclamation mark, and we should be green again.

🎬 18: run cucumber

Great.

When writing scenarios, occasionally we want to use a really long piece of data. 🎬 1: Show feature file

For example, let’s introduce a new rule about the maximum length of a message 🎬 2: New rule

…​and add a scenario to illustrate it 🎬 3: New scenario, making the string just over the boundary of the rule:

That’s pretty ugly isn’t it!

Still, we’ll press on and get it to green, then we’ll show you how to clean it up.

🎬 4: run Cucumber Our existing step definition handles that ugly step with the long message just fine, but the last outcome step is undefined. We could either add a new step definition, or parameterise "Larry should not hear a shout". Let’s modify the existing step definition 🎬 5: Modify stepdef

🎬 6: run cucumber

OK, so we have a failing acceptance test.🎬 7 Let’s dive down into our solution and implement this new rule. It seems like the Network should be responsible for implementing this rule, so let’s go to its unit tests 🎬 8: show NetworkTest As we explain in more detail in the next lesson, we start by adding a new example to specify this extra responsibility. 🎬 9: start creating new unit test

We’ll create a 181-character message like this 🎬 10: finish implementing unit test and then assert that the message should not be heard when it’s broadcast.🎬 11

Let’s run that test 🎬 12: run Cucumber - show the unit test results🎬 13. Good, it fails. Lucy’s still getting the message at the moment. Now how are we going to implement this?

It looks like we’re already implementing the proximity rule here 🎬 14: Network proximity logic in the broadcast method. Let’s add another if statement here about the message length. 🎬 15: add message length logic

Run the unit test again… and it’s passing.🎬 16

And cucumber is green as well 🎬 17: run cucumber

Great.

The code here has got a little bit messy and hard to read. 🎬 18: show the modified logic in the Network class One very basic move we could make to improve it would be to just extract a couple of temporary variables, one for the range rule 🎬 19: extract range temporary variable and one for the length rule. 🎬 20: extract length temporary variable

That’s better. This code could be improved even further of course, but at least we haven’t made it any worse.

Let’s just run the tests to check. 🎬 21: run cucumber Great - everything’s still green.

Now we have everything passing again, we can tidy up the Gherkin to use a new piece of syntax we’ve been wanting to tell you about: a DocString. 🎬 22: show message length scenario in feature file

DocStrings allow you to specify a text argument for a step that spans over multiple lines. We could change our step to look like this instead: 🎬 23: convert message to DocString

Now the scenario is much more readable. 🎬 24: show existing stepdef code

🎬 25: show existing stepdef code We have to add a new step definition too 🎬 26: sean_shouts_the_following_message. It doesn’t need a parameter in the Cucumber Expression 🎬 27 — the DocString gets passed as a string argument to the step definition automatically.🎬 28

Now we can fill out the rest of our new step definition. 🎬 29

Let’s check that we’re still green 🎬 30: run cucumber🎬 31 — and we are!

We don’t use DocStrings very often - having such a lot of data in a test can often make it quite brittle. But when you do need it, it’s useful to know about.

🎬 1: original animation

You might have noticed that we’ve followed a pattern when we added behaviour to the system during this episode.

First we expressed the behaviour we wanted in a Gherkin scenario, wired up the step definitions, then ran Cucumber to watch it fail.

Then, we found the first class in our domain model that needed to change in order to support that new behaviour. In this case, the Network class. We used a unit test to describe how we wanted instances of that class to behave. Then we ran the unit test and watched it fail.

We focused in and made changes to the class until its unit tests were passing. When the unit tests were passing, we then made some minor changes to clean up the code and make it more readable. This is the basic test-driven-development cycle: red, green, clean.

The technical name for this last clean-up step is refactoring. Refactoring is an ugly name for an extremely valuable activity: improving the design of existing code without changing its behaviour. You can think about it like cleaning up and washing the dishes after you’ve prepared a meal: basic housekeeping. But imagine the state of your kitchen if you never made time to do the dishes.

Go on, imagine it for a second.

Yuck!

Well, that’s how many, many codebase end up. The good thing about taking this course is that we’re teaching you how to write solid automated tests, and the good thing about having solid automated tests is you can refactor with confidence, knowing that if you accidentally change the system’s behaviour, your tests will tell you.

Once we’re done refactoring, what do we do next? Run Cucumber, of course! In this case, our scenario was passing with a single trip round the inner TDD loop, but sometimes you can spend several hours working through all the unit tests you need to get a single scenario to green.

Once the acceptance test is passing, we figure out the next most valuable scenario on our todo list, and start the whole thing all over again!

Together, these two loops make the BDD cycle. The outer loop, which starts with an acceptance test, keeps us focussed on what the business needs us to do next. The inner loop, where we continuously test, implement then refactor small units of code, is where decide how we’ll implement that behaviour.

Both of these levels of feedback are important. It’s sometimes said that your acceptance tests ensure you’re building the right thing, and your unit tests ensure you’re building the thing right.

That’s all for this chapter of Cucumber School. See you next time!

🎬 1: Animation Hello, and welcome back to Cucumber School.

Last time we learned about two very different kinds of loops. First, we used DataTables to loop over data in your scenarios.

Then we learned about TDD cycles. We saw how the outer loop of TDD helps you to build the right thing while the inner loop helps you build the thing right.

In this lesson, we’re going to teach you all about how to configure Cucumber.

🎬 2: Scroll through shout.feature, end by showing scenario 'Message too long'

When we start working on a new scenario we often take a dive down to the inner TDD loop where we use a unit testing tool to drive out new classes or modify the behaviour of existing ones. When our unit tests are green and the new code is implemented we return to the Cucumber scenarios to verify whether we have made overall progress or not.

🎬 3: Scroll through shout.feature, end by showing scenario 'Message too long'

If we have lots of Cucumber scenarios, it can be distracting to run all of them each time we do this. We often want to focus on a single scenario - or perhaps just a couple - to get feedback on what we’re currently working on.

There are several ways to do this in Cucumber - and your IDE may offer other options. We’ll start by showing some basic filtering on the command line, before showing you some alternatives.

Probably the easiest way to filter is to tell Cucumber to run only a scenario with a particular name.

🎬 4: type bundle exec command in console, show output and highlight that it has only run the one scenario 'Message too long' 🎬 5 We can pass arguments to Cucumber using the --name option, which tells Cucumber to only run scenarios with a name matching "Message is too long".

The value of the --name option is actually a regular expression, so you can use your imagination here to run more than one scenario. Let’s use it to run all scenarios with the text "range" in their name. 🎬 6: type bundle exec command in console, show output and highlight that it has run the two scenarios containing the word 'range'🎬 7

We can also use the abbreviated form of --name, -n 🎬 8

We can accomplish the same thing by adding some configuration on the cucumber.yml file, but we’ll talk about that at the end of the lesson.

Another way to tell Cucumber to run a specific scenario is to specify the line number of the scenario within a feature file. The 'Message too long' scenario starts on line 44 in the feature file. 🎬 9: in feature file show that 'Message too long' starts on line 44

We can use that line number when we run Cucumber. 🎬 10: use line number on comand line 🎬 11 🎬 12

You can even specify multiple line numbers for each file. Let’s run 'Two shouts' as well. [🎬 13: in feature file, show 'Two shouts' starts on line 33

Let’s add that line number when we run Cucumber. 🎬 14: type bundle exec command in console, show output and highlight that it has run two scenarios - 'Two shouts' and 'Message too long'🎬 15

You can list several files and lines together like this if you have a specific set of scenarios you want to run.

The examples that you’ve just seen set a Ruby property on the command line. If you’re working in an IDE this is less than ideal, but fortunately there are other ways to achieve exactly the same outcome.

Let’s look at using a property file to set the system properties. Create a property file called cucumber.yml in the root path of the project 🎬 16 and add default: --name range 🎬 17

When we run Cucumber, it picks up the property setting from the file and only runs the "range" scenarios. 🎬 18: type bundle exec cucumber in console, show output and highlight that it has run the two scenarios containing the word 'range'🎬 19

The benefit of a properties file is that it gets checked in with your code, which means that any settings can be shared by all team members.

In this lesson you’ve learnt how to filter the set of scenarios to run using scenario names and line numbers from the command line and using property files.

🎬 1 In the previous lesson, we modified Cucumber’s behavior using scenario names and line numbers. In this lesson I’m going to show you how to filter scenarios using tags.

First, let’s delete the contents of the cucumber.yml file. 🎬 2. We’ll leave default --quiet for now. We’ll explain what’s it about in a later lesson.

If we run Cucumber, it will run all scenarios. 🎬 3: run Cucumber

We’ll put a focus tag right here, above this scenario. 🎬 4: add a @focus tag to the 'Listener is out of range' scenario Tags start with an at-sign and are case sensitive.

Now, after re-creating the `cucumber.yml`file, let’s add a tag expression to the default key, which Cucumber will use to filter the scenarios run 🎬 5

Now Cucumber will run only the scenarios tagged with focus - there should be only one…​ 🎬 6: run Cucumber, then highlight that only 'Listener is out of range' scenario was run🎬 7

Yep.

It’s entirely up to you what you name your tags. When we’re working on a particular area of the application it is common to use a temporary tag like this - we’ll remove it before we check our code into source control.

Tags can be used for other purposes as well. If you have lots of scenarios it can be time-consuming to run them all every time. For example, you can tag a few of them with @smoke and run only those before you check in code to source control. 🎬 8: tag first and third scenario with @smoke🎬 9

Running just the smoke tests will give you a certain level of confidence that nothing is broken without having to run them all. 🎬 10: run Cucumber, then highlight that only first and third scenarios were run🎬 11

If you’re running Cucumber on a Continuous Integration Server as well, you could run all the scenarios there, detecting any regressions you might have missed by only running the smoke tests.

Tags give you a way to organise your scenarios that cut across feature files. You can think of them like sticky labels you might put into a book to mark interesting pages that you want to refer back to.

Some teams also use tags to reference external documents, for example, tickets in an issue tracker or planning tool. Let’s pretend we are using an issue tracker while working on Shouty and all the behaviour we built so far is related to the issue number 11. We could tag the whole feature file with this single line at the top. 🎬 12: tag feature with @SHOUTY-11 All the scenarios within that file now inherit that tag, so if we change the tag expression in cucumber.yml 🎬 13: edit YML file,

Cucumber will run all the scenarios in the feature file. 🎬 14: run Cucumber, then show that all scenarios were run🎬 15

You can use more complex tag expressions to select the scenarios you want to run. For example, you could use a tag expression to exclude all the scenarios tagged as @slow. 🎬 16: tag last two scenarios with @slow Then rewrite the tag expression in cucumber.yml using the not keyword 🎬 17: "modify Cucumber.yml Now when you run Cucumber, the "@slow" scenarios won’t be run. 🎬 18: run Cucumber, then show that the slow scenarios were not run

Note the need to add quotes around "not @slow".🎬 19 If they’re not added, running bundle exec cucumber will result in an error.

You can read about how to build more complicated tag expressions on the Cucumber website 🎬 20: open the link and show the Cucumber website

There’s one more thing to learn about tags. They can be combined with hooks, so that you can be selective about which hooks to run when. We’ll cover that in a future chapter.

Cucumber is first and foremost a tool that facilitates a common understanding between people on a project. Imagine our customers were cats. We could write our features in English, but the cats would obviously not understand that, so I’ll show you how to write a scenario in LOLCAT instead.

You can get a list of all the supported languages with --i18n-languages. 🎬 1

Cucumber supports over 70 different languages, thanks to contributions from people from all over the world.

To see the translation of the Gherkin keywords for a particular language, just use the '--i18n' option with the language code. 🎬 2

Now create a new feature file in the features directory called cat.feature 🎬 3

The first line tells Cucumber which language the feature file is written in. 🎬 4

Cucumber then expects the Gherkin keywords to be in LOLCAT 🎬 5

The step is undefined, but we can quickly generate it by running Cucumber 🎬 6: run new scenario Cucumber has generated a step definition.

We could copy and use this step definition in our steps.rb file the same way we do with regular English. But let’s remove the cat.feature file and continue.🎬 7

Notice that when we run Cucumber, the scenarios run in the order that the occur in the feature file 🎬 8: expand/highlight the test results That’s fine, but there’s a chance that since they always run in the same order we might accidentally make one scenario dependent on some other scenario.

Each scenario should be isolated - it’s result should not depend on the outcome of any other scenario. To help you catch any dependencies between your scenarios, Cucumber can be told to run your scenarios in a random order.

To do this, we can use the random flag in the profile file. 🎬 9

Now when we run Cucumber, the scenarios are run in a random order 🎬 10: run Cucumber & show new order of scenario execution. Now there’s almost no chance of a dependency between scenarios slipping through without being noticed.

🎬 11: show 'List configuration options' section of A full list of Cucumber’s configuration properties can be found by passing the --help flag on the command line. 🎬 12: highlight top of output The same can be accomblished by using the abbreviated version -h 🎬 13

That’s quite a lot to digest, but to make Cucumber really useful to your team, it’s good to spend some time learning the details of how to configure it. In this lesson, we showcased two of Cucumber’s configuration options and you learned how to write your scenarios in different spoken languages.

Cucumber can report results in other formats, which can be useful for generating reports. Let’s take a closer look at some of the formatter plugins that ship with Cucumber - starting with the HTML formatter.

When we use the html formatter we need to specify the filename that the report should be written to using the --out flag.🎬 1 Otherwise it will be written directly to the console.

Let’s take a look at the html that has been generated. 🎬 2: Open target/my-report in the browser As you can see, this generates a nicely structured HTML page that details what scenarios were run and whether the system behaved as expected.

🎬 3: run Cucumber Next, we’ll use the JSON formatter. We can use the abbreviated version of our --format and --out flags -f and -o.🎬 4🎬 5🎬 6

The JSON report outputs the results in a single file. 🎬 7: open the json file You can write your own script or program to post-process this file to generate your own report. Additionally, many continuous integration servers understand the json format and can turn it into a nicely formatted report.

There is also a progress formatter,🎬 8: run Cucumber which just prints out a single character for each step.🎬 9

🎬 10: run cucumber with multiple formatters We can specify multiple formatters like this.

The one without a path appended will be written to the console. If you ask multiple formatters to output to the console, only the last one mentioned will actually produce any output.

🎬 1: show HTML output In the last lesson we saw the output generated by the HTML plugin. This is a great way for your business colleagues and customers to engage with the development of the product. Since the scenarios are written in business language, they act as documentation that everyone interested in the product can understand. And, because the results are colour-coded green (if the system behaves as expected) or red (if it doesn’t) everyone can see what behaviour has been implemented.

The challenge is making sure that this documentation is easily available. Feature files are usually checked into source control along with the source code, which isn’t a great way of making it accessible to less technical team members. The HTML output can be shared, but it needs to be stored somewhere that everyone has access to - such as on your intranet or wiki. That’s something that your team has to configure themselves.

Since Cucumber 6.0.0 there has been a new feature that allows you to automatically publish the results online to a free service called Cucumber Reports. 🎬 2: go to reports.cucumber.io

Ensure that you’re using Cucumber 6.0.0 or later 🎬 3: show package-lock.json file

and remove publish-quiet from cucumber.yml. 🎬 4: cucumber.js

Now when we run Cucumber, 🎬 5: npm test it helpfully prints out a banner telling you how to publish your results to Cucumber Reports 🎬 6: highlight banner.

Let’s follow the instructions in the banner and add --publish to cucumber.js 🎬 7.

Now we can run Cucumber again and we get a different banner output 🎬 8. The unique URL in this banner is the address of your published report 🎬 9: highlight URL.

🎬 10: follow URL Open the URL and you’ll find your report published in the same format as the HTML plugin. Now you can share the report just by sharing the URL. You also get some extra information about the run that generated the report. If you publish reports from a recognised CI server, then extra information is gathered.

You might have noticed the warning in the banner that says the report will "self-destruct". 🎬 12: highlight warning To prevent a report from being deleted, it has to be associated with an authenticated account.

Follow the link in the report to authenticate your account 🎬 13🎬 14 You can then retrieve your Cucumber Reports publish token 🎬 15. Reports associated with a publish token will be kept until explicitly deleted.

🎬 16: publish quiet During development you probably won’t want to publish a report after every build…​ and you might prefer not to see the banner output telling you about Cucumber Reports. Let’s fix this in cucumber.js by replacing --publish with --publish-quiet:

🎬 17: no banner Now when we run Cucumber, no report is published and no banner advertising Cucumber Reports is output.

Cucumber Reports is under active development, so expect to see many more useful features coming in the coming months.

Once again, while we were away, the developers of Shouty have been busy. A new hot-shot ninja rock-star subcontractor, Stevie, has built a new feature called premium accounts. We don’t know much about it yet but, our tester Tamsin has reported a bug from their manual exploratory testing, and it’s up to us tofix it.

🎬 1: Opens the premium accounts feature file

This seems like a good time to ask our domain experts for clarification about this behaviour. Ideally a three amigos meeting would have done this already, but things don’t always go according to the script. Let’s pay a visit to our product owner.

Paula the product owner tells us the rules are as follows: 🎬 2: Writes the rules up in the feature file

We’ve just scribbled these down in the feature description for now, but later, once we’ve teased this scenario apart, we’ll be able to use the Rule keyword as we showed you in chapter 4.

OK, well that helps us a great deal, but this scenario is still doing a poor job of illustrating those rules. Let’s take a moment to understand why.

🎬 3: 07.03.animation.mp4

It’s all about the details.

When you’re first exploring a new domain problem, details like the exact messages people have shouted are a great way to shine light into the dark corners of your ignorance. They bring examples to life by making them vivid and real. This encourages what we call divergent thinking, which helps you discover even more examples as you explore the behaviour you need to provide.

In BDD, we call this deliberate discovery, when we try to explore the problem domain as thoroughly as we can. Details are good here.

At some point, however, we need to write a computer program. When that time comes, we need to switch to convergent thinking and try to distill down all that detail into something that clearly communicates the essence of the behaviour. Now, too much detail can be distracting, or even misleading to our future readers. We call these incidental details.

Being able to distill down the essence of a scenario with too much detail is a skill you’ll find yourself practicing time and time again as a BDD practitioner, since we almost always deliberately start with too much detail, then want to refine it afterwards as it becomes more clear which details are relevant, and which are incidental.

Seb Rose came up with a brilliant acronym to help you remember six heuristics or guidelines to think about when reviewing the quality of your scenarios: BRIEF.

"B" is for Business language: The words used in a scenario should be drawn from the business domain, otherwise you will not be able to engage your business colleagues painlessly. The language you use should use terms that business team members understand unambiguously.

"R" is for Real data: When you’re first discussing the details of a story, your examples should use concrete, real data. This helps bring the scenarios to life, and expose boundary conditions and underlying assumptions early in the development process. When writing scenarios, we should also use real data whenever this helps reveal intention and make them move vivid.

"I" is for Intention revealing: Scenarios should describe the intent of what the actors in the scenario are trying to achieve, rather than describing the mechanics of how they will achieve it. We should start by giving the scenario an intention revealing name, and then follow through by ensuring that every line in the scenario describes intent, not mechanics.

"E" is for Essential: The purpose of a scenario is to illustrate how a rule should behave. Any parts of a scenario that don’t directly contribute to this purpose are incidental and should be removed. If they are important to the system, then they will be covered in other scenarios that illustrate other rules. Additionally, any scenarios that do not add to the reader’s understanding of the expected behaviour have no place in the documentation.

"F" is for Focused: Most scenarios should be focused on illustrating a single rule.

You might have noticed we said "six heuristics" but we only gave you five. That’s because the word Brief itself is the sixth guideline. We suggest you try to restrict most of your scenarios to five lines or fewer. This makes them easier to read, much easier to reason about, and helps avoid that temptation to test multiple rules, or add incidental details.

Let’s try to distill the essence of this scenario by removing the incidental details.

🎬 1: Opens the premium account feature

We can start with this step, When Sean shouts "Come and buy a coffee". 🎬 2

From what what we know about the rules, what’s important here is that the shout contains the word “buy”. So let’s write that:

🎬 3: Changes step to When Sean shouts a message containing the word

Better. We still have a little bit of detail - the word buy - but that’s quite important, in fact it helps to illustrate our business rule.

We’ll need a new step definition for this, of course.

🎬 4: Runs cucumber --tags ~@todo, copies / pastes step def snippet into steps file.

🎬 5 We can just copy the code for shouting a message from this step down here for now. We will deal with this duplication, but later.

🎬 6: Copies code from step def below, then adds code above to create a test message containing the given word.

Let’s run Cucumber to check we haven’t made any mistakes…

🎬 7: Runs cucumber --tags ~@todo.

All green. Good.

Now we can use that same step everywhere else in the scenario, too, where that is the real intent of the step. 🎬 8: Changes the other two steps that mention the word “buy”. Runs cucumber --tags ~@todo. All green.

And run cucumber again. 🎬 9

Now things are really getting clearer.

There are still a couple of problems with this scenario.🎬 1 One is the name of the scenario. It really doesn’t tell us anything at all.

A great way to name your scenarios is to think about how they named episodes of the TV sitcom series, Friends. Remember? They were all called something like The one where Ross is fine or The one where Phoebe gets married.

Instead of expressing the outcome, we find it’s best to keep that out of our scenario, and just descrbe the context and the action.

So if this scenario were an epside of Friends, what would it be called? This is the one where… well.. the one where Sean shouts some over-long messages and some containing the word “buy”.

🎬 2: Updates the name of the scenario

Well, this is better than what we had before, but it’s s quite a complicated name isn’t it? Maybe this scenario is doing too much!

…​and that’s the second problem.

It’s trying to test both business rules at once.

🎬 07.closing.common.animation.mp4

Well that’s been quite a session. We came in to fix one bug, and ended up having to fix our feature file first. We’re still not done with that, either. By pushing the incidental details down out of the scenario into the step definitions, we’ve made a mess of duplication in the step definitions. There’s a neat fix for that, but we’ll have to save that for next time.

Let’s reflect on what we’ve learned.

When scenarios are very heavy in detail, they can be confusing to read. We call these incidental details when they are just noise that detracts from communicating the essence of the scenario.

Scenarios that are heavy in detail are sometimes said to be written in an imperative style. They contain lots of “how”, and not much “what”. We often use this style when we’re working on a brand new domain problem and are still grasping for an understanding. We just want to write something down.

As your confidence in your domain knowledge improves, you’d expect to feel comfortable removing some of these details. Scenarios with more abstract steps like this are said to be written in a declarative style.

Using a more declarative style might mean you’ll need to find names for things, like the way we had to name an over-long message. This discovery of your ubiquitous domain language is a great side-effect of distilling the essence of your scenarios. Now you have a bigger vocabulary that you can use all the way down through your code, and in your future conversations, too.

One down-side, as you’ve seen, of pushing the “how” down from your scenarios into the step definitions is that the step definition code becomes more complex. Some teams reject this, and prefer to use a simple vocabulary of step definitions, leaving more detail in their scenarios. There are no right and wrong answers here, but if you have sufficient competence with code, you’ll easily be able to handle that extra bit of complexity and keep readability top of your priorities.

That’s what we’ll work on next time. Bye for now!

🎬 2: BDD circles diagram In terms of the three practices we introduced in Chapter 1 - Discovery, Formulation and Automation - what went wrong with the Premium Accounts feature?

Thinking about it, we can see that the development team 🎬 3: BDD circles diagram - (1) pointing to Automation jumped straight into Automation - writing the implementation of the feature. They did the bare minimum of 🎬 4: BDD circles diagram - (2) pointing to Formulation Formulation - just enough to automate a test for the feature, but really we did a lot of the Formulation later on as we cleaned it up. Finally, much of the 🎬 5: BDD circles diagram - (3) pointing to Discovery Discovery happened at the end once Tamsin had a chance to test the feature by hand.

🎬 6: BDD circles diagram - draw a red 'X' over the three arrows So in essence, they did everything backwards.

🎬 7: Animation ending with 'Deliberate Discovery' In software projects, it’s often the unknown unknowns that can make the biggest difference between success and failure. In BDD, we always try to assume we’re ignorant of some important information and try to deliberately discover those unknown unknowns as early as possible, so they don’t surprise us later on.

A team that invests just a little bit extra in Discovery, before they write any code, saves themselves a huge amount of wasted time further down the line.

🎬 8: Animation introducing three people, showing them talking In lesson 1, we showed you an example of the Three Amigos - Tester, Developer and Product owner - having a conversation about a new user story.

Nobody likes long meetings, so we’ve developed a simple framework for this conversation that keeps it quick and effective. We call this 🎬 9: Example Mapping Example Mapping.

🎬 10: diagram: User Story → Example Mapping

An Example Mapping session takes a single User Story as input, and aims to produce four outputs:

We capture these, as we talk, using index cards, or another virtual equivalent.

Working with these simple artefacts rather than trying to go straight to formulating Gherkin, allows us to keep the conversation at the right level - seeing the whole picture of the user story without getting lost in details.

🎬 1: index cards and pens

We first developed example mapping in face-to-face meeting using a simple a multi-colour pack of index cards and some pens. For teams that are working remotely, there are many virtual equivalents of that nowadays.

We use the four different coloured cards to represent the four main kinds of information that arise in the conversation.

We can start with the easy stuff: Take a yellow card and write down the name of the story.

🎬 2: write 'premium accounts' on a yellow card

Now, do we already know any rules or acceptance criteria about this story?

Write each rule down on a blue card:

🎬 3: write two rules on blue cards

They look pretty straightforward, but let’s explore them a bit by coming up with some examples.

🎬 4: Show male character, with text appearing on their left

Darren the developer comes up with a simple scenario to check he understands the basics of the “buy” rule: "I start with 10 credits, I shout buy my muffins and then I want to buy some socks, then I have zero credits. Correct?"

"Yes", says Paula. 🎬 5: Write up Darren’s example on a green card

Darren writes this example up on a green card, and places it underneath the rule that it illustrates.

🎬 6: Show female character Tammy the tester chimes in: "How about the one where you shout a word that contains buy, like buyer for example? 🎬 7: Show female character with text appearing If you were to shout I need a buyer for my house. Would that lose credits too?"

🎬 8: Show second female character in foreground Paula thinks about it for a minute, and 🎬 9: Second female character opens arms and smiles decides that no, only the whole word buy counts. They’ve discovered a new rule! 🎬 10: Modify text on blue card, add new green card They write that up on the rule card, and place the example card underneath it.

🎬 11: Show male character in foreground, talking Darren asks: "How do the users get these credits? Are we building that functionality as part of this story too?"

🎬 12: Show female character in foreground, talking Paula tells him that’s part of another story, and they can assume the user can already purchase credits. They write that down as a rule too.

🎬 13: Write 'assumption: credit purchase has already been implemented'

This isn’t a behaviour rule - it’s a rule about the scope of the story. It’s still useful to write it down since we’ve agreed on it. But it won’t need any examples. We could also have chosen to use a red card her to write down our assumption.

🎬 14: Female character speaking, blank background; writing appears Still focussed on the “buy” rule, Tammy asks: "What if they run out of credit? Say you start with 10 credits and shout buy three times. What’s the outcome?"

Paula looks puzzled. "I don’t know". She says. I’ll need to give that some thought.

🎬 15: Write out red card: 'What should happen when one runs out of credits? Darren takes a red card and writes this up as a question.

🎬 16: More (empty) cards appearing They apply the same technique to the other rule about long messages, and pretty soon the table is covered in cards, reflecting the rules, examples and questions that have come up in their conversation. Now they have a picture in front of them that reflects back what they know, and still don’t know, about this story.