How Cucumber Works

Before we dive into the meat of the book, let’s give you some context with a high-level overview of a typical Cucumber test suite. Cucumber is a command-line tool. When you run it, it reads in your specifications from plain-language text files called features, examines them for scenarios to test, and runs the scenarios against your system. Each scenario is a list of steps for Cucumber to work through. So that Cucumber can understand these feature files, they must follow some basic syntax rules. The name for this set of rules is Gherkin.

Along with the features, you give Cucumber a set of step definitions, which map the business-readable language of each step into Ruby code to carry out whatever action is being described by the step. In a mature test suite, the step definition itself will probably just be one or two lines of Ruby that delegate to a library of support code, specific to the domain of your application, that knows how to carry out common tasks on the system. Normally that will involve using an automation library, like the browser automation library Capybara, to interact with the system itself.

This hierarchy, from features down to automation library, is illustrated by the figure.

If the Ruby code in the step definition executes without error, Cucumber proceeds to the next step in the scenario. If it gets to the end of the scenario without any of the steps raising an error, it marks the scenario as having passed. If any of the steps in the scenario fail, however, Cucumber marks the scenario as having failed and moves on to the next one. As the scenarios run, Cucumber prints out the results showing you exactly what is working and what isn’t.

That’s it in a nutshell. There are many other advantages to Cucumber that make it an excellent choice: you can write your specifications in more than forty different spoken languages, you can use tags to organize and group your scenarios, and you can easily integrate with a host of high-quality Ruby automation libraries to drive almost any kind of application. All that and more will become clear as you read the rest of the book.