Gherkin - how do you write an unambiguous test case in English?

Question

English could be ambiguous, and it seems to me there is an assumption in methodologies that employ Gherkin, that a anyone who speaks English to some degree, can write and understand the test cases, even before any code has been written.

So how does the methodology instruct you to work, given the following simple test scenario that needs automation:

In a Library application, to add a book to the library, the user clicks on Add, a Book Info dialog pops up and the user is expected to fill in the book title etc' and click OK.

Suppose the QA person writes the following:

Scenario: clicking the Add button
    Given a user who is already logged in to the application
    When the user clicks the Add button
    Then the Book Info dialog is displayed

Simple enough? Is this a good test? i think i speak English but i don't understand it.

The fields in the dialog should be empty, perhaps some fields should have some default or initial value. Perhaps the tester expects the implementation of the "Then the Book Info dialog is displayed" to ensure all of that, but does the implementor know that? how is that communicated?

Perhaps the test should have been written as

Scenario: clicking the Add button
    Given a user who is already logged in to the application
    When the user clicks the Add button
    Then the Book Info dialog is displayed and all the fields are empty

It could take a couple of seconds between the Add click and the dialog showing. So the test may fail because the implementation checked too soon if the dialog is up, or didn't wait long enough for the dialog to show, and the test fails.

A person doing manual testing does not need to involve herself with that issue, unless it takes too long for the dialog to appear. So the above is exactly how this person would write the test (so the point here is that the tester needs to be smart enough to take this into consideration, or some developer needs to explain that, or they just fix it after the test fails).

Somehow, this simple action requires some more information... when is it communicated between the person writing the test and the one implementing the actions of the test?

Perhaps the test should have been written as

Scenario: clicking the Add button
    Given a user who is already logged in to the application
    When the user clicks the Add button
    Then the Book Info dialog is displayed within a couple of seconds  and all the fields are empty

or perhaps it should have been written as:

Scenario: clicking the Add button
    Given a user who is already logged in to the application
    When the user clicks the Add button
         And the user waits a couple of seconds
    Then the Book Info dialog is displayed and all the fields are empty

Is the person writing the test in English expected to

1. write all the expectations in the test action, e.g. "Then the Book Info dialog is displayed within a couple of seconds and all the fields are empty", or
2. write the short statement as in "the Book Info dialog is displayed" but then write an additional document that describes (in English) what is meant by this statement, and what are all the expectations?

Answer 1

In the general case, I'd argue for (closer to) the second.

If you pollute your scenarios with repetitive "noise" by adding assumptions, you've lost the concise, targeted ideal that BDD is aiming to achieve. It also becomes hard to know where to stop.

That said, if your story / scenario has specific requirements around these, or even if you expect it to have an impact on these, there's nothing to stop the addition of addition clauses such as And all input fields are empty.

Remember, if you are using an Agile methodology like Scrum, you'll have a separate Definition of Done which, although more business or process-like, can contain "global" requirements for accepting a story. These may include levels of test coverage, or performance requirements... arguably close enough to what you discuss here.