The Everything User Story Guide:
Tips and Tricks for Writing Better Requirements

What Are Requirements for Digital Solutions?

In the past, we used “requirements” to describe business needs. This term dates back to the 1960s and was popularized by IBM’s System Requirements Definition (SRD) methodology.

Some maintain that User Stories replace “requirements”. That is not universally true. To explain, we need to understand conventional requirements and the missing perspective that User Stories deliver.

In 2015, the International Institute of Business Analysis (IIBA®) published the Business Analysis Body of Knowledge (BABOK ™ version 3.0) which gives us a common definition of various types of requirements. It distinguishes software requirements by their level of detail:

• Business Requirements (desired business outcome of the digital solution)
• Stakeholder Requirements (features that benefit individuals or groups within the organization)
• Solution Requirements (functional and non-functional instructions for developers)
• Transition Requirements (conditions that must be met to implement the delivered solution)

Read my post Business, Stakeholder, and Solution Requirements vs User Stories for a detailed treatment of the power and limitations of traditional requirements as opposed to User Stories.

Whereas Business, Stakeholder, and Solution Requirements are typically expressed in a simple sentence or phrase, a User Story typically follows the three C’s concept.

User Story Structure: What Are the 3 C’s of User Stories?

User Stories were introduced in a software development method called “eXtreme Programming”.  They were necessary because IT projects were notoriously difficult to scope, estimate, and deliver. The development team created Stories to understand what they needed to build and to prioritize those requirements.

User Stories describe the functionality of a product in terms of three C’s:

• the Card (expressing the business or user need)
• the Conversation (analyzing and collaborating during development)
• the Confirmation (Confirming the results or outcomes based on User Acceptance Criteria)

The Card: Writing the User Story

A User Story describes something that the business community MIGHT want, provided that the development team can deliver it in an appropriate time frame and budget. The emphasis is on simplicity.

The User Story format at this early stage is intended to capture what a certain stakeholder or user in the business community needs from IT, and why.

Why is this called “the Card”? Originally, User Stories were handwritten on one side of a 3X5 index card. The size of the card was deliberately chosen to limit the amount of information that could be captured and to keep the User Stories short and simple.

Although most User Stories in today’s world are captured and maintained digitally, the concept of keeping them short and simple (“handwritten on a 3X5 index card”) is still a fantastic guideline.

The Conversation: Analyzing and Collaborating

The User Story itself is not a requirement but serves as a trigger for a clarifying conversation or discussion between the author and the Agile Team (or developers).

Conversations about the User Story should only occur when the developers are ready to schedule that Story for an upcoming iteration (in Scrum terminology: Release or Sprint). The main thrust of the conversation is to ensure that the developers understand the author’s intent behind the User Story.

The conversation is not a single event. It will happen on an as-needed basis. The product owner, developers, and other stakeholders discuss selected User Stories in detail, analyze them, break them down if they are too big, identify User Acceptance Criteria, and stop only when consensus is reached. Then the developers can start writing code.

Collaboration is the essence of productive teams and without effective facilitation, there can be no collaboration. Having a facilitator on hand should not be your fallback plan. From regular participatory feedback to Agile 3 amigo conversations, effective facilitation can bring out creativity and improve the outcomes.

The Confirmation (or Criteria): Confirming the Results

Acceptance Criteria are the basis for creating User Acceptance Tests which are part of a conversation between business and IT to determine how developers can recognize whether the delivered functionality satisfies the User Story intent.

In the original concept, these were written on the back of the Card. Even when the User Stories are maintained digitally, it is important to maintain the connection between the Story as such (the “front” of the index card”) and the Acceptance Criteria (the back of the card).

The development team uses high-level Acceptance Criteria to decide whether a User Story is ready to be included in an upcoming release. More detailed User Acceptance Criteria are often not defined until a developer starts to work on a Story. Some organizations prefer to write Acceptance Criteria in the Gherkin Given-When-Then format for consistence and clarity (more on that later). 

The User Story Format: On Being a Well-Formed Story

