Using Gherkin To Write Accessibility Tests

By Gemma Pitman | 2nd November 2017

Behaviour Driven Development (BDD) is a software development methodology used by lots of Agile teams. It allows both technical and business stakeholders to easily understand product requirements. Gherkin is 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).

Accessibility acceptance tests can come in many different forms. Some are technical and require the tester to look within the source code itself, which is traditionally known as white box testing (although I find that term quite old fashioned), whereas others are purely related to how a user interacts with the product (which is traditionally know as black box testing).

This blog post briefly discusses how and when it is appropriate to using the Gherkin syntax as a way of writing accessibility tests.

Prior knowledge

This post is not going to explain what Gherkin or BDD is, however there are many resources online which can give you a basic understanding of it. Some of my favourites are:

Practical guidance

When is gherkin an appropriate tool?

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

Here are some examples where it would be appropriate 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

The previous example demonstrates how easy it is to use Gherkin to write an accessibility scenario. 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 the code has been marked up to meet accessibility standards.

In the teams I’ve worked with, we’ve always 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 type.



Did you enjoy this blog post? If so, let me know by emailing me or tweeting @openforaccess

Find out more about what Open Inclusion does and how we can help you on your accessibility journey