Google has plenty of special purpose languages, but this is the first general purpose language to come out of Mountain View. That fact alone makes it quite interesting. Add to it that some of the original C and UNIX people are involved, and it becomes something that requires investigation.

What's it for?

Go is a systems programming language. Think of it as a modern C. It's meant for the same types of programming: operating systems, compilers, infrastructure pieces.

What's it all about?

To summarize the main golang.org page, Go is: simple, fast, safe, concurrent, open source, and fun.

What's so different about it?

Go is an object-oriented language, but not in the style that most programmers these days think of OO. Go doesn't have implementation inheritance (more on that later). Also, you don't define methods inside a class as in many OO languages. Instead, you add methods to types in a way somewhat reminiscent of CLOS . For example:

func (file *File) Read(b []byte) (number_bytes_read int, err os.Error) { ... }
  if file == nil {
    return -1, os.EINVAL
  }
  r, e := syscall.Read(file.fd, b);
  if e != 0 {
    err = os.Errno(e);
  }
  return int(r), err
}

Here we have a function Read that's being attached to the type *File. Read takes a single parameter, b, which is an array of byte and it returns an int named number_bytes_read and an Error named err. There are three things to note here. Read, is (1) being attached to an existing type (a pointer type at that), and (2) returns multiple values which (3) are named. Even if the return value names aren't used, they are superb for documenting what the returned values mean.

Points of Note

Fast compilation

Go compiles fast. Really fast. This means no long waits for builds. More importantly, it means a tighter test-code development cycle.

Less typing... and less typing

Here's the basic way to declare a variable (a string in this case):


var s string = "";


If the type can unambiguously be inferred, you can do:


var s = "";


and using the initializing declaration operator, you can simplify even more:


s := "";


I say shiny: this is pretty sweet. Minimal boilerplate and type inference.

Arrays and Slices

Arrays are, of course, built-in to the syntax. Arrays are fixed size linear collections of data. They work pretty much as expected except that they don't support the pointer arithmetic tricks that C programmers take for granted. So, you get an actual pointer to an array, not just a pointer to something that happens to be the first thing in the array.

Slices are the idiomatic way to work with sequences of data in Go. They wrap arrays to give a more powerful way to work. Slices are too big of a topic to explore in this post, but basically they provide a dynamic window onto an array.

Arrays have a size as an integral aspect of the type, thus [3]int is a different type than [5]int. Slices have a size as part of their data.

You create a slice of an array by specifying the initial and one past the final index. For example:

a := [4]int{1, 2, 3, 4};
s := a[1:3];

s[0] == 2
s[1] == 3

Here s has a size of 2 (3 - 1) and type []int.

Here's a function that takes a slice as its parameter:

func F(buf []byte)

You can tell this is a slice because there is no size inside the brackets.You could call the above function with an explicit slice:

var a [5]byte;
F(a[2:4]);

but you can also implicitly pass a slice that covers a complete array:

var a [5]byte;
F(a);

Strings and Maps are built-in

Something that's nice to see is that strings are built into the language and standard library as in C (but unlike C++). The proliferation of string libraries in C++ caused great confusion and frustration in C++'s early days.

What's even nicer to see is that hashes are built-in. Having the basic and extremely useful types built-in to the language make it possibly to optimize them quite aggressively. This way. programmers don't have to worry about choosing a slow string or hash library.

Maps are very flexible, here's an example from Effective Go:

var timeZone = map[string] int {
  "UTC":  0*60*60,
  "EST": -5*60*60,
  "CST": -6*60*60,
  "MST": -7*60*60,
  "PST": -8*60*60,
}

func offset(tz string) int {
  if seconds, ok := timeZone[tz]; ok {
    return seconds
  }
  log.Stderr("unknown time zone", tz);
  return 0;
}

Note the multiple return values where the second is an indicator as to whether a valid value was found.

Interfaces

Interfaces are just a collection of function signatures. Here's an example of interface use taken from the IO library:

type Reader interface {
  Read(p []byte) (n int, err os.Error);>
}

