Call for Testing: wp-theme-auditor

Building on initial efforts at WCUS 2018 Contributor DayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of There are many teams that people can participate in, each with a different focus. in Nashville, the AccessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). ( Team has continued to move forward with the development of automated accessibility testing tools for WordPress themes. The work so far is available in the wp-theme-auditor GitHub repository, and the Accessibility Team is now seeking feedback from the broader WordPress community in order to make this tool as useful as possible.

wp-theme-auditor is a JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. package which includes end-to-end testing tools from the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. project and Deque Labs’ axe accessibility testing framework. It is meant to be installed as a development dependency in a WordPress theme, and includes a default set of test cases based on the Accessibility Team’s a11y-theme-unit-test-data. wp-theme-auditor can be run against a local development siteDevelopment Site You can keep a copy of your live site in a separate environment. Maintaining a development site is a good practice that can let you make any changes and test them without affecting the live/production environment. (remote sites are theoretically supported but untested).

You can install the tool by running the following command (if the theme to be tested does not already include a package.json file, you will need to create one first by running npm init -y):

npm install --save-dev wpaccessibility/wp-theme-auditor

Installing the dependency also runs a postinstall script which copies the required Babel and Jest configuration files to the theme directory and copies required test files (including the default test cases) to a test folder within the theme directory.

Two scripts must then be added to the theme’s package.json file:

  "scripts": {
    "create-test-cases": "create-test-cases",
    "test:axe": "wp-scripts test-e2e"

If you want to test your theme with these default test cases, you need to import a11y-theme-unit-test-data into your development site first. Then, running WP_BASE_URL=https://mytheme.test npm run test:axe (where the local development site URL is https://mytheme.test) will audit all the imported posts and pages using axe and provide detailed feedback about any violations. (The imported posts and pages from a11y-theme-unit-test-data have been crafted to ensure that content does not include any accessibility issues, so tests will catch accessibility issues in the theme itself rather than content.)

Running npm run test:axe will load any files which match the pattern test/*.test.js, so if you need to exclude any of the default test cases, you can move them out of the test folder.

The other script, create-test-cases, provides an interactive command line prompt for creating new test cases for custom post or page templates. For example, if your theme has a custom page template for a contact page and you want to make sure that your contact form passes axe tests, you can use the interactive prompt to specify the post type (post or page), slug, and label for that test:

npm run create-test-cases
Creating test cases...
? What is the post type? page
? What is the slug of the post or page? contact
? What is the title of the post or page? Contact
Test case created at /var/www/wp-content/themes/mytheme/test/contact.test.js.

Theme developers are encouraged to try wp-theme-auditor and share feedback via the project’s GitHub repository. Future goals for the tool include the ability to add it to themes using the wp-cli scaffold command and the ability to run tests in a Docker container as part of a continuous integration (CI) environment.

While all automated accessibility testing has limitations and there are many accessibility issues it cannot catch, wp-theme-auditor could be an exciting new tool to guide WordPress theme developers towards accessibility best practices.