Declarative or Imperative? How do you write your feature file scenarios?

BDD is something that I find more and more companies attempting to utilise these days. So with everyone dabbling in writing feature files, I wanted to blog about the differences between Declarative and Imperative writing styles when it comes to writing your scenarios.


Whats the difference?

This is sometimes difficult to explain, but I usually like sticking with the dictionary definitions for each of the words:

  • Imperative: “Giving an authoritative command”
  • Declarative: “The nature of making a declaration”

Lets turn this into some examples as to better understand the meanings in the context of writing feature files…

  • Imperative feature file scenario:

Scenario: Logging in using valid credentials
Given I am on the login screen
When I enter the email address as ""
And I enter the password as "fakepassword"
And I click on the "Login" button
Then I am logged in and see the message "Welcome Dan!"

  • Declarative feature file scenario:

Scenario: Logging in using valid credentials.
Given I am on the login screen
When I log in with a valid email address and password
Then I am logged in and see the welcome message

From these examples, its easy to see that the imperative method offers more details surrounding the actions involved in the scenario and also touches on the functionality/fields involved, whereas the declarative method seems to focus more on the scenario itself, with the actions and the functionality not really being described.

Each way of writing the scenario has its different benefits, mainly depending on who you are writing the feature file for (is it the business? or the development team? hopefully both, right?)

Personally, I prefer to write feature files using the declarative format… Mainly because I like to have the flexibility behind the scenarios and I like to have the flexibility of using different data in my scenarios (which is detailed in the step definitions. I feel that a declarative scenario seems far less brittle and less restricted in comparison to the imperative feature file scenario and it tells the story of the scenario more efficiently too. But there may be times where you want to have the exact data used consistently, and you might need to be explicit about this in the scenario.

Either way, both styles of writing feature file scenarios are acceptable and the better style is completely dependant on your context. Knowing the difference between the two styles will hopefully be helpful in determining which style to use in your context.

4 thoughts on “Declarative or Imperative? How do you write your feature file scenarios?

  1. The trend in companies I’ve been working with (e.g. BBC) has definitely been towards the declarative format for step definitions. The cases where imperative seems most useful to me is where I want to parameterise test scenarios (e.g. use the same test step to try a long input, null input, special characters, etc). Then again arguably these could be different scenarios since they’re different test cases. If I’m writing the feature files (which the developers would implement) it usually comes down to how specific the instructions are that I want to give to the developers 🙂

    Liked by 1 person

  2. We just started with these kinds of tests but already leaning heavily towards the declarative style, stating the WHAT of the test rather than the HOW. Our use case is executable requirements in the regulated clinical trials space (a space you know well @DanAshby). What I like about the declarative style is that it gives me the freedom to create the test with a headless http-client and collect test evidence as a set of requests/responses or I can write step defs that drive a browser. Or I can do both and use the scenario to implement a “testing in depth” strategy. If the test is written “And I click the Login button” then an auditor might expect to see some evidence that a button was actually clicked and that is not the point of the test. But this article was very useful to encourage me to go further into the imperative style and eliminate even more of the “how” so thanks for this.


Please leave a comment!

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s