Scenario Outline: Placeholders with a restricted number of possible values

Question

I am relatively new to BDD and I have a question regarding scenario outlines. When looking at samples over the internet I have the feeling that the placeholders can take any values. The number of elements in their domain is not restricted. Here is one example:

Scenario Outline: eating
  Given there are <start> cucumbers
  When I eat <eat> cucumbers
  Then I should have <left> cucumbers

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

The placeholder <start> for example can be any number so the number of values is infinite.

In my specs I have to deal with contracts which can have one of four states (planned, ongoing, paused, and closed). My specs say that I can edit planned contracts but I am not allowed to edit contracts which have one of the remaining three states.

I think I would write a scenario named "Updating a planned contract" and one scenario outline where the status of a contract is a placeholder.

Scenario: Update a planned contract
  Given the list of contracts as follows
    | name | status  | some value |
    | c1   | planned | 123        |
  And I have edited contract c1 as follows
    | field      | value |
    | name       | c1    |
    | some value | 456   |
  When I save contract c1
  Then the list of contracts should be as follows
    | name | status  | some value |
    | c1   | planned | 456        |

Scenario Outline: Update contract
  Given there is a <status> contract
  And I have edited that contract
  When I save that contract
  Then I an error 'only planned contracts are allowed to change' should be displayed

  Examples:
    | status  |
    | ongoing |
    | paused  |
    | closed  |

Is that the right way? One expicit scenario and one parameterized? Or should I write the scenario outline as explicit scenarios for each possibility? I am not sure because the status of a contract is restricted by four possible values as opposed to the examples on the internet.

Answer 1

One thing I find that helps is to remember that Gherkin is just a syntax for Specification by Example. You are trying to provide the examples that make most sense to you in the business domains language.

As such, what you are proposing is perfectly valid. You have one example of a scenario that uses tables to define what happens when a planned contract is edited, and another set of examples that produce errors when contracts in other states. You could also do it explicitly by expanding the outline for each state. Both are valid, and you can always refactor your feature sepcifications as you would the codebase.

What you are aiming to do here however is to provide a grammar, a framework, a language, call it what you will, that you can use to have conversations with your business analysts. You want to be able to pull out this document and say "This is how the system works now, how do we change this to make it support your new feature?".

Personally, I'm avoiding tabular and outline forms in my features right now as I want to make it look as friendly as possible to all I show it to, and as yet, my features are still easy to describe.