Layers of abstraction: writing great cucumber code

September 2011

I blogged about Gojko’s thoughts on layers of abstraction a week or so ago, discussing three different ways we can think about the behaviour of any system. These way are: the business rules, the workflow of that system, and the specific activity the user is undertaking.

Today I want to think about how we can leverage these insights to help us write really good cucumber features and step code.

I used to write terrible features

Do these look familiar?

Feature: Paul pays employees
  In order to retain staff
  As Paul the Payroll Manager I want to pay my staff

Scenario:
  Given an admin user called "Paul" with a password "password"
  And a user called "Bob"
  And "Bob" is an employee
  And "Bob" gets paid "$2,000" a month
  When I visit the homepage
  And I click on "Log in"
  And I fill in "username" with "Paul"
  And I fill in "password" with "password"
  And I click "Log in"
  And I click "Payroll"
  And I click "Bob"
  And I click "Pay"
  And I enter "$2,000"
  And I click "Pay"
  Then I should see "Bob has been paid"

We’ve all written features like this in the past: there’s plenty of guidance out there these days to help you write better features than this. However, rather than just accept “best practices” at face value, let’s take a look under the hood and work out why this is better.

Variance revisited

Last time I discussed this topic, I mentioned the key differentiator was variance. Business rules are unlikely to change significantly unless the company decides to pivot: this is more likely in a startup but still less likely overall. The workflow is normally fairly static, but the activity the user follows changes regularly.

Co-incidentally, there are three levels of behaviour implementation that we write when we work with Cucumber:

The feature files. Ideally there are written in collaboration with the customer and are written out before coding begins.
The step definitions. We implement each step of our feature with ruby code as we are writing the feature, sometimes reworking existing steps to be more powerful (often at our peril).
Support code. Cucumber executes our steps inside a ‘world object’, which we can easily extend through the adding of modules and methods.

Each of these implementation levels is also differentiated in terms of variance:

The feature files are the most difficult to change, as this ideally requires a conversation with the customer, and any wording changes have a knock on effect on step definitions.
Step definitions can be tricky to change, especially if they are used by multiple feature files. Their implementation is closely tied to the regular expression they match, which can make them difficult to understand if highly reused: one case where Don’t Repeat Yourself can fall down quickly.
Support code is easy to change as it’s plain ruby and as such very malleable: we can easily refactor and be careful with our naming to tease out duplication.

Where to put the code?

If it’s easy to change support code, then it follows that we should put our higest varying code there: namely the code which describes specific activity. Normally only programmers are interested in this code and it’s easy enough to find and understand if the support methods are well-named.

The workflow code lives best in individual steps which aren’t often reused and which have simple regular expressions. The people who are interested in this area are normally designers and User Experience people, who should be able to read well-named ruby code at a pinch and therefore can understand what’s going on.

The code that’s least likely to change (the business rules) can safely live in the feature files with impunity, where it can be discussed with product owners. The product owner is most interested in the rules of their system: they’re only moderately interested in the workflow and usually aren’t too opiniated about the specific activities. That’s partly why we struggle to write features with our clients: if we’re trying to discuss activity specifics like in the example feature above, we’re probably nailing down details too early and bore our product owner to tears. It’s hard enough for a programmer to read these sorts of features: how can we expect anyone else to understand them?

An example

Given this, how would I refactor the feature above to improve things? After deleting web_steps.rb, I would rewrite the feature with my customer citing the business rule, rather than any specific workflow:

Feature: Paul pays employees
  In order to retain staff
  As Paul the Payroll Manager I want to pay my staff

@paul_signed_in
Scenario:
  Given an employee called "Bob"
  Then I should be able to pay "Bob" his salary

My step definitions would look something like this:

Given /^an employee called "([^"]+)"$/ do |employee_name|
  create_employee(employee_name)
end

Then /^I should be able to pay "([^"]+)" his salary$/ do |employee_name|
  pay_salary_to(employee_)
end

And the support code might look roughly like this:

Before("paul_signed_in") do
  paul = create_employee("Paul")
  paul.assign_role("payroll")
  sign_in_as(paul)
end

def create_employee(name)
  Employee.create!(:name => name, :username => name,
    :password => "password")
end

def pay_salary_to(name)
  payee = Employee.find_by_name(name)
  visit payroll_employee_path(payee)
  fill_ :salary, :with => payee.salary
  click_button "Pay"
end

You’re also free not to test the UI if you’d prefer not to in your support code. However, as we’ve given ourselves the ability to remove duplication, it’s easy to change the code when the UI changes. So far I’ve not found UI brittleness to be too much of an issue.

In conclusion

These are rules of thumb, but they can be very helpful in keeping the rate of development up as our codebase expands. One change that I’ve made recently to my own practice is to be more aggressive at pushing activity code down into support code, and it’s really helped to keep feature code flexible and easy to change.

