Gherkin uses a set of special keywords to give structure and meaning to executable specifications. Each keyword is translated to many spoken languages; in this reference we\u2019ll use English.<\/p>\n\n\n\n
Most lines in a Gherkin document start with one of the keywords<\/a>.<\/p>\n\n\n\n Comment lines are allowed anywhere in the file. They begin with zero or more spaces, followed by a hash sign ( Either spaces or tabs may be used for indentation. The recommended indentation level is two spaces. Here is an example:<\/p>\n\n\n\n The trailing portion (after the keyword) of each step is matched to a code block, called a step definition<\/a>.<\/p>\n\n\n\n Each line that isn\u2019t a blank line has to start with a Gherkin keyword<\/em>, followed by any text you like. The only exceptions are the feature and scenario descriptions.<\/p>\n\n\n\n The primary keywords are:<\/p>\n\n\n\n There are a few secondary keywords as well:<\/p>\n\n\n\n Localisation<\/p>\n\n\n\n Gherkin is localised for many spoken languages<\/a>; each has their own localised equivalent of these keywords.<\/p>\n\n\n\n The purpose of the The first primary keyword in a Gherkin document must always be You can add free-form text underneath These description lines are ignored by Cucumber at runtime, but are available for reporting (They are included by default in html reports).<\/p>\n\n\n\n The name and the optional description have no special meaning to Cucumber. Their purpose is to provide a place for you to document important aspects of the feature, such as a brief explanation and a list of business rules (general acceptance criteria).<\/p>\n\n\n\n The free format description for You can place tags<\/a> above Free-form descriptions (as described above for You can write anything you like, as long as no line starts with a keyword.<\/p>\n\n\n\n The (optional) For example:<\/p>\n\n\n\n This is a concrete example<\/em> that illustrates<\/em> a business rule. It consists of a list of steps<\/a>.<\/p>\n\n\n\n The keyword You can have as many steps as you like, but we recommend you keep the number at 3-5 per example. If they become longer than that, they lose their expressive power as specification and documentation.<\/p>\n\n\n\n In addition to being a specification and documentation, an example is also a test<\/em>. As a whole, your examples are an executable specification<\/em> of the system.<\/p>\n\n\n\n Examples follow this same pattern:<\/p>\n\n\n\n Each step starts with Cucumber executes each step in a scenario one at a time, in the sequence you\u2019ve written them in. When Cucumber tries to execute a step, it looks for a matching step definition to execute.<\/p>\n\n\n\n Keywords are not taken into account when looking for a step definition. This means you cannot have a Cucumber considers the following steps duplicates:<\/p>\n\n\n\n This might seem like a limitation, but it forces you to come up with a less ambiguous, more clear domain language:<\/p>\n\n\n\n When Cucumber executes a The purpose of It\u2019s okay to have several Examples:<\/p>\n\n\n\n It\u2019s strongly recommended you only have a single Examples:<\/p>\n\n\n\n Imagine it’s 1922<\/p>\n\n\n\n Most software does something people could do manually (just not as efficiently).<\/p>\n\n\n\n Try hard to come up with examples that don\u2019t make any assumptions about technology or user interface. Imagine it\u2019s 1922, when there were no computers.<\/p>\n\n\n\n Implementation details should be hidden in the step definitions<\/a>.<\/p>\n\n\n\n The step definition<\/a> of a An observation should<\/em> be on an observable<\/strong> output. That is, something that comes out<\/em> of the system (report, user interface, message), and not something deeply buried inside it (like a database).<\/p>\n\n\n\n Examples:<\/p>\n\n\n\n While it might be tempting to implement You should only verify outcome that is observable for the user (or external system), and databases usually are not.<\/p>\n\n\n\n If you have several Or, you could make it read more fluidly by writing:<\/p>\n\n\n\n Occasionally you\u2019ll find yourself repeating the same Since it is repeated in every scenario, this is an indication that those steps are not essential<\/em> to describe the scenarios; they are incidental details<\/em>. You can literally move such A A You can only have one set of For example:<\/p>\n\n\n\n For a less explicit alternative to The The keyword Copying and pasting scenarios to use different values quickly becomes tedious and repetitive:<\/p>\n\n\n\n We can collapse these two similar scenarios into a Scenario outlines allow us to more concisely express these scenarios through the use of a template with #<\/code>) and some text. Comments do have to start on a new line.<\/p>\n\n\n\nFeature: Guess the word\n\n # The first example has two steps\n Scenario: Maker starts a game\n When the Maker starts a game\n Then the Maker waits for a Breaker to join\n\n # The second example has three steps\n Scenario: Breaker joins a game\n Given the Maker has started a game with the word \"silky\"\n When the Breaker joins the Maker's game\n Then the Breaker must guess a word with 5 characters<\/code><\/pre>\n\n\n\nKeywords \ud83d\udd17\ufe0e<\/a><\/h1>\n\n\n\n
Feature<\/code><\/li>Rule<\/code> (as of Gherkin 6)<\/li>Example<\/code> (or Scenario<\/code>)<\/li>Given<\/code>, When<\/code>, Then<\/code>, And<\/code>, But<\/code> (steps)<\/li>Background<\/code><\/li>Scenario Outline<\/code> (or Scenario Template<\/code>)<\/li>Examples<\/code><\/li><\/ul>\n\n\n\n\"\"\"<\/code> (Doc Strings)<\/li>|<\/code> (Data Tables)<\/li>@<\/code> (Tags)<\/li>#<\/code> (Comments)<\/li><\/ul>\n\n\n\nFeature \ud83d\udd17\ufe0e<\/a><\/h2>\n\n\n\n
Feature<\/code> keyword is to provide a high-level description of a software feature, and to group related scenarios.<\/p>\n\n\n\nFeature<\/code>, followed by a :<\/code> and a short text that describes the feature.<\/p>\n\n\n\nFeature<\/code> to add more description.<\/p>\n\n\n\nFeature: Guess the word\n\n The word guess game is a turn-based game for two players.\n The Maker makes a word for the Breaker to guess. The game\n is over when the Breaker guesses the Maker's word.\n\n Example: Maker starts a game<\/code><\/pre>\n\n\n\nFeature<\/code> ends when you start a line with the keyword Rule<\/code>, Example<\/code> or Scenario Outline<\/code> (or their alias keywords).<\/p>\n\n\n\nFeature<\/code> to group related features, independent of your file and directory structure.<\/p>\n\n\n\nDescriptions \ud83d\udd17\ufe0e<\/a><\/h2>\n\n\n\n
Feature<\/code>) can also be placed underneath Example<\/code>\/Scenario<\/code>, Background<\/code>, Scenario Outline<\/code> and Rule<\/code>.<\/p>\n\n\n\nRule \ud83d\udd17\ufe0e<\/a><\/h2>\n\n\n\n
Rule<\/code> keyword has been added in Gherkin v6. (Note that Gherkin 6 has not yet been incorporated into all implementation of Cucumber!) The purpose of the Rule<\/code> keyword is to represent one business rule<\/em> that should be implemented. It provides additional information for a feature. A Rule<\/code> is used to group together several scenarios that belong to this business rule<\/em>. A Rule<\/code> should contain one or more scenarios that illustrate the particular rule. A Rule<\/code>cannot contain a Background<\/code>.<\/p>\n\n\n\n# -- FILE: features\/gherkin.rule_example.feature\nFeature: Highlander\n\n Rule: There can be only One\n\n Example: Only One -- More than one alive\n Given there are 3 ninjas\n And there are more than one ninja alive\n When 2 ninjas meet, they will fight\n Then one ninja dies (but not me)\n And there is one ninja less alive\n\n Example: Only One -- One alive\n Given there is only 1 ninja alive\n Then he (or she) will live forever ;-)\n\n Rule: There can be Two (in some cases)\n\n Example: Two -- Dead and Reborn as Phoenix\n ...<\/code><\/pre>\n\n\n\nExample \ud83d\udd17\ufe0e<\/a><\/h2>\n\n\n\n
Scenario<\/code> is a synonym of the keyword Example<\/code>.<\/p>\n\n\n\nGiven<\/code> steps)<\/li>When<\/code> steps)<\/li>Then<\/code> steps)<\/li><\/ul>\n\n\n\nSteps \ud83d\udd17\ufe0e<\/a><\/h2>\n\n\n\n
Given<\/code>, When<\/code>, Then<\/code>, And<\/code>, or But<\/code>.<\/p>\n\n\n\nGiven<\/code>, When<\/code>, Then<\/code>, And<\/code> or But<\/code> step with the same text as another step.<\/p>\n\n\n\nGiven there is money in my account\nThen there is money in my account<\/code><\/pre>\n\n\n\nGiven my account has a balance of \u00a3430\nThen my account should have a balance of \u00a3430<\/code><\/pre>\n\n\n\nGiven \ud83d\udd17\ufe0e<\/a><\/h3>\n\n\n\n
Given<\/code> steps are used to describe the initial context of the system – the scene<\/em> of the scenario. It is typically something that happened in the past<\/em>.<\/p>\n\n\n\nGiven<\/code> step, it will configure the system to be in a well-defined state, such as creating and configuring objects or adding data to a test database.<\/p>\n\n\n\nGiven<\/code> steps is to put the system in a known state<\/strong> before the user (or external system) starts interacting with the system (in the When<\/code> steps). Avoid talking about user interaction in Given<\/code>\u2019s. If you were creating use cases, Given<\/code>\u2019s would be your preconditions.<\/p>\n\n\n\nGiven<\/code> steps (just use And<\/code> or But<\/code> for number 2 and upwards to make it more readable).<\/p>\n\n\n\nWhen \ud83d\udd17\ufe0e<\/a><\/h3>\n\n\n\n
When<\/code> steps are used to describe an event, or an action<\/em>. This can be a person interacting with the system, or it can be an event triggered by another system.<\/p>\n\n\n\nWhen<\/code> step per Scenario. If you feel compelled to add more, it\u2019s usually a sign that you should split the scenario up into multiple scenarios.<\/p>\n\n\n\nThen \ud83d\udd17\ufe0e<\/a><\/h3>\n\n\n\n
Then<\/code> steps are used to describe an expected<\/em> outcome, or result.<\/p>\n\n\n\nThen<\/code> step should use an assertion<\/em> to compare the actual<\/em> outcome (what the system actually does) to the expected<\/em> outcome (what the step says the system is supposed to do).<\/p>\n\n\n\nThen<\/code> steps to just look in the database – resist that temptation!<\/p>\n\n\n\nAnd, But \ud83d\udd17\ufe0e<\/a><\/h3>\n\n\n\n
Given<\/code>\u2019s, When<\/code>\u2019s, or Then<\/code>s, you could<\/em> write:<\/p>\n\n\n\nExample: Multiple Givens\n Given one thing\n Given another thing\n Given yet another thing\n When I open my eyes\n Then I should see something\n Then I shouldn't see something else<\/code><\/pre>\n\n\n\nExample: Multiple Givens\n Given one thing\n And another thing\n And yet another thing\n When I open my eyes\n Then I should see something\n But I shouldn't see something else<\/code><\/pre>\n\n\n\nBackground \ud83d\udd17\ufe0e<\/a><\/h2>\n\n\n\n
Given<\/code> steps in all of the scenarios in a feature.<\/p>\n\n\n\nGiven<\/code> steps to the background, by grouping them under a Background<\/code>section.<\/p>\n\n\n\nBackground<\/code> allows you to add some context to the scenarios in the feature. It can contain one or more Given<\/code> steps.<\/p>\n\n\n\nBackground<\/code> is run before each<\/em> scenario, but after any Before hooks<\/a>. In your feature file, put the Background<\/code> before the first Scenario<\/code>.<\/p>\n\n\n\nBackground<\/code> steps per feature. If you need different Background<\/code> steps for different scenarios, you\u2019ll need to split them into different feature files.<\/p>\n\n\n\nFeature: Multiple site support\n Only blog owners can post to a blog, except administrators,\n who can post to all blogs.\n\n Background:\n Given a global administrator named \"Greg\"\n And a blog named \"Greg's anti-tax rants\"\n And a customer named \"Dr. Bill\"\n And a blog named \"Expensive Therapy\" owned by \"Dr. Bill\"\n\n Scenario: Dr. Bill posts to his own blog\n Given I am logged in as Dr. Bill\n When I try to post to \"Expensive Therapy\"\n Then I should see \"Your article was published.\"\n\n Scenario: Dr. Bill tries to post to somebody else's blog, and fails\n Given I am logged in as Dr. Bill\n When I try to post to \"Greg's anti-tax rants\"\n Then I should see \"Hey! That's not your blog!\"\n\n Scenario: Greg posts to a client's blog\n Given I am logged in as Greg\n When I try to post to \"Expensive Therapy\"\n Then I should see \"Your article was published.\"<\/code><\/pre>\n\n\n\nBackground<\/code>, check out tagged hooks<\/a>.<\/p>\n\n\n\nTips for using Background \ud83d\udd17\ufe0e<\/a><\/h2>\n\n\n\n
Background<\/code> to set up complicated states<\/strong>, unless that state is actually something the client needs to know.Given I am logged in as a site owner<\/code>.<\/li><\/ul><\/li>Background<\/code> section short<\/strong>.Background<\/code> is more than 4 lines long, consider moving some of the irrelevant details into higher-level steps.<\/li><\/ul><\/li>Background<\/code> section vivid<\/strong>.\"User A\"<\/code>, \"User B\"<\/code>, \"Site 1\"<\/code>, and so on.<\/li><\/ul><\/li>Background<\/code> section has scrolled off the screen, the reader no longer has a full overview of whats happening. Think about using higher-level steps, or splitting the *.feature<\/code> file.<\/li><\/ul><\/li><\/ul>\n\n\n\nScenario Outline \ud83d\udd17\ufe0e<\/a><\/h2>\n\n\n\n
Scenario Outline<\/code> keyword can be used to run the same Scenario<\/code> multiple times, with different combinations of values.<\/p>\n\n\n\nScenario Template<\/code> is a synonym of the keyword Scenario Outline<\/code>.<\/p>\n\n\n\nScenario: eat 5 out of 12\n Given there are 12 cucumbers\n When I eat 5 cucumbers\n Then I should have 7 cucumbers\n\nScenario: eat 5 out of 20\n Given there are 20 cucumbers\n When I eat 5 cucumbers\n Then I should have 15 cucumbers<\/code><\/pre>\n\n\n\nScenario Outline<\/code>.<\/p>\n\n\n\n< ><\/code>-delimited parameters:<\/p>\n\n\n\nScenario Outline: eating\n Given there are <start> cucumbers\n When I eat <eat> cucumbers\n Then I should have <left> cucumbers\n\n Examples:\n | start | eat | left |\n | 12 | 5 | 7 |\n | 20 | 5 | 15 |<\/code><\/pre>\n\n\n\n