• Intro
• How to use
  • Installation
  • Configuration
  • Usage
• Current rules
• Contributing
  • What's a rule anyway?
  • Proposing a new rule
  • ReactTestInstance
• Related Projects

The React Native ecosystem is massive but it's still lagging behind React Web when it comes to accessibility tools. As mobile developers, we're still braving the challenge of mapping robust, time-tested web guidelines into equally robust guidelines for mobile. In React Native, we also face the challenge of adhering to the accessibility guidelines of multiple platforms using only React Native's Accessibility API. There aren't many practical tutorials on the best use of this API, which means there are limited resources for React Native developers who want to make their apps more accessible. Indeed, there's still a lot of confusion about what makes an app accessible or what accessibility even is.

This project aims to make solving these problems a little easier.

• Create an engine capable of traversing a component tree making accessibility-related checks
• Create an app to showcase accessiblity best-practices
• Keep it open-source!

npm install react-native-accessibility-engine --save-dev
# or
yarn add react-native-accessibility-engine --dev

Add the custom toBeAccessible matcher to your Jest config's setupFilesAfterEnv array:

{
  ...
  "setupFilesAfterEnv": [..., "react-native-accessibility-engine/lib/commonjs/extend-expect"],
}

Alternately, if you have a Jest setup file, you could add the matcher there:

{
  ...
  "setupFilesAfterEnv": ["path/to/your/setup/file"],
}

// At the top of your setup file
import 'react-native-accessibility-engine/lib/commonjs/extend-expect';

import React from 'react';
import { Image, TouchableOpacity } from 'react-native';
import Icons from './assets';

const Button = () => (
  <TouchableOpacity accessible={false}>
    <Image source={Icons.filledHeart['32px']} />
  </TouchableOpacity>
);

it('should be accessible', () => {
  expect(<Button />)).toBeAccessible();
});

You can also pass test instances from react-test-renderer and @testing-library/react-native:

import React from 'react';
import { Image, TouchableOpacity } from 'react-native';

import TestRenderer, { ReactTestInstance } from 'react-test-renderer';
import { render } from '@testing-library/react-native';

import Icons from './assets';

const Button = () => (
  <TouchableOpacity accessible={false} accessibilityRole={'button'}>
    <Image source={Icons.filledHeart['32px']} />
  </TouchableOpacity>
);

it('should be accessible, using react-test-renderer', () => {
  const button = TestRenderer.create(<Button />).root;
  expect(button).toBeAccessible();
});

it('should be accessible, using @testing-library/react-native', () => {
  const { getByA11yRole } = render(<Test />);
  const button = getByA11yRole('button');
  expect(button).toBeAccessible();
});

RNAE is totally open to questions, sugestions, corrections, and community pull requests. Though the goal of this project is eventually to cover a wide variety of components and situations, that's still a work in progress. Feel free to suggest any rules you feel could be helpful. ✌️

Rules are objects that represent a single assertion on a component tree. Let's take the link-role-required rule, for example:

import { Text } from 'react-native';

const rule: Rule = {
  id: 'link-role-required',
  matcher: (node) => isText(node.type),
  assertion: (node) => {
    const { onPress, accessibilityRole } = node.props;
    if (onPress) {
      return accessibilityRole === 'link';
    }
    return true;
  },
  help: {
    problem:
      "The text is clickable, but the user wasn't informed that it behaves like a link",
    solution:
      "Set the 'accessibilityRole' prop to 'link' or remove the 'onPress' prop",
    link: '',
  },
};

First, we define an id, which doubles as the rule's name and should be as simple and self-explanatory as possible. It should also be unique, so take a look at the rules catalog to make sure it isn't already in use.

A matcher is a function that accepts a ReactTestInstance node and returns true or false.

• If you return true, that means that this node is relevant to the rule and should be tested using the assertion defined below.
• If you return false, the node will be ignored.

In our link-role-required example, we only want to test Text nodes.

An assertion is a function that accepts one of the nodes selected by the matcher function, tests for some condition, and returns true or false.

• If you return true, that means the condition is met and no error is thrown.
• If you return false, the assertion fails and the engine will eventually (after traversing the whole tree) throw an error with the data contained in the help field.

In our link-role-required example, we test the following:

- if the text component contains an onPress prop
  - return true if the accessibilityRole prop equals 'link'
  - return false otherwise
- return true otherwise

The help field is an object containing three fields: problem, solution, and link.

• The problem field is a one-sentence string explaining in simple, clear language why the assertion failed.
• The solution field is a one-sentence string explaining what the developer needs to do to correct the oversight.
• The link field is a link to support material.

Note: For now, most rules do not have a link.

Just clone the project, create your own branch off of main and get to work. 💪 Go into the src/rules directory and create a folder named with the ID of your rule. Inside this folder, create two files:

• index.ts (make sure the rule object is the default export)
• index.test.tsx

Every rule needs to be tested. If you need to define a helper, put it in the src/helper folder and remember to test that, too. Also remember to run all the code quality scripts before you open a PR.

yarn lint
yarn test
yarn typescript

For reference, this the type of the node object passed to the matcher and assertion functions.

export interface ReactTestInstance {
  instance: any;
  type: ElementType;
  props: { [propName: string]: any };
  parent: null | ReactTestInstance;
  children: Array<ReactTestInstance | string>;

  find(predicate: (node: ReactTestInstance) => boolean): ReactTestInstance;
  findByType(type: ElementType): ReactTestInstance;
  findByProps(props: { [propName: string]: any }): ReactTestInstance;

  findAll(
    predicate: (node: ReactTestInstance) => boolean,
    options?: { deep: boolean }
  ): ReactTestInstance[];
  findAllByType(
    type: ElementType,
    options?: { deep: boolean }
  ): ReactTestInstance[];
  findAllByProps(
    props: { [propName: string]: any },
    options?: { deep: boolean }
  ): ReactTestInstance[];
}

• eslint-plugin-react-native-a11y is an Eslint plugin that lints your components and accessibility-related props.
• axe-core is the project that inspired this one. It's a similiar accessbility engine made for HTML-based languages like React Web.
• storybook-addon-a11y is a Storybook add-on that uses Axe under the hood and allows you to inspect your components for accessibility problems as you develop them in Storybook.

MIT