Many people have given up on Cucumber, citing long build times and the brittleness of the test code as primary reasons. Obie Fernandez recently blogged about finding “high-ceremony” development too much work in a startup. I think that’s a real shame: it’s a fantastic way to drill down to specific behaviour and ensure you’re only building what you need. If you think about the behaviour of your system correctly, aggressively remove duplication in all your code (including test code), and only test code you own then you shouldn’t be burdening yourself with too much of an overhead.

Have you given up using Cucumber? Or if you use it, is this the way you do it or do you have a better method?

BlueSky

Extreme YAGNI: How BDD nails your prototyping stage

May 2016

prototyping

Sometimes people don’t see the value in the BDD process. They contend that the BDD ceremonies are a waste of time, and get in the way of delivering real features to customers. Others cannot see how to apply BDD to their project, as no-one knowns exactly what the project will look like yet. As they’re only in the prototyping stage, by the time a feature file is written and made executable, it’s already out of date.

I don’t agree with this. If our process is set up right, we can prototype using just as effectively and retain the collaboration benefits that BDD gives us.

You Ain’t Gonna Need It

One of the biggest wins that Test-driven Development (TDD) gives us is the principle of YAGNI - “You Ain’t Gonna Need It”. It’s very tempting when writing code to go off on a tangent and produce a beautiful structured work of art that has zero practical use. TDD stops us doing this by forcing us only to write code that a test requires. Even some experts who don’t practice or encourage TDD often espouse the power of writing the calling code first in order to achieve much the same effect.

BDD gives us the same YAGNI win: but at a level higher than TDD. With the BDD cycle we’re adding thin slices of customer observable behaviour to our systems. If we can only write the code thats directly used by the business, then in theory we should be cutting down on wasteful development time.

However, there’s a snag here. if we’re prototyping, we don’t know whether this feature will make it into the final product. We still need to give feedback to our product team, so we need to build something. If the feature is complex, it might take a while to build it, and the feature might never get used. Why bother going through the process of specifying the feature using BDD and Cucumber features?

Happily, we can take YAGNI a level further to help us out.

Extreme YAGNI

Often in TDD, and especially when teaching it, I will encourage people to take shortcuts that might seem silly in their production code. For example, when writing a simple supermarket checkout class in Javascript, we might start with a test like this:

    var checkout = new Checkout();
    expect(checkout.total()).toEqual(0);

Our test defines our supermarket checkout to have a total of zero on creation. One simple way to make this work would be to define the following class:

    var Checkout = function() {
      this.total = function() {
        return 0;
      };
    }

You might think that’s cheating, and many people define a member variable for total, set it to 0 in the constructor, and miss this step out entirely. There is however an important principle at stake here. The code we have does exactly what the test requires it too. We may not need a local variable to store total at all.

Here’s the secret: we can practice this “extreme YAGNI” at the level of our features, too. If there’s a quick way to make our feature files work, then there’s nothing to stop us taking as many shortcuts as we can to get things working quickly.

For example, if we’re testing the user interface of our system via Cucumber features, one fast way to ensure things are working is to hard code the values in the user interface and not implement the back end behaviour too early. Why not make key pages static in your application, or hard code a few cases so your business gets the rough idea?

Again, you might think that’s cheating, but your features pass, so you’ve delivered what’s been asked for. You’ve spent the time thrashing out the story in a 3 amigos meeting, so you gain the benefits of deliberately discovering your software. You’re giving your colleagues real insight to guide the next set of stories, rather than vague guessing up front. Our UX and design colleagues now have important feedback through a working deployed system very quickly, and quick feedback through working software is a core component of the agile manifesto.

By putting off implementing the whole feature until later, we can use BDD to help us navigate the “chaotic” Cynefin space rather than just the “complicated” space. This in theory makes BDD twice as useful to our business.

Fast, fluid BDD

This all assumes that we have a fast, fluid BDD process, with close collaboration built in. If it takes a week to coordinate everyone for the next feature file, then the temptation is to have a long meeting and go through too many features, without a chance to pause, prototype, deliver and learn from working software. Maybe it’s time to re-organise those desks and sit all the members of your team together, or clean up your remote working practices, or block out time each day for 3 amigo sessions. You’ll be suprised how much small changes speed your team up.

Why you can scale agile with the right attitudes

December 2014

The more I work with teams, the more I think agile at any scale lives or dies based on attitudes of people in the organisation, rather than the scale at which you are attempting to do it.

Software development is hard, and it’s harder the greater the scale as Rachel’s post eloquently argues. However, I don’t think the scale is always the limiting factor here.

