This is the first in a series of short posts explaining what Cucumber is and isn’t. Used correctly, Cucumber can be a tool for great good. Used poorly, it’s an invitation to disaster. KNOW YOUR TOOLS.

I’ve been cuking for nearly as long as cuking has been possible. I’ve made every mistake there is to make. I’ve recently given a talk on Cucumber, and will be giving another one along somewhat similar lines at LA Ruby Conf with co-conspirator Robbie Clutton.

Your Feature and your UI are two different things

One of the quickest ways to go wrong with Cucumber is to attempt to describe your user interface in words. I’ve seen a lot of features that read something like this:

Scenario: Send a valid tweet
  When I click inside the tweet text input
  Then it should expand to a text area
  And I should see photo, location, and tweet buttons
  And the tweet button should be disabled and greyed out
  When I type the following text into the text area: "short tweet"
  Then I should see the "Tweet" button enable itself
  When I click the tweet button
  Then a new div should appear in my timeline letting me know a new tweet is available
  When I click on the anchor tag within that div
  Then I should see the timeline expand with my new tweet automatically without a page refresh

Words can’t do a UX justice. They are far too inefficient. And worse, any attempt to describe a user interface with words will inevitably obscure the underlying state machine of your feature. It will hide behind the laborious language of the user interface. This scenario should have been written like this:

Scenario: Send a valid tweet
  Given I have authenticated
  When I submit a tweet 140 characters or less
  Then my followers should receive that tweet
  And I should see my tweet in my timeline

This feature captures the actual underlying state machine behind sending a tweet:

1. You have to be logged in
2. Your tweet has to be less than 140 characters
3. Anyone following you will automatically receive your tweet
4. You will see your tweet posted in your timeline

It also discusses the feature in the language of the application’s domain, not in the language of a particular user interface.

So what do you do about the UI? Turns out, you can create *visuals* to describe your User Interface. A picture truly is worth a thousand words. There’s lots of great ways to work out the visual UX of your application, including:

• Designers
• Pen and Paper
• Whiteboards
• Storyboarding paper prototypes with your iPhone
• Balsamiq
• Photoshop

Cucumber is a tool for working out the state machine that is your application, and living with the complexity that the state machine entails. It’s a way to structure the conversation you have to have with your product owner. It’s a way to capture all of the concrete examples and edge cases behind a feature.

It’s not a replacement for a designer. It’s not a replacement for wireframes. It’s not a replacement for story boards. It’s a tool for collaboration; if a feature file isn’t the result of a conversation, you are doing it wrong.