Creating a Feature
Cucumber tests are grouped into features. We use this name because we want them to describe the features that a user will be able to enjoy when using our program. The first thing we need to do is make a directory where we’ll store our new program along with the features we’ll be writing for it.
| | $ mkdir calculator |
| | $ cd calculator |
We’re going to let Cucumber guide us through the development of our calculator program, so let’s start right away by running cucumber in this empty folder:
| | $ cucumber |
| | |
| | You don't have a 'features' directory. Please create one to get started. |
| | See http://cukes.info/ for more information. |
Since we didn’t specify any command-line arguments, Cucumber has assumed that we’re using the conventional features folder to store our tests. That would be fine, except that we don’t have one yet. Let’s follow the convention and create a features directory:
| | $ mkdir features |
Now run Cucumber again.
| | $ cucumber |
| | |
| | 0 scenarios |
| | 0 steps |
| | 0m0.000s |
Each Cucumber test is called a scenario, and each scenario contains steps that tell Cucumber what to do. This output means that Cucumber is happily scanning the features directory now, but it didn’t find any scenarios to run. Let’s create one.
Our user research has shown us 67 percent of all mathematical operations are additions, so that’s the operation we want to support first. In your favorite editor, create a plain-text file called features/adding.feature:
| first_taste/01/features/adding.feature | |
| | Feature: Adding |
| | |
| | Scenario: Add two numbers |
| | Given the input "2+2" |
| | When the calculator is run |
| | Then the output should be "4" |
This feature file contains the first scenario for our calculator program. We’ve translated one of the examples we were given in the previous section into a Cucumber scenario that we can ask the computer to run over and over again. You can probably see that Cucumber expects a little bit of structure in this file. The keywords Feature, Scenario, Given, When, and Then are the structure, and everything else is documentation. Although some of the keywords are highlighted here in the book—and they may be in your editor too—it’s just a plain-text file. The structure is called Gherkin.
When you save this file and run cucumber, you should see a great deal more output than the last time:
| | $ cucumber |
| | Feature: Adding |
| | |
| | Scenario: Add two numbers |
| | Given the input "2+2" |
| | When the calculator is run |
| | Then the output should be "4" |
| | |
| | 1 scenario (1 undefined) |
| | 3 steps (3 undefined) |
| | 0m0.003s |
| | |
| | You can implement step definitions for undefined steps with these snippets: |
| | |
| | Given /^the input "(.*?)"$/ do |arg1| |
| | pending # express the regexp above with the code you wish you had |
| | end |
| | |
| | When /^the calculator is run$/ do |
| | pending # express the regexp above with the code you wish you had |
| | end |
| | |
| | Then /^the output should be "(.*?)"$/ do |arg1| |
| | pending # express the regexp above with the code you wish you had |
| | end |
| | |
| | If you want snippets in a different programming language, |
| | just make sure a file with the appropriate file extension |
| | exists where cucumber looks for step definitions. |
Wow, that’s a lot of output all of a sudden! Let’s take a look at what’s going on here. First, we can see that Cucumber has found our feature and is trying to run it. We can tell this because Cucumber has repeated the content of the feature back to us. You might also have noticed that the summary output 0 scenarios has changed to 1 scenario (undefined). This means that Cucumber has read the scenario in our feature but doesn’t know how to run it yet.
Second, Cucumber has printed out three code snippets. These are sample code for step definitions, written in Ruby, which tell Cucumber how to translate the plain English steps in the feature into actions against our application. Our next step will be to put these snippets into a Ruby file where we can start to flesh them out.
Before we explore beneath the layer of business-facing Gherkin features into step definitions, it’s worth taking a quick look at the map in case anyone is feeling lost. Figure 2, The main layers of a Cucumber test suite reminds us how things fit together. We start with features, which contain our scenarios and steps. The steps of our scenarios call step definitions that provide the link between the Gherkin features and the application being built.
Figure 2. The main layers of a Cucumber test suite
Now we’ll implement some step definitions so that our scenario is no longer undefined.