Whose domain is it anyway?

The brittleness of tests or specs is a recurring topic in BDD (or acceptance test-driven development, specification-by-example, or whatever you choose to call the thing where you write acceptance criteria, automate them and then make the application match). This is a tricky area, and there are probably as many styles of defining and grouping acceptance criteria as there are teams automating them.

The aspect I want to focus on in this article is domain language, because there’s a failure mode I encounter surprisingly often, which seems to have a common root cause.

Here’s an example:

Story: User logs in

[Narrative about why a user should have to log in]

Scenario: User with valid credentials

Given an unauthenticated user
When the user tries to navigate to the welcome page
Then they should be redirected to the login page
When the user enters a valid name in the Name field
And the user enters the corresponding password in the Password field
And the user presses the Login button
Then they should be directed to the welcome page

It seems innocuous enough. It’s a scenario about logging in, a common feature on a web app, but let’s take a look at the vocabulary in use here. We can see language from a number of different domains:

  • Words like unauthenticated, valid, credentials are from the domain of security, more specifically user authentication.
  • Words like name and password are from the subset of that domain concerning password-based authentication.
  • Then we have words like enters, field and button. These are from the domain of UI widgets.
  • Finally we have login page and welcome page. These are from the domain of web assets.

Imagine we’ve delivered this feature and the scenario works as described. Now what happens if we go from password-based authentication to OpenID, or a centralized authentication system (CAS) model? This would obviously break the scenario. The requirement for a password becomes redundant so we would naturally expect to have to rethink the scenario. Alternatively what if we change the UI so the name is now selected via a drop-down list or a radio button? The scenario breaks again, because there is no longer a Name field to enter a value. And again, what if we change the site navigation strategy and decide that a successful login should take you to the Dashboard page, bypassing the Welcome page? Once again we would need to reword the scenario.

If you are thinking this is starting to look like a bit brittle, then you are right. We’ve made the mistake of combining too many domains into a single scenario – an indicator that we are overspecifying something – which makes the scenario vulnerable to change along a number of axes. We’ve created accidental complexity because we lost sight of the intended audience of the scenario.

Unpacking the domain

Let’s think about this for a moment. The intent of the scenario is that a user with valid credentials can gain access. That entire sentence lies in the domain of user authentication, so we could ask someone from that domain whether the premise of the scenario is correct. (Are valid credentials enough? Should we also require a physical token? Can credentials expire?) In general, any domain will map to a single subject matter expert, who we can call the stakeholder or representitive for that domain. In fact it’s a circular definition: a domain is simply the “subject” in the phrase “subject matter expert,” so for any given domain we should be able to identify a single stakeholder who represents that domain.

As an aside, this raises some interesting questions. What if you are writing scenarios in a domain that no-one seems to care about? (You can tell by watching their eyes glaze when you talk about it.) A lot of what we traditionally call non-functional requirements can fall into this category. For instance, most non-technical people aren’t interested in networking terms like latency, throughput or packet loss, but they might perk up when you start talk about sluggish response times or requests going missing. You can use the glaze test as a heuristic to know if you are talking to the wrong person – or using the wrong language. Similarly, if you can’t the answer the question “who cares about this requirement?” with an actual name, you either have a redundant requirement or a missing stakeholder.

But back to our login story. Every domain we include in a scenario potentially pulls in an additional stakeholder, whose requirements or priorities might change at any time. So to avoid a scenario becoming brittle we want to involve the minimum number of stakeholders we can get away with. The simplest useful scenario should involve exactly two domains – and therefore only two stakeholders – namely the domain of the scenario title (the problem domain, or the what) and the domain of the steps (the solution domain, or the how). We can’t have fewer than two domains. If we exclude the problem domain we aren’t explaining the value, or the intent, of the scenario. If we exclude the solution domain the scenario can’t describe the behaviour we want from the application. But any additional domains are likely to provide unnecessary constraints or noise, and make the test brittle. (When I talk about the solution domain, I mean the “outermost” solution domain – the solution’s interface if you like – as opposed to the domains of any of its implementation details.)

The what of our example scenario is logging in with valid credentials. The how is using a name/password pair to validate the user. The details of the how with its button clicks and whatnot aren’t adding any value to describing the capability we want. So maybe we could convey the same intent by rewording the scenario like this:

Scenario: User with valid credentials

Given an unauthenticated user
When the user tries to access a restricted asset
Then they should be directed to a login page
When the user submits valid credentials
Then they should be redirected back to the restricted content