There is a wealth of information available about the User Story format. I will only briefly describe it here. You can find free videos with detailed explanations in my KnowledgeKnugget™ library.

A User Story must answer the question: WHO wants WHAT and WHY?

 Any User Story format must name:

• The ROLE the author represents (answers the WHO component)
• The OUTCOME or action (answers the WHAT part)
• The BENEFIT or business value (answers the WHY dimension)

For example,

As a traveler (the role this individual plays when starting this interaction),
I can select the lowest fare flight that meets my travel needs (the outcome the role desires)
to save money (the value the role receives).

This User Story example answers all three questions:

Who requests something (ROLE – in this example a traveler)?
You want the role—not a job title—this person plays in the Story. If you would like more information on how to identify and model user roles, please watch my video: How to Define User Story Roles: User Role Modeling, Persona Development, and Stakeholder Identification.

What does the requester want (OUTCOME – selecting the lowest fare)?
It’s important that the User Story expresses WHAT the author wants. For more detail, watch our free KnowledgeKnugget “A User Story Expresses WHAT, Not HOW!“.

The outcome of the User Story can be qualified. In our Story, “lowest” is a qualifier. You can use anything that will restrict or clarify exactly how the Role or Persona wants to have or know something. 

Why is this outcome important (BUSINESS VALUE – to save money)?
A good User Story will clearly outline the benefits of this feature to the ROLE (user) and why they want it. The business value helps both end-users and technical teams have better conversations. If developers understand the “Why” or business value of a User Story, they can create better software solutions.

The User Story Format Is Flexible

You do not have to follow a strict pattern like, “As…, I can…, to…”. As long as all three questions—Who wants to do what, and why—are answered, you have a valid User Story structure.

Here is another User Story Example:

“As a Sales Manager, I can get a monthly report of customer complaints to review the performance of my Sales Reps.”

We have worked with companies that write simple sentences answering the WHO, WHAT, and WHY. They call them User Stories. Other organizations still use the term “requirements” but follow the User Story format.

Here is the same User Story Example expressed in a goal-focused User Story format:

“To review the performance of their Sales Reps, Sales Managers can get a monthly report of customer complaints.”

Limitations of the User Story Structure

A digital solution is a complex endeavor involving many stakeholders. Although user functionality is important, it is only one facet of the solution. Many stakeholders within your organization have a voice in what they want the technology to accomplish.

On the business side, we are talking about executives who approve initiatives and special interest groups (Audit, Legal, Compliance, etc.) who make legitimate demands on any digital solution.

On the technology side, there are other groups (Infrastructure, Data Administration, Security, etc.) that ensure that any digital solution meets technical and organizational standards.

Strong proponents of the User Story structure argue that most (if not all) of these considerations can and should be expressed using the User Story format.

For example:

As database administrator, I can see thrashing issues to ensure the application meets our performance standards.

Whether you express these non-user stakeholder requirements in User Story format or any other format, make sure you capture them somehow.

The INVEST Model: A Powerful Guide for Writing Good User Stories

Creating User Stories is relatively easy; the basic structure is straightforward. However, writing good User Stories can be a challenge.

Fortunately, Bill Wake—the creator of the INVEST model—supplies guidance on how to write effective User Stories. You can use this mnemonic (INVEST) to remember six characteristics that good User Stories possess to guide you in creating your own.

 A Good User Story Is Independent

The “I” stands for Independent, meaning each User Story should be self-contained to avoid dependencies on other User Stories. This does not mean that Stories cannot have prerequisites.

However, it should be possible for a developer to code the Story, test it, and release it into production without having to depend on other Users Stories working first. Obviously, this should be taken with a grain of salt, but every User Story should be as independent as possible.

A good litmus test for this principle is to ask yourself, “If you drastically alter this User Story, would any of the other Stories be invalidated?”. If you do find that your User Stories are dependent upon one another, combine them into larger Stories or isolate the dependence into its own User Story.

A Good User Story Is Negotiable