type Writer interface {
  Write(p []byte) (n int, err os.Error);
}

This is nothing too earth shattering if you're familiar with Java. If you're used to Ruby, this is something a little different: actually having to codify the protocols to which your objects conform (see Jim Weirich's RubyConf 2009 talk for a discussion of this).

Making the connection between interfaces and the types that implement them is just the opposite. It's implicit—as it is in Ruby et.al.— not explicit, as it is in Java. For example here is something that can be used whenever a Reader is expected:

type limitedReader struct {
  r Reader;
  n int64;
}

func (l *limitedReader) Read(p []byte) (n int, err os.Error) { ... }

This example also shows declaring a variable (a struct member in this case) of an interface type.

One nice thing about the way interfaces are done in Go is that if you define an interface that declares some methods of an existing type, you have implicitly performed an Extract Interface refactoring. None of the types implementing those methods have to be touched: they can now be implicitly and automatically used wherever you use the new interface.

One nice feature is the ability to make composite interfaces:

type ReadSeeker interface {
  Reader;
  Seeker;
}

Here, the ReadSeeker interface encompasses everything in both the Reader and Seeker interfaces. Anything that implements the methods declared in Reader and Seeker can be used wherever Reader, Seeker, or ReadSeeker is used.

No Implementation Inheritance

It is the lack of implementation inheritance that seems odd. Most of us are used to considering it as a necessary part of an OO language. In his 1996 talk "What is Object-Oriented Programming?" Bjarne Stroustrup (creator of C++) went so far as to say:

Consider a language having some form of method lookup without having an inheritance mechanism. Could that language be said to support object-oriented programming? I think not.

It's interesting to note, however, that Alan Kay (arguably the father and namer of OO) didn't originally consider inheritance necessary as part of the language (in "The Early History of Smalltalk"):

I just decided to leave inheritance out as a feature in Smalltalk-72, knowing that we could simulate it back using Smalltalk's LISPlike flexibility. The biggest contributor to these AI ideas was Larry Tesler who used what is now called "slot inheritance" extensively in his various versions of early desktop publishing systems. Nowadays, this would be called a "delegation-style" inheritance scheme.

Inheritance was jumped on when OO hit the scene back in the 80s. We saw it used far too much and too freely. Over the years the thinking shifted to a more sensible approach of composition rather than inheritance. This is what Kay was referring to back in '72.

Garbage Collection

Go has a rudimentary mark-sweep garbage collector, but there are plans to improve that. One of the boons of having garbage collection is that you completely sidestep entire classes of memory related bugs. It also means you don't have to write the code to deal with memory management. In the context of Go being a language that embraces parallelism, garbage collection means that you can avoid worrying about cleaning up allocated memory.

Concurrency

In today's world of multi-core processors, concurrent programming is becoming increasingly relevant. The Go authors recognized this and designed Go for use in writing concurrent programs. Go embodies a different philosophy of concurrency than most systems languages:

Do not communicate by sharing memory; instead, share memory by communicating.

Go offers two primitives to accomplish this sharing by communication: goroutines and channels.

Goroutines

Goroutines are functions executing in parallel with other goroutines. The Go runtime manages parallelizing all of the goroutines using operating system primitives. They are light-weight and easy to use.

go doSomething(); // Do something, but do not wait for it to complete

You can even pass an anonymous function literal:

go func() {
  time.Sleep(5);
  fmt.Prinln("Hello World");
}();

Channels

With goroutines, executing functions in parallel is easy. However we still need a mechanism for communicating between them. That's what channels are for. Channels provide a synchronized, type-safe way to communicate values from one goroutine to another.

ch := make(chan int); // unbuffered channel of integers

go func() {
  result := 0;
  for i := 0; i < 1000000; i++ {
    result += i;
  }
  ch <- result;
}();

/* Do something else for a while */

sum := <-ch;
fmt.Println(sum);

The above example shows how channels can be used to communicate between two goroutines, and it also shows how they can be synchronized. The binary send operation will block until another goroutine receives the value, and the unary receive operation will block until another goroutine sends a value. So a channel can be used as a simple way to synchronize a goroutine.

ch := make(chan bool);
go func() {
  /* do some stuff */
  ch <- true;
}();
<-ch; // strobe the channel to synchronize

What's not there?

Some things are absent from Go (at least for now), including generics, exceptions, and assertions. Generics and exceptions might be added in the future, when an acceptably clean and efficient design is devised. Keep in mind that Go is meant for system programming. Efficiency is important, and language features such as generics and exceptions have non-trivial runtime performance implications. Go is not a kitchen sink language—it is designed for a fairly specific use.

Conclusions

Go is extremely easy to dive into. There are a minimal number of fundamental language concepts and the syntax is clean and designed to be clear and unambiguous.

Go is still experimental and still a little rough around the edges. For example, if a function has a return value, and it returns from every branch of execution, it will still complain if it doesn't return from the end of the function.

That said, Go allows you to do Pascal style return values where you give the result a name, assign to it, and use it in computation. However, you still have to put the return keyword at the end.

The only typing is duck typing. To Rubyists, this is a great thing.

As Carl Lerche comments, "It's not production quality yet, but there's enough that it's interesting to explore."

In retrospect, I don't really like the term Best Practice—the value of most practices is very much context dependent. That said, some ways of doing things are just generally better than others, so here are some of those good things to keep in mind. I'll comment briefly on each one.

1. Feature Files Should Actually be Features, Not Entire Portions of an App

One feature per well named file, please, and keep the features focused.

2. Avoid Inconsistencies with Domain Language

You'll get the most benefit out of using Cucumber when your customers are involved. To that end, make sure you use their domain language when you write stories. The best course of action is to have them involved in writing the stories.

3. Organize Your Features and Scenarios with the Same Thought You Give to Organizing Your Code

One useful way to organize things is by how fast they run. Use 2-3 levels of granularity for this:

• Fast: scenarios that run very fast, e.g. under 1/10 of a second
• Slow: scenarios that are slower but not painfully so, maybe under one second each
• Glacial: scenarios that take a really long time to run

You can do this separation several different ways (and even some combination):

• Put them in separate features
• Put them in separate subdirectories
• Tag them

4. Use Tags

Tags are a great way to organize your features and scenarios in non functional ways. You could use @small, @medium and @large, or maybe @hare, @tortoise, and @sloth. Using tags let you keep a feature's scenarios together structurally, but run them separately. It also makes it easy to move features/scenarios between groups, and to have a given feature's scenarios split between groups.

The advantage of separating them this way is that you can selectively run scenarios at different times and/or frequencies, i.e. run faster scenarios more often, or run really big/slow scenarios overnight on a schedule.

Tagging has uses beyond separating scenarios into groups based on how fast they are:

• When they should be run: on @checkin, @hourly, @daily
• What external dependencies they have: @local, @database, @network
• Level: @functional, @system, @smoke
• Etc.

5. Use Rake Tasks to Run Features

This provides a consistent environment for running features: this way each run uses the same set of options and parameters. This goes a long way toward maintaining deterministic results.

Another benefit is that this makes for easy integration with continuous integration tools. There is a single point of entry into the spec run, with all options/parameters encapsulated.

6. Don't Get Carried Away with Backgrounds (Stick to Givens)

The larger the background, the greater the load of understanding for each scenario. Scenarios that contain all the details are self-contained and as such, can be more understandable at a glance.

7. Make Scenarios Independent and Deterministic

There shouldn't be any sort of coupling between scenarios. The main source of such coupling is state that persists between scenarios. This can be accidental, or worse, by design. For example one scenario could step through adding a record to a database, and subsequent scenarios depend on the existence of that record.

This may work, but will create a problem if the order in which scenarios run changes, or they are run in parallel. Scenarios need to be completely independent.

Each time a scenario runs, it should run the same, giving identical results. The purpose of a scenario is to describe how your system works. If you don't have confidence that this is always the case, then it isn't doing its job. If you have non-deterministic scenarios, find out why and fix them.

8. Write Scenarios for the Non-Happy-Path Cases As Well

Happy path tests are easy; edge cases and failure scenarios take more thought and work. Here's where having some good (and yet pathological) testers on the team can reap rewards.

Use rcov with your full Cucumber runs to find holes in coverage. Definitely check out Aslak Hellesoy's thoughts on the matter for more details.

9. Be DRY: Refactor and Reuse Step Definitions

Especially look for the opportunity to make reusable step definitions that are not feature specific. As a project proceeds, you should be accumulating a library of step definitions. Ideally, you will end up with step definitions that can be used across projects.

10. Use a Library (Such as Chronic) for Parsing Time in Your Step Definitions

This allows you to use time in scenarios in a natural way. This is especially useful for relative times.

Background:
  Given a user signs up for a 30 day account

Scenario: access before expiry
  When they login in 29 days
  Then they will be let in

Scenario: access after expiry
  When they login in 31 days
  Then they will be asked to renew

11. Revisit, Refactor, and Improve Your Scenarios and Steps

Look for opportunities to generalize your steps and reuse them. You want to accumulate a reusable library of steps so that writing additional features takes less and less effort over time.

12. Refactor Language and Steps to Reflect Better Understanding of Domain

This is an extension of the previous point; as your understanding of the domain and your customer's language/terminology improves, update the language used in your scenarios.

13. Use Compound Steps to Build Up Your Language

Compound steps (calling steps from steps) can help make your features more concise while still keeping your steps general—just don't get too carried away. For example:

Given /^the user (.*) exists$/ do |name|
  # ...
end

Given /^I log in as (.*)$/ do |name|
  # ...
end

Given /^(.*) is logged in$/ do |name|
  Given "the user #{name} exists"
  Given "I log in as #{name}"
end

14. Use Parallel Step Definitions to Support Different Implementations for Features

For example, running features against Webrat and Selenium. Put these step definitions somewhere where they won't be auto-loaded, and require them from the command line or rake task.

15. Avoid Using Conjunctive Steps

Each step should do one thing. You should not generally have step patterns containing "and." For example:

Given A and B

should be split into two steps:

Given A
And B

In Closing...

When I put out a call on Twitter, along with some of the above, I got the following:

• Sliced, w/tomatoes, red onion, balsamic vinegar, olive oil, salt and pepper.
• Get the kind without seeds, they stay good longer, and mix with a bit of rice vinegar to play the "flavors that mix well" game
• slice. add humus. add bread. eat.
• Eat them freshly picked out of an organic garden!

There are numerous ways to best utilize Cucumber and to improve your general Cucumber practices; the above list is by no means all inclusive. If you've got a great tip I missed, leave a comment—I'm always looking to learn and improve :)

