Comments: Allowed only at start of lines. Formally zero or more spaces followed by a hash followed by any characters until newline.

Freeform comment: These are only allowed in some keywords that explicitly allow freeform comments.

Keywords: Feature, Rule, Example, Scenario, Given, When, Then, And, But, *, Background, Scenario Outline, Scenario Template, Examples, Scenarios

Asterisk is for writing lists.

Given I am an elf
* i am alive
* i have pointy ears

The following keywords are allowed a freeform comment section: Example, Scenario, Background, Scenario Outline, and Rule.

Heirarchy

• Feature: must be exactly one per .feature file.
• Rule: A container for scenarios and examples. Optional.
• Scenarios and Examples: A container for steps.
• Steps: Trigger a particular part of the acceptance test.

Background

Background is a container for steps which are run before every scenario in the feature file. It is used to prefix every test with a chain of "given ... and ..." clauses.

Step keywords

Step keywords do not actually matter. The keyword you use is not passed along to the testing harness. But you are still encouraged to use them correctly.

• Given: set up initial conditions
• When: the action triggering the test
• Then: the expected result
• And, But, *: additional clauses

Scenario Templates and Outlines

"Scenario Template" and "Scenario Outline" are used for template and table based tests. Steps within the outline are executed with keywords surrounded in <>'s being replaced with the value of rows in a table.

One or more "Examples" and "Scenarios" blocks must be provided. Each block must contain a table with variable names and values of each variable in that test situation.

Scenario Outline: eating
  Given there are  cucumbers
  When I eat  cucumbers
  Then I should have  cucumbers

  Examples:
    | start | eat | left |
    |    12 |   5 |    7 |
    |    20 |   5 |   15 |

Doc strings and table parameters

Doc strings are triple quotes, end with triple quotes. Passed to the step as their last parameter. Indentation is not significant outside the quote but the indentation leading up to the first triple quote is removed from all lines of the string.

Given some step
  """
  the two spaces before this line are removed because of the string
  """

Table parameters work the same way but a table instead of a string. Used to provide a table of values to a step.

Given the following users exist:
  | name   | email              | twitter         |
  | Aslak  | aslak@cucumber.io  | @aslak_hellesoy |
  | Julien | julien@cucumber.io | @jbpros         |
  | Matt   | matt@cucumber.io   | @mattwynne      |