I am having trouble understanding whether it is considered a best practice to write acceptance criteria in the Cucumber-style given/when/then format, or if there are some scenarios in which this is counterproductive. Let's say my acceptance criteria are that the application should have the same look and feel across multiple devices with different screens, and that it should be mobile-responsive. Should I reword it somehow to fit the given/when/then format?


5 Answers 5



Your underlying issue is not a question of format or style. The real issue is that hand-wavy criteria like:

  • should have the same look and feel across multiple devices

  • should be mobile-responsive

are insufficiently descriptive to guide technical implementation plans and too vague to be testable during development. If you don’t clearly communicate your validation criteria before the development team starts planning the work, you haven’t defined non-subjective acceptance criteria in a way that lends itself to successful feature delivery regardless of whether your framework is agile or not.

This will eventually create problems for the project, especially agile projects that don't rely on exquisitely detailed (but frequently out-of-date as soon as they are written) specification documents. Big, broad, and untestable criteria don't lend themselves to core agile principles like test-first design, small increments of iterative work, or ongoing collaboration and expectation management with stakeholders. By making your expectations more explicit, granular, and testable, you will avoid many of these problems regardless of whether you use Gherkin-style syntax or something else.

Gherkin Syntax is Fine, But Your Acceptance Criteria Need Refinement

[M]y acceptance criteria are that the application should have the same look and feel across multiple devices with different screens and that it should be mobile-responsive. Should I reword it somehow to fit the given/when/then format?

The format you describe is from the Gherkin syntax used by Cucumber to define system behavior or acceptance criteria in something close to natural language, using business terms and a product glossary that fits a specific knowledge domain, company, or product. It is not the only way to define acceptance criteria, but can be a good one especially when coupled with an agile Definition of Done that leads to test-first design and executable tests.

However, your problem here is not about whether Gherkin syntax or Cucumber is suitable for driving your acceptance tests. Your real issue is that, unless they are already clearly defined elsewhere by your project, your "acceptance criteria" aren't properly decomposed or well-defined.

You should decompose the acceptance criteria in whatever format you choose into individual statements using terms and definitions that have been clearly defined for your project. Consider the following worked example.

A Worked Example

In order for acceptance criteria to support test-first design and development, and to fit the Gherkin syntax in a way that can be turned into testable steps, you need to decompose them. Consider the following examples of testable acceptance criteria:

Feature: Consistent Cross-Platform User Interface Elements
  Different platforms such as iPhone, iPad, and desktop versions
  of each application should provide a consistent experience with
  a similar look-and-feel, where each platform contains similar
  widgets, color schemes, and interactive element placement even
  when implemented using responsive design.

  # In Gherkin, the Background keyword is basically common setup
  # for each scenario, rule, or outline for the feature. You may
  # not need this in many cases.
    Given the "standard user interface" for each "target system",
    When the "application is viewed" on each platform
    Then the user interface should "contain similar elements" across platforms.

    Scenario Outline: standard widget images
      Given the application is installed on <platform>,
      When the <widget> is displayed
      Then it should use a <correctly-sized> <image> for the button.

        | platform | widget | image     | correctly-sized |
        |      iOS |  login | login.png |         200x200 |
        |   iPadOS |  login | login.png |         800x800 |
        |    macOS |  login | login.png |       1280x1280 |
Feature: Responsive Design Using Dynamic Image Resizing
      The application should match the sample image in some
      predefined way regardless of screen size or native
      screen resolution.

      Example: iOS  
        Given an "iPhone 12 screen"
        When the application is viewed at "standard resolution"
        Then screen capture should "match the default"

      Example: iPadOS 12
        Given an "iPad 12 screen"
        When the application is viewed at "standard resolution"
        Then screen capture should "match the default"

      Example: macOS Big Sur with 24-inch monitor
        Given "macOS Big Sur"
        And a "24 inch Retina monitor"
        When the application is viewed at "standard resolution"
        Then screen capture should "match the default"
      Example: macOS Big Sur with 27-inch iMac monitor
        Given "macOS Big Sur"
        And a "27 inch iMac monitor"
        When the application is viewed at "standard resolution"
        Then screen capture should "match the default"