Project Structure

Let's start by taking a look at your project structure: the usual advice is to have a features directory as the root of your Cucumber work. In that directory, you place all of your .feature files which contain your features (as you would expect) as well as support and step_definitions directories.

The support directory should contain whatever support code your features need, and an env.rb file which is responsible for loading any required code that lives outside the feature directory tree.

In the step_definitions directory, you place the files (with .rb extensions) that contain your step definitions. These will all get loaded when your features run.

You can have multiple subdirectories in the features directory for grouping features. This allows you to run the features in a particular directory. While this can be useful, it can be awkward in practice. That's because (as of this writing) cucumber loads each ruby file (ending in .rb) it finds in the directory you tell it to run and, recursively, all subdirectories. For example, consider the following tree (each .rb files simply has a puts "x" where x is the name of the file):

features
   +- 1.rb
   +- 2.rb
   +- sub1
      +- 3.rb
   +- sub2
      +- 4.rb
      +- sub3
         +- 5.rb
         +- sub4
            +- 6.rb

So when you run cucumber features, you get:

1
2
3
4
5
6
0 scenarios
0 steps
0m0.000s

but, if you run cucumber features/sub2 you get:

4
5
6
0 scenarios
0 steps
0m0.000s

The issue is that features don't inherit support code or steps from parent directories unless that parent is also visited by Cucumber. So if you want to run subdirectories separately and they share setup code or steps, you have to somehow duplicate that code (possibly by explicitly requiring files from up the tree). This isn't significant, but it is a bit messy. A better approach might be to use tags (described below). If your features groups don't share much, then using subdirectories can work fine.

