Lean Requirements with User Acceptance Test Cases

The Agile Manifesto extols the virtues of working software over documentation as a true measure of progress and business value. Teams in the early stages of agile adoption sometimes misinterpret this to mean that they should not write anything down.  Other teams that are accustomed to waterfall and documentation-heavy methodologies continue creating extensive and redundant documentation under the guise of User Stories and Acceptance Criteria.

Lean Agile Requirements is a middle ground that provides a framework in which complex requirements are captured in living documents that speak to many audiences and serve a purpose beyond the initial development of the application. The flow for discovering and capturing these requirements in the process of developing new software appears in the diagram below.

User Story Writing Workshop

Product Owners, business representatives, and the development team meet to identify user stories. User roles are identified and a couple of sentences are written to describe the goal and value of each story. Stories are mapped into releases and become the basis of the product backlog.


Grooming conversations occur at regular intervals in advance of the sprint in which a story is actually turned into software.  In grooming, a user story may just contain a couple of sentences describing the feature increment.  Each story is discussed and the UI might be sketched on a whiteboard or in a UI mockup tool. Acceptance criteria also may be identified – these are high-level user acceptance test cases (hint: these are not detailed tests, yet) but are only discussed/captured to the extent needed to size the story.

Sprint Planning

Sprint planning conversations are where the team starts to think in more detail about how it will build the feature increment described in a story. The discussion becomes more detailed but it is important to avoid getting into too much detail too soon (e.g. avoid things like “Should we show transactions that are less than or less than or equal to the Invoice Date?”). Any details that do surface can be captured as the initial User Acceptance Test Cases but they are not always necessary at this point. The technical design is reflected in the tasks and estimates that the team creates. Note that the user story itself does not need to contain any of this additional detail.

What is a User Acceptance Test Case?

Acceptance Test Driven Development (ATDD) is based on the premise that one of the most effective ways of communicating requirements is by understanding how the user will use/test a feature and the expected results.  Acceptance tests avoid many of the pitfalls of business rule statements because they eliminate the layer of interpretation and ambiguity involved in understanding the outcome of a business rule in various scenarios.  Writing these tests is as simple as asking the user “What tests will you run to validate this feature?”  The test cases capture the user’s actions and expected results using real examples as much as possible. For the developer, it is like having the answers to an exam before taking it.


When the team has pulled a user story into a sprint, the first step in working on the story is to meet with the users and detail the user acceptance test cases. This is when and how detailed requirements and behaviors are captured.  Note once again that the user story itself does not need to contain any of this detail. The detailed user acceptance test cases are then used by developers, QA staff, and users to create and validate the working software.

Requirements Life Cycle in Support


Once the feature is deployed to production, bug reports that are handled as support tickets may uncover additional user acceptance test cases. As the one living document that the team maintains, the user acceptance test cases are updated as the software evolves.  They are used to run regression tests to make sure that other functionality is not impacted by the defect correction.

By capturing complex requirements in the form of user acceptance test cases, the team can build and maintain a product with the confidence that the user’s needs are being satisfied.

Are You Being Agile or Doing Agile?

The GoalThe starting point for adopting agile is for a team to learn the mechanics of an approach such as Scrum.  They write user stories instead of use cases, do daily standups dutifully, and replace their lessons learned meetings with sprint retrospectives. Eventually the rest of the business comes on board, and the Product Owner takes over writing the user stories and maybe even attends the retrospectives. The product backlog gets populated in time for the next sprint planning session.  The team might spend some time talking about some of the upcoming stories before the next sprint.

A novice golfer often focuses too much on swing mechanics and less on the desired end result of putting the ball on the target.  In doing so, he is “doing golf” rather than “playing golf” and his improvement typically plateaus at a mediocre level. Agile teams can also plateau and fail to realize the full potential of an agile approach by “doing agile” rather than “being agile”.  Here are some of the smells of teams that are doing agile:

Detailed user stories

One of the principles of the Agile Manifesto is that “the most efficient and effective method of conveying information to and within a development team is face-to-face conversation.” Product owners who are accustomed to waterfall methodologies may still be tempted to put all of the requirements in the user story rather than using stories as placeholders for conversations with the developers.  Detailed user stories are both inhibitors to conversation and wasteful since it makes more sense to capture detailed requirements as test cases.

Obsession with metrics

The first step in replacing traditional project management methodologies with agile approaches to is to stop equating hours worked with progress.  In agile, stories that are “done” are the only true measure of progress. As such, it can be very tempting for an organization to put emphasis on user story completion rates as a key metric for judging the performance of agile teams. The danger is that when a team is considered a failure if it does not deliver 100% of planned stories for every sprint. The natural reaction is for the team to work very hard to eliminate all uncertainty and risk before starting a sprint. This can quickly lead to a culture of big, detailed user stories and excessive story grooming and sprint planning efforts in order to eliminate all possibility of not delivering 100% of stories in the sprint. In extreme cases, a team may spend an entire week planning a 4-week sprint!

Fear of building features over many sprints

The misconception that it is best to develop an entire feature in one fell swoop may still be present in some organizations.  Usually the rationale is something along the lines of building the entire feature in a single sprint makes the process more efficient by only having to test it once.  This misses the point of agile, which is to build feature and product increments, learn from user feedback, and make adjustments by adding to the feature in subsequent iterations. This brings to mind the old adage “Users don’t really know the requirements until they fail to be met by the software.” But what about having to regression test as increments are added?  Automated testing can eliminate alot of that effort.

Stories not considered done when new requirements discovered

New requirements will surface as the software comes to life in a sprint.  That’s good!  The key is recognizing these new requirements as new user stories rather than as defects that must be corrected in order to consider the story “done”. This requires strong trust between the users, Product Owners, and development team to recognize that the new requirements were not factored into the story sizing for the current sprint (remember – requirements are not detailed before starting a story).  If team starts to feels like story is a lot bigger than what they thought when they sized/estimated it, this culture of trust allows for a new user story to be created to handle that additional work in a subsequent sprint.  The “doing agile” version of this is where CYA kicks in and the Product Owner and team members run for cover to avoid the organizational fallout from additional work coming out of a sprint.


  • Being agile allows a team to focus on building great software that delights customers rather than merely creating the illusion of progress.
  • Just like becoming a great golfer, this is often the most challenging part of an agile transition.