Acceptance criteria (and other things) for a BDD story

Question

We have a workflow engine that presents a list of available workflows (I mean workflow definitions, not instances) and user can click on the "Execute" link next to any workflow to ,well, execute a new instance of that workflow. I want to do this "execute a workflow" story(feature?) in the BDD way.

    Story: execute a workflow
    Scenario: execute a workflow by clicking on execute link in workflow list and nothing goes wrong
    Given I am a user with sufficient rights
    And I have added a workflow called "wf"
    When I click on the execute link next to "wf" in the workflows list
    When I view the list of workflow executions
    Then the output is:
"""
    1 | wf1 | not started
"""

(1st column: item#, 2nd: workflow name, 3rd: state)

I kinda feel this is more like a mess than a nice cut DBB scenario, I'm specially concerned with the acceptance criteria. My mind is not clear about how exactly I should approach something coarse-grained and user-coupled like "executing a workflow". I mean when it is API you are doing, everything is clear but what if you are describing some behavior which is initiated through (human)user interaction and the result of which is evident from initiating another use-case with complex output (like a list of items). The criteria for knowing that the workflow is indeed executed is to see a new item in the list of workflow executions, which is another story for itself. I kinda feel confused here.

Should I talk to database layer and check for the row that stores the newly created workflow instance -or- should I check for the presence of the item that points to the new instance in the list of workflow executions? If the second, then how exactly? should I check for all columns with correct values in one scenario or each column in it's own scenario?

Answer 1

May I refer you to a post I did quite recently on Acceptance Criteria vs. Scenarios? I think the example might be more illuminating if you use something resembling a specific use of the workflow engine, rather than a generic one. For instance, here's a fake pet shop which I'm using to try out an automation tool. I've then written scenarios around the pet shop, rather than trying to specify generic automation concerns.

If your customers are sometimes in healthcare, for instance, knock up a fake diagnosis tool which uses your engine and write a scenario around that. It might seem like a bit of work to start with, but I've found it pays back for itself very quickly.

Story: A doctor diagnoses black death

Scenario: The doctor starts the diagnosis

Given I am doctor with rights to use the system
And I've added a workflow called "diagnosis"
When I choose the "diagnosis" workflow
Then it should tell me that it's not started.

This is the benefit you're looking for - that a user gets some information, not that something is stored in a database. As far as possible, a scenario should push for the end value! So maybe it should even say something like:

Story: A doctor diagnoses Black Death

Scenario: The doctor starts the diagnosis

Given I am doctor with rights to use the system
And I want to diagnose a patient
When I choose "Diagnosis"
Then the system should prompt me to start diagnosing.
Given that all the symptoms match Black Death
When I perform the diagnosis
Then I should be able to diagnose the patient with Black Death.

Any smaller steps which are needed to make this easy and aesthetic are really usability issues. Don't use BDD frameworks to describe usability concerns (though they can step through them, thus giving you your regression tests). Instead, try it manually. BDD isn't a substitute for manual testing, it just helps out a bit.

If you can create a vaguely realistic use of the workflow engine, it'll help you to think of scenarios which you might miss. For instance, I have no idea right now how this workflow can be associated with a particular patient. I find specific, imaginative examples tend to help people visualise other scenarios more than something vague, generic and all-encompassing.

Also, try phrasing it in the same language the business might use, thinking about the business outcomes that you really want. Try not to think about how to implement the scenario - instead, just write it. This will be much, much easier if you actually go and talk to your business people or customers about the scenarios they can think of!

Any complexity needed to make the scenario run then goes into the code, where it's easier to maintain and refactor.

As an additional benefit, by identifying particular customers with particular needs, you can help your customer avoid the trap of putting every possible feature into the workflow engine "in case someone needs it". By talking through real scenarios with real people, they'll be able to help identify who needs which features the most, reducing scope and helping you to deliver as much value as possible.