How to describe expected error messages in BDD / Gherkin

We are just getting started with BDD in our company, and we are currently trying to write our first features. We have created something like the following:

Feature: There can only be one
It is important that there is only one Highlander in the system for a given time period.

Scenario: Inserting a new Higlander for a time period already taken by another 
Given there is a Highlander Adam in the system for time period 1820-1900
When I insert a Higlander Bert for time period 1800-1900
Then the System raises Error Code "ONLY1"  

Scenario: Inserting a new Higlander for a free time period
Given there is a Highlander Adam in the system for time period 1820-1900
When I insert a Higlander Bert for time period 1901 - 1902
Then the System raises no Error

My question ist about the error code (ONLY1) in the first scenario. Currently, our system raises many errors, but we do not have a simple way to identify a specific error condition. Our System ist more than 15 years old. Isn't it funny that we havn't found this to be an issue for so many years? I find it great that BDD makes it so obvious that we need a clear, shared language to identify our error messages.

Some of my colleagues argue that there is no need for an error code. This means that we have to write the assertion like this:

Then the System shows the error "There can only be 1 Highlander for a given time period."

This makes me cringe, because

The test will break if we later decide to change the text to something else
The test will only be successful on the english version of the software (we support several languages)
An error Code is great for finding information in a knowledge base or in suppoert tickets.

Of course, we should show the error code and a readable description of the error in the users language, but in the test spec, I would prefer to only mention the error code.

How do you test for errors? do you use codes or exceptions or just plain text?

Best Regards Mat

Solution

Speaking strictly from a BDD persepective, you want to stay focused on the behavior that is expected. Keep your tests devoid of technical details. That being said, error codes are technical details. When trying to adhere to BDD, avoid error codes in your feature files. Put the error codes in your step definitions instead.

User friendly error messages are a little different though. An error message shown to an end user is not a technical detail in the same sense as an error code or enum. It is something that an end user should understand. If they do not understand the user friendly error message, then it is not user friendly and should be rewritten until it is. So your example below is perfectly valid BDD:

Then the System shows the error "There can only be 1 Highlander for a given time period."

You should also understand the drawback to this approach. Any change to the message terminology means you need to update all tests that reference this message. While putting the message in your features might not violate BDD, it does make your test suite more labor intensive to maintain. A better assertion captures the essence of the behavior without requiring the scenario author to know the exact details of the user interface:

Then the system says there can only be 1 highlander

The step definition is then free to use error codes, enums or UI error messages as part of the assertion. This provides a layer of abstraction between the implementation and the description of the behavior. A functional change to the UI or code that does not affect the overall behavior can be fixed in one spot.

Check out BDD 101: Writing Good Gherkin for some good guidance.