README.md

@sa11y/wdio

Provides assertAccessible(), assertAccessibleSync() APIs that can be used with WebdriverIO to check accessibility of web pages rendered in browsers.

• Caution
• Usage
• Reference

Caution

• headless: Checks such as color contrast do not work in headless mode. In general executing tests in headless mode might yield different accessibility results. Hence, it is recommended to run accessibility checks in windowed mode when possible for accurate results.

Usage

import { assertAccessible, assertAccessibleSync } from '@sa11y/wdio';

describe('demonstrate usage of @sa11y/wdio', () => {
    it('should demonstrate usage of assertAccessible API', async () => {
        // Navigate to page to be tested
        await browser.url('pageToBeTested.html');
        // Check for accessibility of the loaded page
        await assertAccessible();
    });

    it('should demonstrate usage of assertAccessibleSync API', () => {
        return sync(() => {
            // Navigate to page to be tested
            browser.url('pageToBeTested.html');
            // Check for accessibility of the loaded page
            assertAccessibleSync();
        });
    });

    it('should demonstrate checking a11y of a selected element', async () => {
        // Navigate to page to be tested
        await browser.url('pageToBeTested.html');
        // Check accessibility of a particular element using https://webdriver.io/docs/selectors
        await assertAccessible({ scope: browser.$('selector') });
    });

    it('should demonstrate exception list', async () => {
        // Navigate to page to be tested
        await browser.url('pageToBeTested.html');
        // Exception list is a map of rule to corresponding css targets that needs to be filtered from a11y results
        const exceptions = {
            'document-title': ['html'],
            'link-name': ['a'],
        };
        // Check for accessibility of the loaded page, filtering out results from given exception list
        await assertAccessible({ exceptionList: exceptions });
    });
});

Options

An options object containing following properties can be passed to WDIO APIs

• driver - WDIO BrowserObject instance navigated to the page to be checked.
  • Created automatically by WDIO test runner.
  • Might need to be passed in explicitly when other test runners are used.
• scope - Element to check for accessibility found using browser.$(selector).
  • Defaults to the entire document.
• rules - @sa11y/preset-rules used for checking accessibility.
  • Defaults to base ruleset.
• exceptionList - map of rule id to corresponding CSS targets that needs to be filtered from results

Reference

• Sync mode vs async · WebdriverIO