Accessibility testing
Automated accessibility testing (a11y) checks your pages against rules derived from the Web Content Accessibility Guidelines (WCAG) and accessibility best practices.
In a Selenium test on TestingBot, calling tb:accessibility with executeScript runs the axe-core engine on the page the browser has open and returns its result to your test. There is nothing to install in your project.
Because the scan runs on the current page, you can log in, open a dialog or fill in a form first, and scan the page in that state.
Example
The following example will start a browser in the TestingBot browser grid, navigate to a website and call the custom tb:accessibility command to fetch the accessibility results.
We will then retrieve the results from the accessibility test from inside our automated test. The results will be saved in a JSON file for inspection.
#!/usr/bin/env ruby
require 'rubygems'
require 'selenium-webdriver'
options = Selenium::WebDriver::Options.chrome
options.browser_version = 'latest'
options.platform_name = 'WIN11'
options.add_option('tb:options', { 'name' => 'Accessibility Test' })
driver = Selenium::WebDriver.for(
:remote,
url: "https://api_key:api_secret@hub.testingbot.com/wd/hub",
capabilities: options
)
driver.navigate.to "https://testingbot.com"
result = driver.execute_script('tb:accessibility')
require 'json'
File.write("path/to/report.json", JSON.generate(result))
driver.quit
import com.fasterxml.jackson.databind.ObjectMapper;
import org.openqa.selenium.*;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.io.FileWriter;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.HashMap;
import java.util.Map;
public class AccessibilityTest {
public static final String KEY = "api_key";
public static final String SECRET = "api_secret";
public static final String REMOTE_URL = "https://" + KEY + ":" + SECRET + "@hub.testingbot.com/wd/hub";
public static void main(String[] args) {
WebDriver driver = null;
try {
ChromeOptions options = new ChromeOptions();
options.setBrowserVersion("latest");
options.setPlatformName("WIN11");
Map<String, Object> tbOptions = new HashMap<>();
tbOptions.put("name", "Accessibility Test");
options.setCapability("tb:options", tbOptions);
driver = new RemoteWebDriver(new URL(REMOTE_URL), options);
driver.get("https://testingbot.com");
JavascriptExecutor js = (JavascriptExecutor) driver;
Object result = js.executeScript("tb:accessibility");
Path outputPath = Files.createTempFile("accessibility-report", ".json");
try (FileWriter writer = new FileWriter(outputPath.toFile())) {
writer.write(new ObjectMapper().writeValueAsString(result));
System.out.println("Accessibility report saved to: " + outputPath.toAbsolutePath());
}
} catch (Exception e) {
e.printStackTrace();
} finally {
if (driver != null) {
driver.quit();
}
}
}
}
<?php
require_once('vendor/autoload.php');
use Facebook\WebDriver\Remote\RemoteWebDriver;
use Facebook\WebDriver\Remote\DesiredCapabilities;
$capabilities = DesiredCapabilities::chrome();
$capabilities->setCapability('platformName', 'WIN11');
$capabilities->setCapability('browserVersion', 'latest');
$capabilities->setCapability('tb:options', ['name' => 'Accessibility Test']);
$web_driver = RemoteWebDriver::create(
"https://api_key:api_secret@hub.testingbot.com/wd/hub",
$capabilities, 120000
);
$web_driver->get("https://testingbot.com");
$result = $web_driver->executeScript('tb:accessibility');
file_put_contents("path/to/report.json", json_encode($result, JSON_PRETTY_PRINT));
$web_driver->quit();
?>
import json
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.browser_version = 'latest'
options.platform_name = 'WIN11'
options.set_capability('tb:options', {'name': 'Accessibility Test'})
driver = webdriver.Remote(
command_executor='https://api_key:api_secret@hub.testingbot.com/wd/hub',
options=options
)
driver.get("https://testingbot.com")
result = driver.execute_script('tb:accessibility')
with open("path/to/report.json", "w") as file:
json.dump(result, file, indent=2)
driver.quit()
const { Builder } = require('selenium-webdriver');
const fs = require('fs/promises');
const TESTINGBOT_KEY = 'api_key';
const TESTINGBOT_SECRET = 'api_secret';
const capabilities = {
browserName: 'chrome',
browserVersion: 'latest',
platformName: 'WIN11',
'tb:options': {
name: 'Accessibility Test'
}
};
async function runAccessibilityTest() {
let driver;
try {
driver = await new Builder()
.usingServer(`https://${TESTINGBOT_KEY}:${TESTINGBOT_SECRET}@hub.testingbot.com/wd/hub`)
.withCapabilities(capabilities)
.build();
await driver.get('https://testingbot.com');
const result = await driver.executeScript('tb:accessibility');
const filePath = 'accessibility-report.json';
await fs.writeFile(filePath, JSON.stringify(result, null, 2));
console.log(`Accessibility report saved to ${filePath}`);
} catch (error) {
console.error('Test failed:', error);
} finally {
if (driver) {
await driver.quit();
}
}
}
runAccessibilityTest();
using System;
using System.Collections.Generic;
using System.IO;
using Newtonsoft.Json;
using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;
using OpenQA.Selenium.Remote;
namespace SeleniumTest {
class Program {
static readonly string report = @"path/to/report.json";
static void Main(string[] args) {
var options = new ChromeOptions();
options.BrowserVersion = "latest";
options.PlatformName = "WIN11";
options.AddAdditionalOption("tb:options", new Dictionary<string, object> {
{ "name", "Accessibility Test" }
});
var driver = new RemoteWebDriver(
new Uri("https://api_key:api_secret@hub.testingbot.com/wd/hub"),
options
);
driver.Navigate().GoToUrl("https://testingbot.com");
var result = driver.ExecuteScript("tb:accessibility");
File.WriteAllText(report, JsonConvert.SerializeObject(result, Formatting.Indented));
driver.Quit();
}
}
}
What the scan checks
-
Engine: axe-core 4.11.1. Without options it runs its default rule set: the WCAG 2.0 and 2.1 level A and AA rules and axe-core's best-practice rules. axe-core ships its WCAG 2.2 rule,
target-size, switched off, so a default scan does not run it. To include it, pass the WCAG 2.2 tag as shown under Options. -
Iframes are not scanned: the scan covers the top-level document only. To check content in an iframe, such as an embedded form, open the iframe's URL in the browser and call
tb:accessibilitythere. - One page state per call: the scan checks what is in the page at that moment. Call it again after opening a menu or dialog, or after navigating.
Options
Pass an options object as the second argument of executeScript to choose which rules run and which part of the page is scanned.
Without an options object (or with an empty one) the scan runs as described above.
| Option | Value | Effect |
|---|---|---|
runOnly |
A list of axe-core tags, such as ["wcag2a", "wcag2aa"], or { "type": "rule", "values": ["image-alt", "label"] }
|
Runs only the rules with one of these tags, or only the listed rules. Rules that are off by default, such as target-size, run when you list their tag or rule id. |
rules |
{ "color-contrast": { "enabled": false } } |
Switches single rules off (or on). Only enabled is accepted per rule. |
include |
A CSS selector, or a list of CSS selectors | Scans only the matching elements, for example "main". |
exclude |
A CSS selector, or a list of CSS selectors | Leaves the matching elements out, for example a third-party chat widget. Works with or without include. |
Tag and rule names are the ones axe-core uses; the rules overview lists the rule ids.
A list holds at most 100 entries and a selector at most 1000 characters.
An unknown option or a value of the wrong type fails the command with an invalid argument error that names the field, and no scan runs.
This example runs the rules tagged wcag2a, wcag2aa, wcag21a, wcag21aa and wcag22aa (the last one adds target-size) and skips a chat widget:
const result = await driver.executeScript('tb:accessibility', {
runOnly: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'],
exclude: ['#chat-widget']
});
result = driver.execute_script('tb:accessibility', {
'runOnly': ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'],
'exclude': ['#chat-widget']
})
Map<String, Object> options = new HashMap<>();
options.put("runOnly", Arrays.asList("wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"));
options.put("exclude", Arrays.asList("#chat-widget"));
Object result = ((JavascriptExecutor) driver).executeScript("tb:accessibility", options);
Automated rules cover only part of WCAG 2.2, so a scan without violations does not mean a page meets it; see what automated checks don't catch.
Results
After running the example test, you will find a report.json file with the results of the accessibility test.
The file will contain the following structure:
{
"testEngine": { },
"testRunner": { },
"testEnvironment": { },
"toolOptions": { },
"url": "https://testingbot.com",
"timestamp": "2026-05-13T12:00:00.000Z",
"passes": [ ],
"violations": [ ],
"incomplete": [ ],
"inapplicable": [ ]
}
-
violationsincludes the rules that were violated and need to be fixed. Each rule has animpact(minor,moderate,seriousorcritical),tagssuch aswcag2aaorbest-practice, and thenodes(elements) that failed it. -
passesthe rules that have passed successfully. -
incompletechecks axe-core could not decide, for example text on a background image. A person needs to review them. -
inapplicableno matching content was found for these rules.
An overview of all accessibility rules that will be checked can be found on A11Y rules overview.
Fail the build on violations
To use the scan as a check in CI, keep only the violations of WCAG A and AA rules and fail the test when there are any.
Best-practice findings (tagged best-practice only) are left out here; report them separately if you want to track them.
const assert = require('assert');
const WCAG_TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22a', 'wcag22aa'];
// Call from your test with the selenium-webdriver driver, after the page has loaded:
// await assertNoWcagViolations(driver);
async function assertNoWcagViolations(driver) {
const result = await driver.executeScript('tb:accessibility');
const failures = result.violations.filter((rule) =>
rule.tags.some((tag) => WCAG_TAGS.includes(tag))
);
const summary = failures
.map((rule) => `${rule.id} (${rule.impact}): ${rule.nodes.length} element(s) - ${rule.helpUrl}`)
.join('\n');
assert.strictEqual(failures.length, 0, `WCAG A/AA violations found:\n${summary}`);
}
WCAG_TAGS = {'wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22a', 'wcag22aa'}
result = driver.execute_script('tb:accessibility')
failures = [rule for rule in result['violations'] if WCAG_TAGS & set(rule['tags'])]
summary = '\n'.join(
f"{rule['id']} ({rule['impact']}): {len(rule['nodes'])} element(s) - {rule['helpUrl']}"
for rule in failures
)
assert not failures, f"WCAG A/AA violations found:\n{summary}"
To start with only the worst issues, also filter on the rule's impact, for example only serious and critical.
A passing check means no automated violations were found; see what automated checks don't catch.