Tuesday, March 13, 2012

Acceptance Criteria and UI Controls

Lately, I've been working with some newer team members who haven't done user stories or acceptance tests before. Figuring out the best way to break up stories or write the tests leads to some good discussions where I have to think carefully about the Whats and Whys.  Like today.

Today, I saw that someone had created a story specifically to say that there would be hover-overs on such-and such screen. I pointed out there were already three stories for the functionality the hover-over would present.  "But, if I don't do that," my teammate said, "Then I have to write acceptance tests in each story for when the hover-over appears and when it goes away and I don't want to do that. This way, I only have to write those tests once."

Well, no. You usually don't need to write any stories or tests for GUI widgets, technical elements or UI controls, you only need to focus on the business aspects.

The user may have personal preferences or expectations about how a UI may work, but generally, those are unspoken assumptions. The user really cares about achieving some goal and the precise set of tools is incidental. Will there be a picklist or radio buttons? A field that you type in or a calendar widget?  A single field for phone number or three fields?  In each case, the user doesn't really care as long as the interaction delivers the desired results, reduces the likelihood  of mistakes, and minimizes their effort. 

Generally, whenever the UI is using a known convention, the user story is about the goal and not how the system lets the user achieve the goal: "As a user, I want to enter a phone number so that ...." "As a user, I want to enter a date range, so that ....."   "As a user, I want to select X, ....."

Aside from setting out acceptance criteria for specific business requirements like default selections and required fields, we don't have to write explicit tests for types and behavior of controls; we assume behavior like "the radio button shows as selected when you click it" or "the droplist retracts when focus moves away" are well-tested already.  Of course, the dedicated QA always does a sanity check for correct UI behavior but acceptance tests are meant to be somewhat less than that -- just enough testing to prove that the business logic is correct so that the application can be deployed for production or for more rigorous testing.

Once an application establishes a convention for doing something, if there is a change in UI technology, then we want to write user stories and acceptance criteria in order to track that the technical change is planned for and will not adversely affect the business.

For example, when Ajax came along, a long-running application that I worked on underwent a significant facelift on certain pages to take advantage of the technology. In those cases, we had specific user stories that sort of went like this "as the system, I want to use Ajax to look up X...."  The acceptance tests spelled out that we would see a spinner before that section of the page refreshed. And no surprise, we did find that some things on those pages were broken after we made the change.

For our project today, we are adding completely new functionality. There is no existing UI to break and the user will not have to get over any previous training or expectations about the UI. We plan to use hover-overs but hover-overs or the alternative to show/hide fields when the user clicks into a row are known conventions. Therefore, we don't have to have a separate user story that says "..... use hover-overs on screen X",  instead, we just need separate stories for the business goals -- edit, delete, shorten URL, etc.. 

As part of the story details, or as a comment in the screenshot, it is fine to say something like, "Assume the use of hover-overs to show/hide the edit link." or "This story will use hover-overs to show/hide the link."

Within the acceptance tests, we only need a test that says "When I put focus on a list entry, I will see a link to do X."  We don't need a test to say the link is hidden when we move off the row, although the obsessive test-writer is always free to add that or expand the first test to say that.

It's the simplest way we can write the stories to convey the objectives.