Using Gherkin To Write Accessibility Tests

Accessibility acceptance tests can come in many different forms. Some are technical and require the tester to look within the source code itself (traditionally known as white box testing). Others are purely related to how a user interacts with the product (traditionally known as black box testing).

While many automated accessibility tools exist for white box testing, finding efficient ways to do black box accessibility testing is often harder to achieve.

Behaviour Driven Development (BDD) is a software development methodology already used by lots of Agile teams. It allows both technical and business stakeholders to easily understand product requirements. Gherkin is a business-readable, domain-specific language that lets you describe software’s behaviour without detailing how that behaviour is implemented. It is a popular choice for defining user acceptance test scenarios, and integrates easily with many automation frameworks including Ruby/Cucumber, PHP/Behat and .NET/SpecFlow (amongst others).

This blog briefly examines the benefits of using Gherkin syntax as a way of writing accessibility tests, and how and when to best do that.

Prior knowledge

This blog isn’t going to explain what Gherkin or BDD is, as there are many resources online which can give you a basic understanding of them. Some of my favourites are:

Practical guidance

When is Gherkin an appropriate tool?

As a rule of thumb, Gherkin is most appropriate for scenarios which relate to user behaviour, and so don’t require someone to look at the actual code behind the scenes.

Here are some examples where it would be appropriate and easy to use Gherkin for your accessibility scenarios:

Scenario: Skip to content link
Given I am on the homepage
When I select the ‘Skip to content’ link
Then the main content has keyboard focus

Scenario: Video captions
Given I am on the video page
When I select the ‘play’ button
And I turn on captions
Then the correct closed captions display throughout the video

If you do choose to use this approach, there are several benefits for the team:

  1. It creates a uniform approach to writing acceptance tests – your accessibility scenarios are written in exactly the same way as all of your other functional scenarios.
  2. If you already have an automation framework or a manual test case suite in place, Gherkin scenarios are easily integrated into your current framework and approach. This brings with it the possibility that your accessibility tests could form part of your regression test suite, and test runs can be recorded in your test case management system.

When is Gherkin not an appropriate tool?

However, as I have previously mentioned, not all accessibility tests are suitable for Gherkin, notably the more technical ones. Here are some examples of when Gherkin may not be an appropriate tool to use:

Scenario: Anchor tags
Given I am on the home page
When I inspect the source code
Then each anchor tag has the href attribute

Scenario Outline: ARIA landmark role
Given I am on the [type] page
When I inspect the source code
Then the main content has the landmark=main ARIA markup
Examples: of pages
| type        |
| sign in   |
| account |

Scenarios written using Gherkin describe user behaviour. The previous example is not describing user behaviour, therefore Gherkin is not an appropriate tool in this specific instance.

Another important thing to consider, is that there are numerous automation tools, libraries and APIs already available (including aXe, Pa11y, Google Accessibility Tools) which can be used to check whether code has been marked up to meet accessibility standards.

In the teams I’ve worked with, we’ve often used Gherkin for the tests which aren’t already covered by such tools, and utilise the automated tools to cover the tests which are easily automated.


If your team is already using Gherkin as a tool to write your user acceptance tests, then there’s absolutely no reason why you can’t use it to write your accessibility acceptance tests as well.

However, if you aren’t using Gherkin already, and are using a different tool which works for your team, don’t feel like Gherkin is your only option. The key thing to remember is that when you write your accessibility acceptance tests, try and use the same approach and tools that you are already using within the team. Accessibility tests are no less important than any other type of test.

What do you think?

We hope these insights are useful to you, and would love to hear your experiences around implementing accessibility tests in Gherkin. Please share your comments below.

Want more?

If this blog has been useful, you might like to sign-up for the Hassell Inclusion newsletter to get more insights like this in your email every month.


Steve Lee says

Excellent Idea (and I love the names cucumber and Gerkin). While I’ve never used either I appreciate the concept and have had evaluation on my ToDo for much to long a time!

I’m also very impressed with which is aimed at a more technical audience and have thought of exploring it for similar evaluation.

Happy New Year!

Joshua Randall says

You could re-write the technical tests to be more user focused. For example,

Scenario: anchor tags
Given I’m on the home page
When I select a hyperlink
Then I am navigated to the link’s target

Scenario: ARIA landmark role
Given I’m on the account page
When I use my screen reader to list landmark regions
Then I the following are listed
(list of regions)

Given I’m on the account page in the MAIN region
And the account page has the following regions (list of regions)
When I use my screen reader to navigate to the next region
Then I am navigated to the FOOTER region

Jonathan Hassell says

Thanks for the comment, Joshua. We totally agree. Thanks for your contribution.

Kimmy says

Hello there,

Sorry, I’m totally new to this and I have a few questions regarding writing test cases for websites. How do you break up the stories when it comes to ADA? In other words, if a webpage has a Global Header with sign in buttons, social icons, log in/sign up, and site nav links, would each one be a story or would it be just one giant test?

Also would the navigation(for navigating in the correct order, focus, and when selecting a button be separate tests?

Thank you in advance for reviewing!

Jonathan Hassell says

Hi Kimmy,

Thanks for your comment. It’s a little too detailed to go into here, but send us an email via our contact us page and we can give you some pointers.



Darian Rashid says

Great blog and great information.

Reply to this thread

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.