Now we have exactly two domains, namely the “what” of user authentication (words like unauthenticated, user, credentials) and the “how” of web-based security (words like restricted asset, submits, redirected, content). If either of these domains changes then we would expect the scenario to change too. If we decide valid credentials are no longer enough we’ll probably need to add some more steps. Or if we decide to turn the app into a thick client then there will no longer be a login “page” so we might need to change that step to be a “modal dialog” or “screen” or something else thick-clienty.

Notice how we don’t explicitly say what it means to “submit valid credentials.” We’ve pushed this down into the implementation of the step. If we were to change the authentication model, say from name/password to OpenID, then the scenario would break, which we want (the implementation of the how has changed) so we would change the implementation of the step “the user submits valid credentials” to provide an OpenID URL rather than name/password pair, say.

But the wording and sequence of the scenario itself wouldn’t change because the intent is still the same and the behaviour is still the same – it’s the implementation of the behaviour – corresponding to the step’s implementation – that has changed, and that shouldn’t affect the meaning of the scenario.

Chunking – or the myth of “declarative”

Neuro-linguistic programming (NLP) describes a technique called chunking, that’s useful for either solving problems or creating options. For any statement, you can chunk up by asking “Why..?” or “What for..?” questions and chunk down by asking “How..?” questions. The further you chunk up, the broader your perspective becomes, and the further you chunk down, the more detailed. The power of chunking comes when you start to chunk sideways, by asking “How else..?” questions.

For instance with our login scenario, we could chunk up with: “What are you logging in for?” Perhaps it’s to restrict access to premium content, or for regulatory reasons. If it’s the former we could chunk sideways with: “How else could you restrict access?” Perhaps we could filter on IP or MAC address, or use cookies, or single sign-on. Then we can chunk down again to consider solutions: “How could we filter on MAC addresses? What new security issues could this raise?”

Once you realise you can ask “What for?” or “How?” at any layer of abstraction, concepts like “declarative” or “imperative” suddenly become relative. Any layer is the what of the layer below, and the how of the layer above. SQL is often described as a declarative language: you describe what you want to select but you don’t tell the database how to find it. However, the statement select employee_id, salary from employees where salary > 100000 could equally be considered imperative, a command, if the “declared” requirement is “find all employees paying higher rate tax” (tacit knowledge: higher rate tax kicks in at 100k), which itself is an imperative implementation detail if the original request is “establish our income tax liabilities by rate type.”

Be deliberate in your use of domain language

So tying this all up, when writing your scenarios keep in mind that you are writing them for two audiences: the person the feature is for and the person implementing it. Check the wording to see if you can spot anything from neither the problem nor the solution domains. If you find you are using language from outside those domains, you might be over-specifying the implementation or specifying unnecessarily broad requirements that mix concerns.

If you really care about how the behaviour is implemented, you should probably be specifying that elsewhere in a more fine-grained story – in other words chunking down to provide more detail – that won’t be interesting to the audience of this one. If not, you might want to push the detail down into the implementation of the steps.