The N stands for Negotiable. This is a key criterion in Lean and Agile development environments.

Many Agilists are not fans of the term “requirements” because it has a negative connotation. “Requirement” sounds so authoritative—so “this is how you are supposed to do it!” We do not treat User Stories as rigid requirements.

Supporting business agility is one of the big drivers for the Agile movement allowing and even encouraging changing requirements for digital solutions. There is no promise that a User Story in the Backlog will ever be implemented as is.

User Stories can always be changed or rewritten up until the point of coding. Once the team has started coding a Story, change becomes expensive and should be avoided.

For example, a Product Owner might negotiate the scope and Qualities of a User Story on the fly because of pressing business needs. To support this, your User Stories should never be so detailed or restrictive to prevent your team from arriving at the best solution. Capture the intentions but leave enough room for team discussion.

A Good User Story Is Valuable

V is for valuable. Remember when I introduced the User Story format (Who, What, Why) earlier? I wrote that a User Story always must deliver on the value that the role in the User Story needs.

A significant benefit of having the business value as part of the User Story is that it helps everyone on the team better understand what success looks like for this Story—and if the team does not know what success will look like, then how can they know when they have achieved it?

A Good User Story Is Estimable

Good User Stories are also estimable. This is a major challenge because a User Story should be written from the business perspective whereas estimating the size of a Story is something that the developers need to do. They must estimate how much time it will take to develop the code for this User Story.

This means, that every User Story must have enough information to make a reasonable estimate of the Story’s complexity. However, when we talked about “Negotiable”, we learned that a Story should not have too much detail as to restrict the developers in solution finding or restrict the business community from changing the Story.

This is where you need to find a good balance. Write your User Story with just enough detail for the team to understand what they are building and why. Err on the side of not enough information. If the Agile team cannot estimate a User Story effort during Release Planning, they will talk to the Product Owner or author until they can.

A Good User Story Is Small

Good User Stories are small. They hold just enough information to get a software engineer started. Small in this context means it is at a size that a developer can code within a few days or a single Sprint at the most. It should never take more than two weeks to complete the coding.

When a User Story is too large (i.e., an Epic) it must be broken down into multiple smaller Stories. This process is called splitting or breaking down the User Story. Later in this post, I will add some tips and tricks on doing that.

A Good User Story Is Testable

The T stands for Testable. In Lean/Agile approaches, we have finally recognized that Acceptance Test Scenarios derived from Acceptance Criteria ARE the real requirements that IT needs.

Scenario languages like Gherkin express the business need in a manner that developers can more easily digest. Creating User Story Acceptance Criteria (whether in the form of Scenarios or any other form) before writing the code is critical for the success of Agile/Lean undertakings.

In the last section of this post, I will give you a few suggestions (and links to free videos) on how to write good Gherkin Scenarios. Writing good Test Scenarios in the Gherkin Given-When-Then format is becoming a pre-requisite for anyone in charge of communicating business needs to IT.

Once you have started writing User Stories, you will have a lot of them—a Backlog full of them. What do you do next?

User Story Elaboration Requires Excellent Communication Skills and Analysis Techniques

The next challenge for agile teams is to continuously break down, refine, and elaborate User Stories. In this case, “continuously” means different things at different times during the software development lifecycle. For example, it can mean:

• Refining the Product Backlog at the end of each sprint
• Analyzing and sizing a User Story during release planning
• Adding detail to a User Story as the conversation between developers and end users unfolds
• . . .

User Story elaboration and analysis tasks can be the most difficult to master. To successfully navigate this stage, you need two distinct sets of skills:

• Communication skills
  (after all, the most important thing about a User Story is the conversation)
• Many different business analysis techniques, tools, and tricks
  (Story decomp and splitting, Acceptance Criteria definition, Acceptance Test creation, etc.)

The importance of communication skills is often underrated. The fact is, good communication skills can make or break your product or application.

Good Communication and Facilitation Skills Are the Key to Productive Agile Meetings and Workshops