Languages

In the referenced previous post I talked briefly about Cucumber's multiple language support; here's I'll show you how it's done, and how you can add your own if required.

The file cucumber/lib/cucumber/languages.yml defines the 'natural language' support of Cucumber. This is a yaml file that provides multi-lingual aliases for Gherkin keywords. As an example, here's the entries for English, LOLZ, and Japanese:

"en":
  name: English
  native: English
  encoding: UTF-8
  feature: Feature
  background: Background
  scenario: Scenario
  scenario_outline: Scenario Outline
  examples: Examples|Scenarios
  given: Given
  when: When
  then: Then
  and: And
  but: But
  space_after_keyword: true
"en-lol":
  name: LOLCAT
  native: LOLCAT
  encoding: UTF-8
  feature: OH HAI
  background: B4
  scenario: MISHUN
  scenario_outline: MISHUN SRSLY
  examples: EXAMPLZ
  given: I CAN HAZ
  when: WEN
  then: DEN
  and: AN
  but: BUT
  space_after_keyword: true
"ja":
  name: Japanese
  native: 日本語
  encoding: UTF-8
  feature: フィーチャ|機能
  background: 背景
  scenario: シナリオ
  scenario_outline: シナリオアウトライン|シナリオテンプレート|テンプレ|シナリオテンプレ
  examples: 例|サンプル
  given: 前提
  when: もし
  then: ならば
  and: かつ
  but: しかし|但し
  space_after_keyword: false

