Comments
As well as the description fields that follow Feature and Scenario keywords, Cucumber allows you to precede these keywords with comments.
Like in Ruby, comments start with a # character. Unlike in Ruby, comments have to be the first and only thing on a line (well, apart from whitespace).
Here’s an example:
| gherkin_basics/comments_example.feature | |
| | # This feature covers the account transaction and hardware-driver modules |
| | Feature: Withdraw Cash |
| | In order to buy beer |
| | As an account holder |
| | I want to withdraw cash from the ATM |
| | |
| | # Can't figure out how to integrate with magic wand interface |
| | Scenario: Withdraw too much from an account in credit |
| | Given I have $50 in my account |
| | # When I wave my magic wand |
| | And I withdraw $100 |
| | Then I should receive $100 |
You can also put comments within a scenario. The most common use for this is to comment out a step, as we’ve shown in the previous example.
As in any programming language, comments can quickly go stale and become meaningless or downright confusing. When this happens, the comment causes more harm than good. We advise you to use them as sparingly as you can and put the important stuff into scenarios where it can be tested.
Here’s how we think about this: the description, which you can put after each keyword, is part of the structured Gherkin document and is the right place to put documentation for your stakeholders.
Comments, on the other hand, can be used more to leave notes for testers and programmers who are working with the features. Think of a comment as something more temporary, a bit like a sticky note.
Don’t forget that programmers and testers need documentation too. If there are technical details that need to be documented with the feature, you should feel free to put them into the description too, provided that the business-facing members of your team are comfortable with it being there.