Collaboration, collaboration, collaboration. That is the name of the game in Lean and Agile software development philosophies. Collaboration is a core principle and effective meetings are an essential part of collaboration.

When you are in an Agile meeting or workshop,

• you are collaborating with your team members
• you have conversations with them about how to do better next time
• you make decisions together about what is best for your customers and business as a whole

That is the power of User Story collaboration: working together toward a common goal.

Workshops are by nature collaborative, but not all meetings are. However, all forms of Agile meetings are collaborative. They both have the same purpose: to discuss and decide!

Collaboration is what makes Agile work so well. It’s what makes workshops such an important part of modern software development methodologies.

For example, consider three common types of meetings in an Agile environment:

• a large User Story Workshop to seed or replenish a Product Backlog
• a 3-Amigo conversation to discuss a User Story for imminent development
• a 1-on-1 interview with a domain expert to clarify a volatile function or User Story

All work towards a specific result or outcome. Each requires a certain amount of collaboration to achieve that goal. Communication skills help you understand people’s motivations so that you can work together more effectively. The difficulty often rises when we are trying to reach agreement.

We have all been there. A group of people get together with a loose agenda and no leader, so the meeting devolves into a chaotic mess of conflicting ideas, tangents, and side conversations that go nowhere.

It is frustrating for everyone involved because it seems like such a simple thing to do: just get everyone in one place, let them talk about what they want to do, then use whatever comes out of that discussion to make good decisions.

But this is like trying to untangle Christmas lights without scissors—you are guaranteed to fail. The only way it works is if you have someone there who knows what they are doing and takes charge of the whole thing.

Regardless how many people attend a meeting,
someone must shape and guide the process of collaborating
to meet the goals and accomplish what the meeting is designed to do.

The group can set the agenda and figure out the goals, but someone during the meeting needs to concentrate on following the agenda to achieve the objective. That is the role of the “Facilitator” and different participants may assume that role from one agenda item to the next. Even within the same meeting.

User Story Conversations and Workshops Are Not for the Weak of Heart

But being a facilitator can be frustrating. Participants don’t always agree on the agenda, concepts get sidetracked, and the conversation goes in circles.

The situation is complicated by the fact that each person has a different personality, and each personality requires a different approach. We live in a world where aggressive and straightforward people often get their way, while the more reserved, equivocators, and passive aggressors are often pushed aside.

Managing these situations can be tricky for even the most experienced individuals. Pile virtual meetings on top of face-to-face meetings, and you have a recipe for chaos. While there is no way to avoid meetings if you intend to collaborate with others, you can make your life easier by developing the following three skills:

• Plan and prepare for the workshop/meeting so that it runs smoothly
• Know how to conduct the workshop/meeting so that it gets results
• Realize that it is not over when it is over (a good follow-up is essential for a successful workshop/meeting)

Since People Skills and Facilitation is such a big topic, I will save it for another post. However, if you are interested in learning more about these topics, please check out my course How to Facilitate Agile Meetings and User Story Workshops”.

Here are two previews from this course:

• How to Prepare and Start Face-to-Face or Virtual Requirement Meetings Effectively
• Creative Collaboration Is at the Heart of an IT Business Analyst’s Day

Now that we have covered communication and facilitation skills, let us turn our attention to the next skill set you need during the elaboration stage: breaking User Stories down!

User Story Decomposition: How to Break Down Epics, Features, and User Stories

The decomposition and functional analysis of User Stories is a vital skill that you need to master to succeed on your projects. User Story decomposition is the process of drilling down into User Stories to specify low-level functionality.

When elaborating User Stories, the agile team has two main tasks:

1. Splitting or right-sizing User Stories and Epics
2. Writing User Acceptance Criteria

Epics are very large User Stories that are simply too big for a single release or sprint.

Breaking down User Stories into smaller pieces makes them easier for developers to understand, prioritize and implement. It also helps you identify areas of uncertainty so that you can ask questions, do research, and clarify what you need from the product owner while writing User Acceptance Criteria.