To see what languages are available in the version of Cucumber you have, issue the following command:

cucumber --language help

If your desired language isn't supported, clone aslakhellesoy/cucumber and add it. If you do, please send aslakhellesoy a pull request to have it considered for inclusion.

To run features written in a specific language, use the --language flag followed by the 2 (or so) letter abbreviation of the desired language. For example:

cucumber --language ja

Whenever I'm talking about Gherkin keywords, I'll use the English form. Everything said applies to any language version.

Free-form Story/Text

As mentioned in the intro post, following the feature header, you can have any amount of free-form text. This is generally used to give further background or explanation of the feature. Here's an example from The RSpec Book:

Feature: code-breaker submits guess
  The code-breaker submits a guess of four colored
  pegs. The mastermind game marks the guess with black
  and white "marker" pegs.
  For each peg in the guess that matches color
  and position of a peg in the secret code, the
  mark includes one black peg. For each additional
  peg in the guess that matches the color but not
  the position of a color in the secret code, a
  white peg is added to the mark.
  Scenario Outline: submit guess
  ...

Scenario Outlines and Example Tables

Sometimes you will have a collection of scenarios that are structurally all the same, differing only in some set of values. It might be nice to represent these as a table. In fact, the FIT project is aimed at doing just this. However, it can be nice to use a single tool to solve a given class of problem, and so Cucumber supports this style of testing.

There are two pieces to this capability. First is the definition of the scenario outline. This is a skeleton of the scenario, written with placeholders for the actual values. Continuing on from the previous feature:

Scenario Outline: submit guess
  Given the secret code is <code>
  When I guess <guess>
  Then the mark should be <mark>

This is very similar to a regular scenario definition, with two exceptions. First, you use Scenario Outline: instead of Scenario:. This is what informs the system that you want to do a tabular style scenario. The second difference is the use of placeholders, e.g. <guess>.

The second piece is a data table (or tables). These start with the Scenarios: or Examples: keyword. Following the keyword is a textual description of the data in the table. Then we have a table header that serves to map the columns to the placeholders in the scenario. Following that is the data for each case the scenario should be applied to, one per line. Table cells are bracketed by vertical bars (i.e |):

