Doc Strings
Doc strings just allow you to specify a larger piece of text than you could fit on a single line. For example, if you need to describe the precise content of an email message, you could do it like this:
| | Scenario: Ban Unscrupulous Users |
| | When I behave unscrupulously |
| | Then I should receive an email containing: |
| | """ |
| | Dear Sir, |
| | |
| | Your account privileges have been revoked due to your unscrupulous behavior. |
| | |
| | Sincerely, |
| | The Management |
| | """ |
| | And my account should be locked |
Just like a data table, the entire string between the """ triple quotes is attached to the step above it. The indentation of the opening """ is not important, although common practice is to indent two spaces in from the enclosing step, as we’ve shown. The indentation inside the triple quotes, however, is significant: imagine the left margin running down from the start of the first """. If you want to include indentation within your string, you need to indent it within this margin.
Doc strings open up all kinds of possibilities for specifying data in your steps. We have seen teams use these arguments to specify snippets of JSON or XML data when writing features for an API, for example. There is an example of how to do this in Chapter 12, Testing a REST Web Service. You do need to be cautious when including this much detail in a scenario. It is easy to create a lot of clutter with a large piece of data, making it hard to read the scenario as a whole. You can also easily create brittle scenarios, where the slightest change to the system causes the scenario to fail because it is behaving slightly differently than the way it was described in the doc string.
OK, we’ve covered the more advanced features of Gherkin you can use to express your business requirements. The last thing we want to talk about in this chapter is keeping things organized.