This process is commonly known as User Story splitting or Story slicing. A User Story’s size is contingent upon several factors, including team experience and velocity, as well as iteration length. Ideally, User Stories should be roughly the size of what the development team can accomplish in one iteration.

Splitting User Stories is a core competency for any Agile team, but also for members of the business community. To be effective, Story Splitting should be a group effort.

Read my post “8 Techniques for Splitting User Stories” to learn a few simple techniques to break down User Stories followed by a short description of more advanced techniques.

Acceptance Criteria: The Secret Weapon to Writing Great User Stories

User Stories are great, but they are not enough. They do not have enough detail to tell the technical teams exactly what they need to do to make sure the Story is done and how to know when they are done.

Acceptance Criteria fill in that gap.

They are like the fine print on a package of cookies: It can tell you the ingredients and how you can make them. The fine print in the context of Acceptance Criteria, however, is a series of details buried within each User Story—those short descriptions of what a user wants to do.

Acceptance Criteria are functional and non-functional items that flesh out the details of how the solution will accomplish its goal. Together, they make up the “terms and conditions” that developers need to know before they start coding. With these terms and conditions in hand, developers can make something awesome—but when it comes to User Stories and their Acceptance Criteria, the fine print can be daunting.

For Many Developers Acceptance Criteria ARE the “Real” Requirements

Projects succeed or fail based on the ability of the team to meet their customers documented and perceived Acceptance Criteria. When you clearly define the Criteria up front, you avoid surprises at the end of a sprint, or release, and ensure a higher level of customer satisfaction.

When you are writing Acceptance Criteria for a User Story, your goal is to clearly express what you expect the result of that Story to be. The Criteria are also your opportunity to communicate any assumptions or non-obvious factors that might not have been clear in the description of the story. When defining them, think about two questions:

1. What is the desired outcome of this Story?
2. What are some possible ways the Story could get accepted?

Types of User Acceptance Criteria: Functional Requirements vs Non-Functional Requirements

User Acceptance Criteria can be broken down into 2 distinct categories, functional and non-functional. Criteria that are aligned with a specific business feature or requirement are functional because they relate directly to the primary purpose of the software.

Functional Story Criteria focus on what the software should do, and do not include any information about how or why. Acceptance Tests are one way to ensure that these Criteria are met. 

Non-functional Story Criteria describe how or why the software will work. They may address things such as performance, security, usability, and other factors that affect how well the system functions but are outside of its primary purpose. Non-functional ACs often come from requirement documents, technical specifications and other artifacts that describe more than just what the system does.

Acceptance Testing ensures not only that the code functions as expected, but also that it is secure, accessible and efficient, and that the User Experience is seamless.

Why are Acceptance Criteria Important?

Criteria exist to focus our conversations with developers on what is really important—the functional and non-functional specifications of the User Story. They help ensure that you are building the right thing, based on feedback from stakeholders and users.

Acceptance Criteria also act as a safety net for the team, ensuring that there are no gaps in coverage when implementing a Story, ensuring that everyone is on the same page, and ensuring that there are no missing steps in how a Story will be implemented.

Furthermore, User Story Criteria ensure that there is enough detail for developers to be able to reliably estimate how much work a task will take and for project managers to schedule tasks accordingly.

How to Write User Story Acceptance Criteria?

The first question when writing Acceptance Criteria that comes to mind is: “Which format should I use?” This is a tough one to answer. Unless you work in an organization that has established its own custom format, it is hard to tell which format to apply since there are many.

Some companies use checklists, others Gherkin Given-When-Then Scenarios, some have Business Rules, others functional feature lists. Some have a mix them.

Your approach to writing Acceptance Criteria will also depend on what kind of Acceptance Tests the team needs. If you are automating your tests with Cucumber or another automated testing tool, you will most likely write them in the Gherkin format. I will tell you more about the Gherkin language in the last section of this post.

Functional Requirements AND Non-functional Requirements Make Great Acceptance Criteria

