Add a11y example (#260)

Author: bahmutov

README.md

@@ -164,6 +164,7 @@ We have several subfolders in [examples](examples) folder that have complete pro
 <!-- prettier-ignore-start -->
 Folder Name | Description
 --- | ---
+[a11y](examples/a11y) | Testing components' accessibility using [cypress-axe](https://github.com/avanslaars/cypress-axe)
 [react-scripts](examples/react-scripts) | A project using `react-scripts` with component tests in `src` folder
 [react-scripts-folder](examples/react-scripts-folder) | A project using `react-scripts` with component tests in `cypress/component`
 [tailwind](examples/tailwind) | Testing styles built using [Tailwind CSS](https://tailwindcss.com/)

circle.yml

@@ -31,6 +31,18 @@ workflows:
                 name: Build folder 🏗
                 command: npm run build
 
+      - cypress/run:
+          name: Example A11y
+          requires:
+            - Install
+          # each example installs "cypress-react-unit-test" as a local dependency (symlink)
+          install-command: npm install
+          verify-command: echo 'Already verified'
+          no-workspace: true
+          working_directory: examples/a11y
+          command: npm test
+          store_artifacts: true
+
       - cypress/run:
           name: Example Babel
           requires:
@@ -239,10 +251,11 @@ workflows:
           requires:
             - Install
             - Test
-            - Example Sass
+            - Example A11y
             - Example Babel
-            - Example React Scripts
             - Example Component Folder
+            - Example React Scripts
+            - Example Sass
             - Example Tailwind
             - Example Webpack options
             - Visual Sudoku

examples/a11y/.npmrc

@@ -0,0 +1 @@
+package-lock=false

examples/a11y/README.md

@@ -0,0 +1,30 @@
+# example: a11y
+
+> Testing component accessibility
+
+```shell
+npm install
+npm run cy:open
+# or just run headless tests
+npm test
+```
+
+Testing components following the [React accessibility guide](https://reactjs.org/docs/accessibility.html) using [cypress-axe](https://github.com/avanslaars/cypress-axe) plugin.
+
+See the spec file [cypress/component/spec.js](cypress/component/spec.js). For example, an `<input>` without a label is caught:
+
+```js
+mount(<input type="text" value="John Smith" name="name" />)
+cy.checkA11y('input', {
+  runOnly: {
+    type: 'tag',
+    values: ['wcag2a'],
+  },
+})
+```
+
+![Input without a label](images/missing-label.png)
+
+You can click on the error to see more details in the DevTools console
+
+![Error details](images/label-error.png)

examples/a11y/cypress.json

@@ -0,0 +1,7 @@
+{
+  "fixturesFolder": false,
+  "testFiles": "**/*spec.js",
+  "viewportWidth": 500,
+  "viewportHeight": 500,
+  "experimentalComponentTesting": true
+}

examples/a11y/cypress/component/spec.js

@@ -0,0 +1,42 @@
+/// <reference types="cypress" />
+import React from 'react'
+import { mount } from 'cypress-react-unit-test'
+
+describe('Accessibility', () => {
+  before(() => {
+    // https://github.com/avanslaars/cypress-axe
+    cy.injectAxe()
+  })
+
+  // https://www.w3.org/WAI/standards-guidelines/aria/
+  context('aria', () => {
+    // skip a failing test on purpose
+    it.skip('catches missing aria-* label', () => {
+      mount(<input type="text" value="John Smith" name="name" />)
+      cy.checkA11y('input', {
+        runOnly: {
+          type: 'tag',
+          values: ['wcag2a'],
+        },
+      })
+    })
+
+    it('passes', () => {
+      mount(
+        <input
+          type="text"
+          aria-label="label text"
+          aria-required="true"
+          value="John Smith"
+          name="name"
+        />,
+      )
+      cy.checkA11y('input', {
+        runOnly: {
+          type: 'tag',
+          values: ['wcag2a'],
+        },
+      })
+    })
+  })
+})

examples/a11y/cypress/integration/cy-spec.js

@@ -0,0 +1,6 @@
+/// <reference types="cypress" />
+describe('integration spec', () => {
+  it('works', () => {
+    expect(1).to.equal(1)
+  })
+})

examples/a11y/cypress/plugins/index.js

@@ -0,0 +1,9 @@
+// load file preprocessor that comes with this plugin
+// https://github.com/bahmutov/cypress-react-unit-test#install
+const preprocessor = require('cypress-react-unit-test/plugins/react-scripts')
+module.exports = (on, config) => {
+  preprocessor(on, config)
+  // IMPORTANT to return the config object
+  // with the any changed environment variables
+  return config
+}

examples/a11y/cypress/support/index.js

@@ -0,0 +1,2 @@
+require('cypress-react-unit-test/support')
+require('cypress-axe')