I’ve seen small teams with such a lack of trust that they burden themselves with suffocating process, and larger organisations with so much trust that they’re able to operate at the speed of organisations a quarter of their size.

As organisations get bigger, the trust required gets greater. If the trust exists, teams are able to remain independent and don’t get burdened with process.

If you need to work at one thing to make your large organisation more agile, work on building trust between teams, and between teams and management. Try small wins, quick feedback, and constant celebration. Decentralise decisions, give people ownership in their areas, and act like they’re as good as you know they are.

If middle and upper management could be persuaded to give up control and provide leadership instead, your scale matters much less than you might think.

Why BDD works solo, and why that matters for everyone

August 2014

“The monotony and solitude of a quiet life stimulates the creative mind.”

– Albert Einstein

It’s possible to play chess and many other games completely solo, without anyone else to play against.

solo chess

Incredibly, our minds are able to take on the role of both players in a competitive match. Our brains allow us to place ourselves in the opposing player’s shoes. Even more impressively, we are able to hide certain information from our own decision making process – such as what we’re planning to do next turn. We can analyse this incomplete set of information and play a move based solely on that, even if it’s sub-optimal.

BDD can be done solo

Using Behaviour-driven Development (BDD) on our own is much the same as playing a game against ourselves.

Instead of playing the opposing role, we take on the role of the stakeholder. We put ourselves in the shoes of the person paying for or commissioning the project. Because the BDD practice of writing gherkin-style features forces us to think in plain English, we jettison the role of programmer for a moment, and drift in the non-technical solution thought-space.

Why is this important? It’s a valuable exercise for a couple of reasons:

We gain a fresh perspective on what we are doing. By taking our heads out of the code and putting ourselves into the role of the stakeholder, we are able to see the wood for the trees and get perspective on the code we’re writing right now. It might be interesting code to write, but does it matter?
We gain a fresh perspective on the stresses of others. Every developer should take the opportunity to be a stakeholder once in a while. It’s very helpful to see what life it like on the other side of the estimation table. If all the members on a team are able empathise with the constraints and pressures our colleagues from different disciplines have, our team will run much more smoothly.

BDD solo is why BDD matters in the first place

Sometimes we confuse the concepts behind BDD with the tools used to practice BDD, like 3 amigo meetings, story breakdown and Cucumber.

BDD isn’t about the tools we use, it’s about the communication in the team. It’s about having the right conversations at the right times, hammering things out together, airing and refining thoughts and ideas, beating out ambiguity and forging common goals. This is why it matters.

If it was just about the tools, BDD would have been lost in the noise years ago, and BDD solo would be an expensive overhead. Why add another layer of tool complexity if it’s just us?

However, because BDD is about the concepts, not the tools, BDD works just fine solo: the process of deliberately stepping outside our developer role and thinking through our project from a product perspective gains us insight and understanding. This works no matter what tools, languages, frameworks or practices we may prefer.

When we’re solo, we dispense with a lot of the tools we don’t need. We don’t need to schedule a 3 amigo meeting with ourselves, for example. We’re left with a very pure form of BDD, set free from the needed constraints of multi-person teams.

Then we can begin to understand which of the common practices of BDD are only there to work around problems and can be discarded as needed, and which are truly foundational.

Try it out

Try using BDD on a personal project. Play the product owner, and write some Gherkin-style features. Pretend you can’t code. Really think about your problem without thinking about exactly how you’re going to solve it.

Whilst doing this, reflect on what practices you really need, and which you don’t. Which tools are less useful on your own? Which are more useful?

If you feel we’re just wasting time, I’d challenge us to think about what that’s telling us about our own ‘standard’ agile practice. How much of it is truly making us more agile, and how much of it is simply getting in the way?

How not to check in temporary code

July 2014

We’ve all done it.

We were skimming through a set of changes before checking in our code, trying to get the branch pushed up to the build server just before lunch. We’d forgotten that before we went home last night, we added a couple of lines of code to a method which sets up a debug state for testing. Easy to miss; and miss it we did. The change goes up, the build breaks, and we’re left feeling embarrassed.

How do we ensure we don’t check in temporary code? One way to do so is to utilise that old refactoring staple, Extract Method, along with the power of good naming.

Pull out temporary code into a method

Here’s some temporary code currently nestled inside the Card Pirates method for starting a new game. It fixes the position and the cards for the first two players, so I can easily jump to and test the combat user interface.

    def start_new_game
      @state = GameState.new_game(@queue)

      attacker = state.players.current_player
      defender = state.players.next_player

      attacker.x = 3
      attacker.y = 3
      attacker.hand = Card.hydrate ["10_of_england", "4_of_spain", "3_of_france"]

      defender.x = 4
      defender.y = 3
      defender.hand = Card.hydrate ["8_of_england", "3_of_spain"]
      state.map.square(4, 3).face_down_cards = []

      init_services(@state.current_player.name)

      @queue << Command.new(:start_game)
      @queue << Command.new(:start_new_player_turn, @state.current_player.name)
      show_board(@state.current_player.name)
    end