Breaking a User Story down into its functional and non-functional components (a.k.a. Functional Decomposition) is a great technique for developing User Story detail.

It means dividing a User Story into smaller Stories or tasks. It is like zooming in on the big picture until you can see what is really going on. You may think that a Story is complex, but by viewing it as an interconnected series of smaller steps, you can see its complexity disappear.

At this stage, you are not yet talking about how to build the system or what technologies you will use; instead, decomposition focuses on translating user needs into Functional and Non-Functional Requirements (or Solution Requirements in IIBA terminology). As stated above:

• Functional Requirements describe what the software should do
• Non-Functional Requirements describe how the software should be

This technique is particularly useful for software developers trying to build out complicated new features or applications, but it also has some implications for business analysis and design.

To understand Functional Decomposition and how it works, Angela and I dedicated a full section of our course “How To Write User Stories That Deliver Real Business Value” to this topic. It is full of real life examples.

User Story Functional Decomposition: A Simple Software Requirements Specification Technique

Functional Decomposition is not a new concept. It sounds technical, but it is simple and something you are probably doing without even realizing it. Think of Functional Decomposition as a method that takes a User Story and breaks it down into all of its parts:

• Functional Requirements encompasses Functions the solution will perform and related Data the functions consume and create
• Qualities (Non-Functional Requirement), which define the characteristics and properties the digital solution must have
• Constraints (Non-Functional Requirement), which are absolute limitations, rules, laws, and environmental factors that must be considered in any solution.

The fundamental distinction between Qualities and Constraints is what happens if they are not implemented.

• If a Quality Requirement is not met, the Stakeholder is dissatisfied with the solution
• If a Constraint is violated, the solution cannot be implemented

Because of that distinction, you should focus on discovering as many Constraints as you can as early as possible to avoid rework or risk failure.

If you want to learn more about Functional Decomposition, what it is and how to do it, read my post Functional vs Non-Functional Requirements – How to Write FRs & NFRs. It describes in detail and with real-world examples some tips and tricks that can be used to quickly determine functional and non-functional requirements. For many FREE how-to videos and articles browse the blog category “User Stories”.

Defining Non-functional Requirements (Qualities and Constraints)

Now that you have specified the functional requirements, i.e., things the software will do (functions) and information it needs or creates (data), we will examine the other part of requirements at a solution level: the Non-Functional Requirements (NFR). Sometimes called Quality Requirements, Qualities or Constraints, these are attributes of a solution that measure how well the software works.

Missing and misunderstood Non-Functional Requirements are often to blame for the failure of products and projects. In the annals of IT projects, there are many examples in which applications have implemented every single defined requirement. They did it well enough to fulfill those requirements, but not well enough to satisfy customers’ demands.

When the Obamacare website went live, millions of Americans tried to log on to the site. The high demand caused it to crash, and even when it was working, the wait times were measured in hours. The website’s failure was due to a lack of attention to Non-Functional Requirements. It could process applications as soon as they were submitted; it just took too long to get there. Only after months of rework and fine-tuning did the website start to gain customer confidence.

The NFRs that matter for the entire product should be defined at the outset of an initiative. The NFRs that are unique to a Story or feature should be identified during an iteration as it is being developed.

Here are a few Non-Functional Requirements examples:

The nuclear power plant radiation monitor must be available 24/7/365.

This NFR implies that the function must never fail. Considering the gravity of the situation, should it ever fail, this is probably a rather sensible request on behalf of the business community. This is an example of a category of NFRs dealing with the RELIABILITY of the solution.

The next example is technical in nature, as it lists mandatory technologies required for enforcing access control:

The access must be controlled with retinal scan, fingerprint identification, and voice recognition.

Qualities and Constraints do not just apply to functions. They can also affect the data, as you can see in this Non-Functional Requirement example:

A customer ID must be a unique (meaning non-recurring), 15-digit (the specific length), positive (cannot be below 0), real number (cannot be an irrational or an imaginary number) that identifies a single customer

Types of Non-Functional Requirements