Scenarios: all colors correct
| code    | guess   | mark |
| r g y c | r g y c | bbbb |
| r g y c | r g c y | bbww |
| r g y c | y r g c | bwww |
| r g y c | c r g y | wwww |
Scenarios: 3 colors correct
| code    | guess   | mark |
| r g y c | w g y c | bbb  |
| r g y c | w r y c | bbw  |
| r g y c | w r g c | bww  |
| r g y c | w r g y | www  |
Scenarios: 2 colors correct
| code    | guess   | mark |
| r g y c | w g w c | bb   |
| r g y c | w r w c | bw   |
| r g y c | g w c w | ww   |
Scenarios: 1 color correct
| code    | guess   | mark |
| r g y c | r w w w | b    |
| r g y c | w w r w | w    |

Any number of scenario tables can be used, and all apply to the most recent scenario outline. This results in far less copy/paste and the associated potential for error, as well as being a far more concise format.

Tags

In the simplest case, Cucumber runs all the scenarios in all the features that you point it at. By using tags you can be more specific about what is run. In my opinion, this is a killer feature. You tag features or scenarios by prefixing them with one or more tags, separated by spaces. A tag is simply an identifier prefixed by @. For example:

@billing @annoy
Feature: Verify billing
  @important
  Scenario: Missing product description
  Scenario: Several products

To run features and/or scenarios with specific tags you use the --tags command line flag and provide a comma separated list of tags. Specifying a feature with a tag runs all scenarios in the feature. Here's a couple of examples based on the above code:

cucumber --tags @billing            # Runs both scenarios
cucumber --tags @important          # Runs the first scenario

You can also specify tags not to run, like so:

cucumber --tags ~@important         # Runs the second scenario (Scenarios without @important)
cucumber --tags ~@important,~@other # Won't run tasks tagged @important or @other.

Hooks

Cucumber provides the ability to supply hooks to modify the behavior of executing features. Hooks can be used at the various levels of granularity, generally before and after, and are often defined in your env.rb file. Hooks are executed whenever the event they are defined for occurs.

Global Hooks