You can break these down further if desired, but the point is that you are giving each individual element of your acceptance criteria some testable Definition of Done that can be executed in pass/fail steps. For project management purposes, we don't care what those steps are; that's an implementation detail for engineering. Our goal is simply to communicate those things in a way that is granular, and where the results can be unambiguously defined, such as whether images or HTML markup match expectations within an acceptable range of variance based on the target platform or resolution.

Starting with Gherkin 6, you can also specify business rules using the relatively new Rule keyword. This is really not that much different than regular Gherkin, but allows you to say things like:

Feature: application supports responsive design
  The application dynamically adjusts to changes
  in screen resolution or window sizing.

  Rule: The login button is always centered.
    Scenario Outline: login button is centered
      Screen resolution is measured in pixels, and
      the button's center is the X/Y coordinates on
      screen where the middle of the button is
      regardless of the button's size.
      Given a <screen resolution>,
      When the <button> is displayed on screen
      Then the button should be <centered>.

      | screen resolution | button | centered  |
      |         2388x1668 |  login |  1194x834 |
      |         5120x2880 |  login | 5650x1194 |
      |         2340x1080 |  login |  1170x540 |

  Rule: The cancel button is always below the login button.
    The point here was to show you can have more than one
    business rule. The details don't matter from a project
    management perspective, so I didn't spend time making
    anything up.

Why Decomposition Matters

While the examples above may or may not be what you really need for your specific project, they illustrate a level of granularity and self-explanatory business domain logic that lends itself to an agile test-first approach with a potentially-executable pass/fail test for key elements of your acceptance criteria. Whether or not these particular examples fit your product isn't the point; rather, the point is that without this level of testability you are essentially:

  1. Setting the project up for post facto retcons of what the expectations really were, and thus baking opportunities for bugs, heavy refactorings, or redesign into your work up front.
  2. Forcing the development team and test writers into working more closely with whoever is going to be performing the acceptance criteria, since "same look and feel" and "mobile-responsive" are too vague to guide the implementation details.
  3. Leaving the question of How will the developers know they've met the minimum expectation? unanswered until after the fact. This will create frustration, delays, and morale problems for everyone involved.

Whether or not people decide later that they don't like the implementation, or whether they want additional changes or refinements (which is expected in agile development) is irrelevant. The point is simply to create a working agreement for the current iteration so that the work can be done incrementally, iteratively, and in full collaboration with both the project team and its stakeholders.


Requiring a specific structure for acceptance criteria is often wasteful, so I encourage teams to understand different structures for capturing their units of work, their acceptance criteria, and their definitions of done. Although the given-when-then structure could help a team to make sure that the acceptance criteria are clear and precise enough to act upon, there are edge cases (and you have found one) where trying to force the structure could be more difficult and end up in a loss of clarity. Making sure that the acceptance criteria are easy to read and understand is far more important than sticking to a structure.

In your specific example, conforming to a user experience standard or a design system is a clear need. Responsive design is a well-understood concept. I'm not sure how you could format it in the given-when-then structure without adding verbosity and making it harder to understand what it means for the work to be done and acceptable. However, this could be a good conversation with the team, such as at a retrospective. Present the acceptance criteria in different formats and capture it in a way that helps the team understand what they need to deliver.


Common sense is the best! however, personally, I find checklist pretty helpful... help people to write short acceptance criteria and it helps keeping the testing progress.

Another trick is to ask yourself, what do I want to get from this task? the list of things you want to get is the acceptance criteria.

  • 1
    Common sense does not exist. Aug 8, 2022 at 17:24

I think your example in your OP shows why facilitating tools, such as this, are used. It is not that a requirement should be written this way; it is the way to help write the requirement. When you have a team of various ranks, with various levels of experience and knowledge, that has strategic and tactical thinkers, that may have disrupters among them, and that contains different job functions, the results of your output are very likely to be mediocre. If a facilitating tool such as this helps, then the answer is: use it.


as a high level objective "the application should have the same look and feel across multiple devices with different screens" is fine but not helpful when it comes to actually doing the work.

Regardless of how your stories are written, you need to be explicitly about the look and the feel. This could be done via wireframes or screenshots.

You should also be explicit about the list of supported devices, screen sizes, resolution and versions. Does it include phones, tablets, PDAs, mainframes ? Which browsers and which versions are supported? What happens when bandwidth is restricted, does it work in offline mode? What happens when JavaScript is disabled or not available ?

Answering these questions upfront not only helps the developers but also sets expectations with the customer.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.