25 comments

  1. Oh, I very much like that chunking bit, it looks like that’s a useful thing to improve questioning domain experts and especially driving them mad with alternatives ;)

    As to your scenario, asset and content seem to be the same thing, and since there seems to be an implicit web scenario, maybe both should be replaced with resource…

  2. [...] Dan North wrote a lengthy article on how to write stories, making a similar [...]

  3. [...] Whose domain is it anyway? (Dan North) [...]

  4. Interesting post covering something that those of us who use acceptance testing should pay greater attention to.

    One question though:

    “Notice how we don’t explicitly say what it means to “submit valid credentials.” We’ve pushed this down into the implementation of the step. If we were to change the authentication model, say from name/password to OpenID, then the scenario would break, which we want (the implementation of the how has changed) so we would change the implementation of the step “the user submits valid credentials” to provide an OpenID URL rather than name/password pair, say.”

    What happens if you allow *either* username/password credentials or OpenID? Would you need to change the level of granularity for the step in the feature (say “When the user submits valid credentials” becomes “When the user submits a value username and password combination” in one scenario and “When the user submits valid OpenID” in another scenario? Or would you approach it another way?

    1. +1 to Anthony’s question, as I’d like to hear Dan’s thoughts. My initial impression is that by eliminating the login guru stakeholders from the example story, we are now freed up to write mutually exclusive features to address the concerns of different stakeholders who do care about the details of offerign OpenID and/or user/passwords. (Would that be a “chunk sideways”?)

      Dan, this was really a terrific post, thank you for sharing your insights! A lightbulb went off as I read, “any layer is the *what* of the layer below, and the *how* of the layer above.”

    2. Hi Anthony.

      Good question, and of course it would vary with context. When this scenario was written, you can imagine the stakeholder probably didn’t care much how the user logs in, just that an unauthenticated user can’t see the good stuff. As soon as we start introducing options for authentication, the details of authentication suddenly become interesting. (For instance, which OpenID servers are we going to honour?)

      At this point I would expect this scenario to be augmented with some finer-grained, or lower-level, scenarios, each describing the different kinds of authentication we support. These new scenarios would be aimed at a different stakeholder. The person who cares about whether you can log in is probably a content owner or editor somewhere. The guy who cares about how you authenticate might be an infrastructure or security admin. The latter is likely to want you to explicitly enumerate and demonstrate the various ways you can authenticate.

      Of course there’s no reason it shouldn’t be the same person – but they will be wearing different hats (i.e. have different responsibilities) in the different conversations.

  5. This is a terrific treatment on the subject, Dan — thank you.

    I found invoking the notion of domains as sets of terms and the concerns they bring is illuminating. I am working on a series of articles about appropriate use of Cucumber and have wrestled with this very topic ( http://software-as-a-craft.blogspot.com/2011/01/relishing-in-perfection-iii-writing.html ) … and I picked that title for the blog before your hit-by-bus-with-dirty-underwear incident ;). The way I’ve articulated it is, “write Features as if you’re the Business Analyst”. The way you have distilled it down the number of domains being invoked deepened my own understanding.

    The chunking technique as a means of navigating around layers of abstraction is super helpful. I’ve awkwardly been using this technique (without the name or full understanding) when encouraging guys to write meaningful comments (“get to the ‘why’ that adds additional context, repeating what’s in the code is noise…”). Having grasped the NLP-sourced technique you describe in this article is making plain what I’m doing (and now I have more degrees of freedom in this space… cool!)

    I love the “eye glaze” test… something that applies in tons of situations; and here’s a practical application.

    Again, thank you.

  6. Mike Sassak · ·

    +2 for “unpacking the domain”, but -1 for “chunking”.

    I don’t see how describing what a scenario lacks in terms of chunking this way and that is an improvement over saying it needs to be more declarative or less imperative, or that it uses weak verbs, etc. Speaking of steps in terms of declarative and imperative wasn’t, so far as I know, intended to be an absolute measure of anything, but to point people toward a better way to communicate intent with their team members. Chunking seems like a step backwards. BDD is about getting the words right (right?), but “chunking” just sounds like jargon.

  7. In December 2010 I attended a meetup about BDD. We had a short introduction and a small practical example (done by me). You find it in my blog: http://mgryszko.wordpress.com/2010/12/19/refactoring-bdd-scenarios/

    My initial scenarios, prepared for the presentation included terms from the UI widget domain (button, confirmation message) and web domain (list page). But the common opinion was that scenarios was that they should be technology agnostic. A scenario should be executable in a web environment or in an IVR system (no screens, only voice guidance).

    We started refactoring the scenarios. You can find the final result in my blog.

    After reading your post I started to doubt: should scenarios be really technology- agnostic? Should the include any of solution domains?

    In your example, do the words “enters”, “field” and “button” belong to web assets domain either? In an IVR system you would have any field of button.

    I’m confused…

  8. Nice article. Well done! Thanks Dan

  9. Mind = Blown.

    Thanks Dan, you found a pain point I’ve had with out-of-control BDD for a long time now and didn’t know how to express.

    1. Hear, hear!

      Dan, you’ve definitely picked a great topic to discuss here. I find people have a lot of trouble keeping implementation out of problem definition. This post not only demonstrates that it is valuable to separate them, but that the separation leads to much more pithy and cogent specifications/examples.

      Thanks a mil’ for providing us the tools to explain these ideas to others.

  10. Tim Coote · ·

    Dan
    The type of issue you’re identifying here feels very similar to Cockburn’s points about writing effective usecases. For ucs it’s partly helped by the overall structure of the set of ucs and Cockburn’s use of ‘levels’ (sky-> sea level -> pelagic, or similar iirc). Is there a comparable structuring that’s used for BDD?

    Do you use BDD to drive tests for the interactions between components within a ‘system’ (eg the end to end set of transactions from the ATM to the backend systems that manage account balances and that need to be integrated with). In my experience, it’s the integration points that cause much of the grief in larger systems. And the issues are both functional and non-functional.

    In fact, downstream component changes are one of the biggest causes of business pain and suitable test harnesses to simplify component replacement would be very valuable, although quantifying the value would require some sort of ‘technical debt’ analysis.

    Tim

  11. [...] tests have a plain-English abstraction on them, they can be less brittle (although see this blog post by Dan North for more on [...]

  12. [...] campaign against imperative Cucumber stories in favour of declarative stories (see especially Dan North’s great article on domain languages), I’ve been trying to get more naturalistic language into my stories. However, it becomes [...]

  13. [...] Przeczytaj: http://dannorth.net/2011/01/31/whose-domain-is-it-anyway/ . Testy akceptacyjne powinny być pisane w języku domenowym, zrozumiałym przez użytkowników i/lub analityków biznesowych i/lub product ownera. [...]

  14. [...] in thinking is due in part to Liz Keogh’s Step Away from the Tools and Dan North’s Who’s domain is it anyway?. Both of these got me thinking about how I’m using the term BDD (rather loosely) and how much [...]

  15. Si Garnett · ·

    Dan,

    When you say…

    “The intent of the scenario is that a user with valid credentials can gain access”

    …I think you’ve not gone far enough (and thus have not taken your own point to it’s logical conclusion)…

    Actually the intent of the scenario is that a user who really is a user can gain access; such that your next scenario might be “a bogus user cannot gain access”. The “valid credentials” part is yet more domain jargon.

    The business doesn’t really care about ‘credentials’ – what they actually want is for the right people to see the right stuff and other people not to see that stuff. The term ‘Credentials’ is just a an abstraction of Username+password/OpenID or what ever your solution of choice might be.

    You can obviously take this too far…

    I want the right people to see the right stuff

    — chunk up —

    I don’t want to be sued

    — chunk up —

    I don’t want to be fired

    — chunk up —

    I need an income

    So clearly you need to find that sensible level of abstraction so you can still give your scenario/step context.

  16. Dan, the GBC/ACM (Greater Boston Chapter of the ACM) would like to do a seminar on BDD in the late fall or spring.
    We are a non-profit educational organization for software.
    It would probably be a 1 day (Saturday) or a 2 day (Saturday – Sunday) at either MIT or Harvard.
    We are hoping that attendees would come away with the ability to apply BDD when they return to work.
    Would you be interested in doing this, or can you recommend someone ?

  17. Scott B · ·

    I have been building a “BDD framework” ever since i saw rBehave demoed at Red Hat here in Raleigh a few years ago. Something caught my attention on another blog this evening so I drifted back this way. I am glad I did.

    Dan, your post here hits at the core of what I have been working on since that presentation in applied enterprise systems. I have been specifically concerned with taking your ideas and handling domain vernacular, rather than, the functional test automation since that is the “easy” part. Since I work with cognitive engines, computational linguistic frameworks, and things like SNOWMED-CT I have some unique techniques to bring. My goal was to have a BDD that adapted to ever changing business processes (mergers, retooling, etc) around it up into management layers and across longitudinal “Ux” (story maps with context centered user testing and validation)

    Part of my problem is explaining “this” cascading abstraction models with full object orientation to people in any business domains.

    This post really helps me simplify that story. And I love that Neuro-linguistic programming (NLP) is also Natural Language Processing (NLP). Since we work with serious NLP engines, this confusion in and of itself makes for a great point of reference.

    Thank again.

  18. Dan, Its being almost a year you haven’t update your blog, are you publishing somewhere else or what ? :)

  19. Thank you for a very informative and interesting post. One question though: What would be a valid credential? The authentication process seems to be complicated though but will be very useful in giving access only to authenticated users. No matter how the user logs in as long as he enters a valid credential, then he’ll be able to see the page’s full content.

  20. [...] our understanding of scenarios in the following articles: http://dannorth.net/whats-in-a-story/ and http://dannorth.net/2011/01/31/whose-domain-is-it-anyway/. And finally, the BDD tool SpecFlow (http://specflow.org) inspired us to explore the usefulness of [...]

  21. [...] our understanding of scenarios in the following articles: http://dannorth.net/whats-in-a-story/ and http://dannorth.net/2011/01/31/whose-domain-is-it-anyway/. And finally, the BDD tool SpecFlow (http://specflow.org) inspired us to explore the usefulness of [...]

  22. [...] BDD was arriving at a common domain language that everyone could understand. See Dan North (http://dannorth.net/2011/01/31/whose-domain-is-it-anyway/) for a wealth of interesting information on this. Our early uses of BDD fell into the common trap [...]

Follow

Get every new post delivered to your Inbox.

Join 469 other followers

%d bloggers like this: