Cucumber works by using features, and step definitions. Features are written in Gherkin which reads like plain text, and step definitions are written in javascript. Cucumber looks through your feature file, and runs the matching step definition function when it sees a matching pair.

Gettings Started With Cucumber: Gherkin

Cucumber lets you write your features in Gherkin, a language that reads similar to plain English, making features double as documentation. Each feature file consists of a single feature as well as multiple scenarios for that feature. An example can be seen bellow:

Feature: Be a cool cat
	
	Scenario: Become a cool cat
  		Given I am not cool
  		When I read Capsule Cat
  		Then I become a cool cat
	
	Scneario: Continue being a cool cat
		Given I am already cool
		When I read Capsule Cat
		Then I continue being cool

There are a few things to note in the above format. The Scenario is writin using single steps, where each step consists of a single, simple action the user can take. Typically they follow the given, when, then format. Given a certain state, when the user does this action, then they should see this result. In it’s simplicity, it manages to cover nearly all possible options when testing.

However there are additional options such as and and but, as well as more advanced options such as adding a background that runs before all scenarios. To see more on these take a look at the Cucumber docs.

Cucumber doesn’t distiguish between the given, when, then, and or but keywords. It only marks them as being the start to a new step. They are mostly used for documentation purpose, so feel free to use whichever keyword fits your step best.

It is best to keep the number of steps in a scenario between 3 – 5 to keep things simple, and to have a better idea of where failures are happening. It is also a good idea to keep steps as simple as possible, so if you find you are using any keywords mid step, such as:

When I enter my username and my password

It’s best to split the step into multiple steps, even if you pushes your scenario past 5 steps:

When I enter my username
And I enter my password

Gettings Started With Cucumber: Step Definition

While the Gherkin Features and Scenarios are great for documentation and readability, Cucumber doesn’t run them out of the box. There is one more step you will need to do in order to run your features, and that is write some step definitions. While Cucumber supports many languages, we’ll be going over JS.

All step definitions in a step definition file are wrapped in the following function:

	module.exports = function() {
	}

You can place as many steps in a step definition file, as long as they are all placed inside of your module.exports function. Here is a simple step definition to the step: Given I visit "www.capsulecat.com":

module.exports = function() {
	this.Given(/^I visit "([^"]*)"$/, function (searchTerm) {
		client.url(searchTerm);
	});
}

Notice in the definition, you replace what is in the quotations in the step, with "([^"]*)". And the function takes in a paramiter, which in this case is searchTerm. You can then call on that paramiter in the function like you normally would. Cucumber will take what is in the quotations in the step and pass them into the function as the paramiter. Step definitions don’t need to take a paramiter, the above definition could also be written like this:

module.exports = function() {
	this.Given(/^I have visited Capsule Cat$/, function () {
		client.url("http://capsulecat.com/");
	});
}

Similarly to steps, step definitions do not care if you use the given, when, then, and or but keywords. But the keyword you use in your step needs to match the one you used in your step definition.

Now that you know about step definitions, know that there are many ways to automaticlly generate these definitions. Tools like Chimp JS take in your Feature files and give you back empty step definitions, which makes things go by a lot faster, as writing step definitions can be timley.

Folder Structure

While there is no set standard on how to organize your Cucumber files, there is a minimum for what you need. All tests need to be in a “features” folder, but other then that, you can organize them however you’d like.

While it’s nice to have a loose structure, this is so loose that it’s complicated. It’s hard to have feature files and step deffinitions that both don’t get so long they’re impossible to read, or they are so seperated that they overlap. While it’s not perfect, there is a managable format you can try when starting out:

peoject folder
|	project folder ext.
|	features
|	|	specs
|	|	|	stepdefinitions.js
|	|	feature.feature

All step definitions files go in the specs folder, and all feature files go in the feature folder. Your step definition files can get rather long, but with good, standard naming methods, it is managable.