To help you get started, here are four types of Non-Functional Requirements with their subtypes.

External Constraints
Digital solutions do not exist in a vacuum. There are many external forces that can influence or pose limitations on your product. Each of those are external Constraints and I can only give you some general groupings to think about:

• Natural Limits Enforced by Nature
• Laws and Regulations Enforced by External Agencies
• Policies and Rules Enforced by the Organization
• Security: Limiting Access and Protecting Data
• Distribution of Function and Data

Performance Requirements
In the performance category, there are limits to the speed and efficiency of the application and the entire business solution. The main problem with performance is not the difficulty in achieving it, but the cost of measuring it. Modern applications can achieve amazing levels of performance if they are necessary, and if the business is willing to pay for them.

• Frequency: How Often Is the Feature Used?
• Urgency: Response Time vs. Update Time
• Volume of Information
• Precision and Currency of Information

User Experience Requirements
The User Experience is a non-functional dimension that has become ever more critical with the advent of the WWW. This is where technology meets real people and, like any touch point between opposites, it can be tricky. Many of your Non-Functional Requirements will come from this category. You might discover User Experience Requirements regarding your users’ abilities, their location (where will they use the application), their training needs, or maybe their cultural needs and desires.

• Level of Interaction
• Corporate and National Cultures

Architectural Capabilities
If the application is web-based, does it have to be responsive to every device a user might use, such as a smart phone, tablet, PC, Laptop, etc.? Again, the answer is simply one of money as the more devices your application needs to support, the more it will cost. The architectural capabilities of Non-Functional Requirements deal with the ability of the application to react to changes in its business and technological environment. This includes changes in the hardware capabilities, software, competitive environment, or any combination of these.

• Maintainability
• Portability
• Scalability
• Availability
• Reliability

User Acceptance Testing (UAT) Is More Important Than Ever Before

In the past, User Acceptance Testing (UAT) has been seen as one of those things that you could maybe squeeze into your schedule if you had time to spare. It was a little extra step in the development cycle just before you launched the product.

In short, UAT suffered from a lack of respect and attention; it was often treated like a necessary evil. But times have changed, and UAT has evolved.

User Acceptance Testing is more important than ever before. Why? Because increased competition means that companies can no longer afford to take risks with their customers’ satisfaction—if they do, they will quickly become obsolete.

It is now vital for businesses to be able to provide their customers with new features on a regular basis. Those new features could mean higher sales numbers and more happy customers, but they will only happen if you can deliver them when they are needed.

For that reason, in modern development approaches, Acceptance Testing is an integral part of the process and not an afterthought. However, the intent remains the same: verifying that the software meets customer and end-user expectations.

Acceptance Criteria vs Acceptance Tests: What is the Difference?

As I stated earlier, Acceptance Criteria are the conditions that need to be met to accept a User Story as complete; they guide developers during design and coding; they are also used by business stakeholders and the product owner to agree on what the team should build.

Acceptance Tests are scenarios which are derived from Acceptance Criteria. In other words, each Acceptance Criteria can have one or more Acceptance Tests. They prove that the delivered solution does what was agreed upon in the Acceptance Criteria.

For example, if you are testing a car, you might have an Acceptance Criterion that states “the car must be able to drive on all roads without breaking down.” You could then have several Acceptance Tests such as driving on a dirt road at 40mph or driving on a highway at 80mph.

Now that you understand what Acceptance Criteria and Acceptance Tests are, let us look at a wide-spread technique that you can use to create either one – Gherkin Given-When-Then Scenarios.

Using Gherkin Scenarios for Acceptance Criteria and/or Acceptance Tests

Given-When-Then Scenarios are a great way to help your team think about and create Acceptance Criteria or Tests. Using the Gherkin syntax is a best practice for describing the business logic of your application. Scenarios provide context by detailing how users will interact with the product or application.

The simplicity of the Gherkin language enables business teams (e.g. Product Owner, SME, end-user, Business Analysts, etc.) to document Acceptance Tests in a language that the business community, developers, and testers can all understand. This promotes collaboration and mutual understanding of the required user tests.