Global hooks run when Cucumber begins and exits. Begin hooks are informal: simply put the desired code in a file in the features/support directory (possibly env.rb, but I'd advise keeping it separate).

An exit hook is more formal, using at_exit. Here's an example of a pair of global hooks:

#the begin 'hook'
my_heavy_object = HeavyObject.new
my_heavy_object.do_it
at_exit do
  my_heavy_object.undo_it
end

Scenario Hooks

You can add blocks that will run before and after each scenario:

Before do
  # Do something before each scenario.
end
After do |scenario|
  # Do something after each scenario.
end

The After block will be passed the scenario that just ran. You can use this to inspect its result status by using the failed?, passed? and exception methods. For example:

After do |scenario|
 if(scenario.failed?)
    subject = "[Project X] #{scenario.exception.message}"
    send_failure_email(subject)
  end
end

Step Hooks

Cucumber gives you the ability to define a block that will be executed after each (and every) step:

AfterStep |scenario| do
  # Do something after each step.
end

Tagged Hooks

If you've tagged some of your scenarios, you can also tag scenario and step hooks. You simply pass the tags as arguments to the hook methods). These tagged hooks will only be executed before/after scenarios that are tagged the same and after steps in scenarios tagged the same. Here's an example where the hooks will only be run before scenarios tagged with @cucumis or @sativus.

Before('@cucumis', '@sativus') do
  # Do something before scenarios tagged @cucmis or @sativus
end
AfterStep('@cucumis', '@sativus') do
  # Do something after steps tagged @cucmis or @sativus
end

Background

A Background is very much like a scenario in that it consists of a series of steps. The difference is that its steps are executed before the steps of each scenario in the feature. It's basically a factoring out of a set of common lead-in steps for the features scenarios. One thing to remember is that a Background is run after any Before hooks.

You'll generally only have given Backgrounds. Here's an example:

Feature: User Login
  Background:
    Given account 'A123' for 'Dave' with password '123'
    And account 'B456' for 'Joe' with password 'abc'
  Scenario: Dave logs in and sees his account
    When I log in as 'Dave' using password '123'
    Then I am in account 'A123'
  Scenario: Jow logs in and sees his account
    When I log in as 'Joe' using password 'abc'
    Then I am in account 'B456'

Summary

So that's a quick look at some of the more advanced features of Cucumber. It's a great tool, with a growing community behind and around it. I'll be posting on Cucumber Best Practices next time, so keep an eye out. Enjoy, and comment with any questions!

One of Cucumber's most compelling features is that it provides the ability to write these descriptions using plain text in your native language. Cucumber’s language, Gherkin, is usable in a growing variety of human languages, including LOLZ. The advantage of this is that these feature descriptions can be written and/or understood by non-technical people involved in the project.

One important thing to keep in mind is that Cucumber is NOT a replacement for RSpec, test/unit, etc. It is not a low level testing/specification framework.

Cucumber plays a central role in a development approach called Behaviour Driven Development (BDD).

A Bit About BDD

Dan North describes BDD as “writing software that matters” [in The RSpec Book] and outlines 3 principles:

1. Enough is enough: do as much planning, analysis, and design as you need, but no more.
2. Deliver stakeholder value: everything you do should deliver value or increase your ability to do so.
3. It’s a behavior: everyone involved should have the same way of talking about the system and what it does.

BDD in its grandest sense is about communication and viewing your software as a system with behaviour. BDD tools such as RSpec and Cucumber strive to enable you to describe the behavior of your software in a very understandable way: understandable to everyone involved.

Features

A feature is something that your software does (or should do), and generally corresponds to a user story and a way to tell when it’s finished and that it works.

The general format of a feature is:

Feature: <short description>
  <story>
  <scenario 1>
  ...
  <scenario n>

Within the definition of a feature you can provide a plain text description of the story. You can use any format for this, but having some sort of template makes it easier to see the important bits of information with a quick glance. Once of the more common template is discussed by Mike Cohn [in User Stories Applied]:

As a <role>
I want <feature>
so that <business value>

This format focuses us on three important questions:

• Who’s using the system?
• What are they doing?
• Why do they care?

Here’s a sample story:

As a code-breaker
I want to start a game
So that I can break the code

That defines who the user is (a code-breaker), what they want to do (start a game) and why (be able to break the code).

Scenarios

A feature is defined by one or more scenarios. A scenario is a sequence of steps through the feature that exercises one path. Cucumber uses the BDD style that Dan North put forth with his jBehave project: given-when-then.

A scenario is made up of 3 sections related to the 3 types of steps:

1. Given: This sets up preconditions, or context, for the scenario. It works much like the setup in xUnit and before blocks in RSpec.
2. When: This is what the feature is talking about, the action, the behaviour that we’re focused on.
3. Then: This checks postconditions… it verifies that the right thing happen in the When stage.

The general form of a scenario is:

Scenario: <description>
  <step 1>
  …
  <step n>

Following our example, here’s a scenario:

Scenario: start game
  Given I am not yet playing
  When I start a new game
  Then the game should say “Welcome to CodeBreaker”
  And the game should say “Enter guess:”

One thing to note is the last line. Notice the And. And can be used in any of the three sections. It serves as a nice shorthand for repeating the Given, When, or Then. And stands in for whatever the most recent explicitly named step was: Given, When, or Then. The last two lines above could have been:

Then the game should say “Welcome to CodeBreaker”
Then the game should say “Enter guess:”

That doesn’t read nearly as well, though. Similarly, if you want to state a negative Then step, you can use But in place of Then, for example:

Then the game should say “Welcome to CodeBreaker”
But the game should not say “Save the cheerleader, save the world”

While there are no constraints on the number or order of steps, it is generally best to keep scenarios as simple as possible and have multiple simple scenarios. The closer your scenarios conform to the given-when-then format, the better.

Implementing Steps

So here's our feature:

Feature: code-breaker starts game
  As a code-breaker
  I want to start a game
  So that I can break the code
  Scenario: start game
    Given I am not yet playing
    When I start a new game
    Then the game should say “Welcome to CodeBreaker”
    And the game should say “Enter guess:”

If you run that you’ll see an echo of the feature followed by (using Cucumber 0.3.11):

1 scenario (1 undefined)
4 steps (4 undefined)
0m0.001s
You can implement step definitions for undefined steps with these snippets:
Given /^I am not yet playing$/ do
  pending
end
When /^I start a new game$/ do
  pending
end
Then /^the game should say “Welcome to CodeBreaker”$/ do
  pending
end
Then /^the game should say “Enter guess:”$/ do
  pending
end

The next step (pardon the pun) is to define what each of our steps mean. When we executed our feature with no steps defined, Cucumber gave us skeletons for the undefined steps (see above). If we put those in the file features/step_definitions/codebreaker.rb and run it again, we get:

1 scenario (1 pending)
4 steps (3 skipped, 1 pending)

As you can see from above, the basic structure of a step definition is the keyword (i.e. Given, When, or Then) followed by a regular expression and a block of Ruby code. The regular expression is used to identify the desired step implementation. The step text in scenarios is matched against the regular expressions of appropriate (i.e. given, when, or then) step implementations to find the one to use. When a match is found, the substrings matching any groups in the regular expression are used as arguments to the block which is then evaluated. The result of that evaluation is discarded. Note that these arguments are always strings. If you need them converted to other types, it's up to you to do that conversion in the block. These groups and parameters have knowledge of position (i.e.. group 1 is used as the first parameter, group 2 as the second, and so on).

Notice that the suggested steps are completely concrete. While that is fine some of the time, you will generally want to refactor steps and make them more generic and reusable. Notice that there are two then step definitions that are much the same:

Then /^the game should say “Welcome to CodeBreaker”$/ do
end
Then /^the game should say “Enter guess:”$/ do
end

The difference is the string inside quotes (using quotes or similar delimiters is very handy for matching the groups). We can factor that out into a regex group:

Then /^the game should say “(.*)”$/ do |message|
end

Our given step could be:

Given /^I am not yet playing$/ do
  @game = Codebreaker::Game.new
end

Next is the when step:

When /^I start a new game$/ do
end

This might be implemented as:

When /^I start a new game$/ do
    @messages = @game.start
end

Now we have the variable @messages that can be used in subsequent steps.

Recall how we left our then step definition:

Then /^the game should say “(.*)”$/ do |message|
end

We can now fill this in:

Then /^the game should say “(.*)”$/ do |message|
  @messages.should include(message)
end

You can use whatever method of verification you want in the then steps: rspec, test/unit, shoulda, etc. I happen to prefer RSpec.

Earlier I mentioned that Cucumber supports various languages including LOLZ. Here’s a feature in LOLZ:

OH HAI: STUFFING
 MISHUN: CUCUMBR
    I CAN HAZ IN TEH BEGINNIN 3 CUCUMBRZ
    WEN I EAT 2 CUCUMBRZ
    DEN I HAZ 2 CUCUMBERZ IN MAH BELLY
    AN IN TEH END 1 CUCUMBRZ KTHXBAI

And the step implementations:

ICANHAZ /^IN TEH BEGINNIN (d+) CUCUMBRZ$/ do |n|
  @basket = Basket.new(n.to_i)
end
WEN /^I EAT (d+) CUCUMBRZ$/ do |n|
  @belly = Belly.new
  @belly.eat(@basket.take(n.to_i))
end
DEN /^I HAZ (d+) CUCUMBERZ IN MAH BELLY$/ do |n|
  @belly.cukes.should == n.to_i
end
DEN /^IN TEH END (d+) CUCUMBRZ KTHXBAI$/ do |n|
  @basket.cukes.should == n.to_i
end

And that's all there is to understanding the basics of Cucumber.