Can you spot where the temporary code stops, and the ‘real code’ starts? It’s difficult, isn’t it? I thought so too, so I extracted the temporary code into a method, and gave it a very obvious name:

    def test_the_combat_dont_check_in(state)
      attacker = state.players.current_player
      defender = state.players.next_player

      attacker.x = 3
      attacker.y = 3
      attacker.hand = Card.hydrate ["10_of_england", "4_of_spain", "3_of_france"]

      defender.x = 4
      defender.y = 3
      defender.hand = Card.hydrate ["8_of_england", "3_of_spain"]
      state.map.square(4, 3).face_down_cards = []
    end

    def start_new_game
      @state = GameState.new_game(@queue)

      test_the_combat_dont_check_in(@state)

      init_services(@state.current_player.name)

      @queue << Command.new(:start_game)
      @queue << Command.new(:start_new_player_turn, @state.current_player.name)
      show_board(@state.current_player.name)
    end

This has a number of advantages:

It’s quick to do. It only takes a minute to make a change like this, and saves you a lot of headaches later.
It’s easy to spot in a diff. It’s much harder to get out all the code unless it’s clearly encapsulated like this.
It’s easy to spot for someone else. If instead of going on a lunch break you were cycling home for the day, a co-worker would probably be able to spot and fix this before you got back online.
It might be further refactored later. These kind of ‘put the system in a certain state’ methods can actually be useful later - we might be able to use this for a tutorial mode, for example. Temporary code often ends up being much less temporary that we originally envisage.

I’ve found that small refactorings like this often save me lots of time later. How do you stop yourself checking in the wrong code?

How to decide whether a tool is right for you

May 2014

We are only at the beginning of our journey in building software. Our discipline is barely a few decades old. We have only a very little experience in how to correctly write code and a limited range of tools and skills to do it with. We should be actively looking for new tools, not wasting our time either promoting our toolset exclusively or disparaging the toolsets of others.

Tools are tools

Test-driven development has been one of those tools that has proved useful for many people over a number of years. Do I use it? Yes, much of the time.

Using a refactoring IDE has also proved useful to many people over a number of years, especially in certain languages. Do I use one? No. Does that mean it’s not a useful tool to others? No, of course not.

The ability to decouple code to promote changeability is also a great tool to have in your toolbox. Do I try and do this? Yes, wherever I can, and I’m always trying to get better at it.

There are many more. The insight as to when to refactor, not just how, is an incredibly valuable skill to have. The understanding that all code is built for someone and we should ensure we talk to them about what they want is powerful. Being able to check into source control without touching the network is a real speed boost, and gives me a detailed history of progress.

The recent TDD storm

So why do we get so hung up on one particular tool? When something works for us, we’re compelled to proclaim it’s the One True Way and that it’ll work for every problem and solve every headache. This is a grevious error, but in avoiding it, we can make the opposite one: when we find a tool’s limitations, we discard it completely and move on, proclaiming it useless for all.

DHH has a point. Don’t listen to the people who say there’s only one way to do a job, and that we should use any tool for everything.

Gary Bernhardt has a point. Test speeds do matter - the faster the better. Fast tests are a powerful tool.

Uncle Bob has a point. It’s not just about fast tests: separating concerns in order to promote changeability in code is a useful skill to learn.

Tom Stuart has a point. TDD is a useful tool because it gives you another client for your code, encouraging us to think harder about what it’s doing.

Seb Rose has a point. We need to learn how to use TDD (or indeed any tool) well before giving up on it.

Cory House has a point. People display their own biases in their opinions and we should learn from them all.

How to decide whether a software tool is right for you

It doesn’t matter whether it’s TDD, Vim, Git, Refactoring, OO, Functional programming, JavaScript, RubyMotion, etc. Follow the following advice repeatedly, substituting your own values:

If you haven’t tried tool X, give it a go. Many have found it helpful in areas Y and Z. Some have also found it applicable in areas A and B, but your mileage may vary. Some don’t get on with it, and a few hate it and say no-one should use it. Learn it properly before making any final decision about its usefulness to yourself and others. This will take <an amount of days/months/years> to do. Continue using it as long as it’s helpful to you.

There are as yet very few absolutes with software tools - we’re still way too primitive in our discipline for many of those. Let’s learn how to use as many tools and skills as possible, and use the right ones for the job. Let’s not decry the tools, skills and techniques of others if they are useful to them: let’s instead spend our energy actively seeking new skills and tools to further our discipline.