The Gherkin syntax, also known as Given-When-Then, is a narrative format for specifying functional behavior of software. It consists of three parts:

Given (the precondition), When (the action), Then (the expected outcome)

GIVEN-WHEN-THEN is one way to ensure everyone understands exactly what’s needed before they start working.

• GIVEN sets the context for what must happen before the Story can begin
• WHEN defines the event or act that triggers the scenario
• THEN defines precisely what happens if the scenario is successful

When writing the GIVEN, you should provide all the setup data required for a successful test. This includes hardware conditions as well as data that must meet certain criteria to perform the test.

WHEN defines all events that trigger the Scenario. It is the interaction between a stakeholder of the system and the system itself.

For example,

if you are working with a website, WHEN lists stakeholder interactions with the site—i.e., “Enter a value” or “click a button.”

However,

if you are working on an API (Application Programming Interface), then the interaction might be “call API” it—in this case, it is an internal interaction between parts of code as opposed to an interaction with an external stakeholder.

Finally, THEN defines the results or outcomes that determine whether a test was successful. If the conditions in the THEN clause are met, the test succeeds; if not, it fails. This can be a calculated result of some specific value, but it can be any other verifiable outcome.

What Is the Cucumber BACKGROUND Statement?

Sometimes you realize that several SCENARIOS require the same setup conditions. This is where the Gherkin language comes in handy; it provides a simple solution that saves you time and effort. With the BACKGROUND keyword, you can define setup criteria for a group of Scenarios.

Gherkin BACKGROUND keywords are prefaced by the word “Given”. All Gherkin statements between the BACKGROUND statement and the first SCENARIO will be executed as the first step for each SCENARIO in a Feature file in which Scenarios are stored.

Here is a Gherkin User Story example using Given-When-Then and BACKGROUND:

User Story:

To plan their career development paths (WHY), students (WHO) can view classes (WHAT) they still need to take based on their BASE scores (QUALIFIER).

Scenarios:

To reduce redundancy, I used two set-up conditions in a BACKGROUND statement. The first indicates that Fred must be logged into the website, and the second states that he must have completed the Business Analysis Skills Evaluation (BASE) test.

• In our first Scenario, Fred requested a class schedule and had unfinished classes. The desired outcome in that situation is to show the class schedule / customized training plan.
• In the second Scenario, Fred requests a class schedule and has NO unfinished classes. The desired outcome here is to offer a certificate of completion.

Scenario Outlines with Example Tables to Quickly Test Data Variations

What happens if we want to test a Scenario several times with different data? Do we have to create a Scenario for each data set? That would be a lot of wasted effort – definitely not LEAN!

This situation is extremely common in testing. Typically, a single test is insufficient to prove that the application reacts as we intended. We need to prove that the application reacts correctly under a variety of circumstances.

Rewriting Scenarios with many different data values quickly becomes tedious and repetitive. Scenario Outlines together with Examples reduce this effort considerably.

A Scenario Outline also uses the Gherkin syntax. However, it uses variables instead of constants to allow for the execution of a multitude of tests with a single Scenario statement. It avoids constant values like “Fred”, but instead refers to a “Person” or “Name”.

The Scenario Outline is followed by an Example Table that contains the various values assigned to each variable. Each row in the Example Table represents a single test.

Last Thoughts

User Stories are a powerful form of collaboration. They were specifically designed for communicating business needs to developers by replacing unneeded documentation with essential conversation. In my opinion, the power of the User Story paradigm is best summed up in two User Stories:

As a Domain Expert, I can express my business needs in my own words to ensure that developers deliver what I need.

And

As a developer, I can maintain an ongoing conversation with the Domain Experts to ensure that my solution satisfies the intent behind a User Story.

If you can implement those two Epics, your digital solutions will be aligned with your customer’s needs and desires to ensure a successful delivery.

Please share your experiences below: what worked, what didn’t and why. We all learn from each other!